rag-memory-epf-mcp 3.5.2 → 4.0.0

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/embeddingGate.d.ts

@@ -0,0 +1,68 @@
+export type ModelState = 'disabled' | 'idle' | 'loading' | 'downloading' | 'ready' | 'failed';
+export type EmbedPriority = 'interactive' | 'bulk' | 'backfill';
+export type EmbedFn = (text: string, dims: number, isQuery: boolean) => Promise<Float32Array>;
+export declare class GateDisabledError extends Error {
+    readonly code = "EMBEDDINGS_DISABLED";
+    readonly state = "disabled";
+    constructor();
+}
+export declare class GateNotReadyError extends Error {
+    readonly state: ModelState;
+    readonly retryAfterMs?: number | undefined;
+    readonly code = "MODEL_NOT_READY";
+    constructor(state: ModelState, retryAfterMs?: number | undefined);
+}
+export declare class TerminalConfigError extends Error {
+    readonly terminal = true;
+    constructor(message: string);
+}
+export interface GateOptions {
+    mode: 'lazy' | 'eager' | 'off';
+    loadModel: () => Promise<EmbedFn>;
+    onReady?: () => void;
+    onStateChange?: (s: ModelState) => void;
+    backoffMs?: number[];
+}
+export declare class EmbeddingGate {
+    private readonly opts;
+    private state;
+    private embedFn;
+    private startPromise;
+    private queue;
+    private running;
+    private seq;
+    private generation;
+    private shuttingDown;
+    private retryTimer;
+    private attempt;
+    private failedInputs;
+    private demotions;
+    private terminalFailure;
+    readonly abort: AbortController;
+    private readySince?;
+    private lastError?;
+    private retryAt?;
+    private readonly backoff;
+    constructor(opts: GateOptions);
+    get status(): {
+        state: ModelState;
+        readySince: string | undefined;
+        lastError: string | undefined;
+        retryAt: string | undefined;
+    };
+    get isReady(): boolean;
+    get isDisabled(): boolean;
+    private setState;
+    start(): Promise<void>;
+    markDownloading(): void;
+    private loadOnce;
+    private scheduleRetry;
+    embed(text: string, o: {
+        dims?: number;
+        isQuery?: boolean;
+        priority: EmbedPriority;
+    }): Promise<Float32Array>;
+    private pump;
+    get loadInFlight(): boolean;
+    shutdown(deadlineMs?: number): Promise<void>;
+}

package/dist/src/embeddingGate.js

@@ -0,0 +1,227 @@
+// v3.6 lite install (spec 2026-07-18 v5 §3): EmbeddingGate owns the embedding
+// model lifecycle — nothing else. State machine + single-flight load/retry +
+// prioritized serial inference queue. It does NOT touch the DB, backfill
+// policy, FTS SQL, or tool response shapes (A′ boundary).
+//
+// Consumers never read state and then call separately (TOCTOU): embed() decides
+// and executes inside one boundary, rejecting with typed errors when the model
+// is unavailable so each tool can honor its own not-ready contract.
+export class GateDisabledError extends Error {
+    code = 'EMBEDDINGS_DISABLED';
+    state = 'disabled';
+    constructor() {
+        super('Embeddings are disabled (RAG_MEMORY_EMBEDDINGS=off)');
+        this.name = 'GateDisabledError';
+    }
+}
+export class GateNotReadyError extends Error {
+    state;
+    retryAfterMs;
+    code = 'MODEL_NOT_READY';
+    constructor(state, retryAfterMs) {
+        super(`Embedding model not ready (state=${state})`);
+        this.state = state;
+        this.retryAfterMs = retryAfterMs;
+        this.name = 'GateNotReadyError';
+    }
+}
+// Configuration incompatibility (e.g. a non-1024-dim custom model): retrying or
+// quarantining the cache cannot fix it — the gate parks in terminal 'failed'
+// with no reload schedule (beta 2R B3).
+export class TerminalConfigError extends Error {
+    terminal = true;
+    constructor(message) {
+        super(message);
+        this.name = 'TerminalConfigError';
+    }
+}
+const PRIO = { interactive: 0, bulk: 1, backfill: 2 };
+const DEFAULT_BACKOFF_MS = [30_000, 120_000, 600_000, 3_600_000];
+export class EmbeddingGate {
+    opts;
+    state;
+    embedFn = null;
+    startPromise = null;
+    queue = [];
+    running = false;
+    seq = 0;
+    generation = 0;
+    shuttingDown = false;
+    retryTimer = null;
+    attempt = 0;
+    // Systemic-failure detector (beta 2R B4): DISTINCT failed inputs within the
+    // current load epoch (cleared on successful load AND on any inference
+    // success). Same-input retries are data-specific (poison row) and never
+    // demote. `demotions` escalates the reload backoff across repeated
+    // demote-reload cycles and only resets on a real inference success.
+    failedInputs = new Set();
+    demotions = 0;
+    terminalFailure = false;
+    abort = new AbortController(); // loader passes this to lock waits / fetches
+    readySince;
+    lastError;
+    retryAt;
+    backoff;
+    constructor(opts) {
+        this.opts = opts;
+        this.backoff = opts.backoffMs ?? DEFAULT_BACKOFF_MS;
+        this.state = opts.mode === 'off' ? 'disabled' : 'idle';
+    }
+    get status() {
+        return { state: this.state, readySince: this.readySince, lastError: this.lastError, retryAt: this.retryAt };
+    }
+    get isReady() { return this.state === 'ready'; }
+    get isDisabled() { return this.state === 'disabled'; }
+    setState(s) {
+        if (this.state !== s) {
+            this.state = s;
+            this.opts.onStateChange?.(s);
+        }
+    }
+    // Single-flight: concurrent calls share one load; after a failure the next
+    // scheduled retry (or explicit call) re-enters loadOnce.
+    start() {
+        if (this.state === 'disabled' || this.shuttingDown)
+            return Promise.resolve();
+        if (!this.startPromise)
+            this.startPromise = this.loadOnce();
+        return this.startPromise;
+    }
+    // loading -> downloading is reported by the loader via markDownloading().
+    markDownloading() {
+        if (this.state === 'loading')
+            this.setState('downloading');
+    }
+    async loadOnce() {
+        this.setState('loading');
+        try {
+            this.embedFn = await this.opts.loadModel();
+            this.attempt = 0;
+            this.retryAt = undefined;
+            this.lastError = undefined;
+            this.failedInputs.clear(); // fresh load epoch (beta 2R B4)
+            this.readySince = new Date().toISOString();
+            this.setState('ready');
+            this.opts.onReady?.();
+            this.pump();
+        }
+        catch (e) {
+            this.lastError = e instanceof Error ? e.message : String(e);
+            this.setState('failed');
+            this.startPromise = null;
+            if (e?.terminal === true) {
+                // Config incompatibility (beta 2R B3): retrying or quarantining cannot
+                // fix it — no reload schedule; a restart with a fixed config is the
+                // only recovery.
+                this.terminalFailure = true;
+                this.retryAt = undefined;
+                console.error(`❌ embeddings disabled for this run (config): ${this.lastError}`);
+                throw e;
+            }
+            this.scheduleRetry(this.attempt++);
+            throw e;
+        }
+    }
+    // Shared retry scheduler with jitter; escalation index picks the backoff slot.
+    scheduleRetry(escalation) {
+        if (this.shuttingDown || this.terminalFailure)
+            return;
+        const base = this.backoff[Math.min(escalation, this.backoff.length - 1)];
+        const delay = Math.round(base * (0.8 + Math.random() * 0.4)); // jitter ±20%
+        this.retryAt = new Date(Date.now() + delay).toISOString();
+        this.retryTimer = setTimeout(() => {
+            this.retryTimer = null;
+            void this.start().catch(() => { });
+        }, delay);
+        this.retryTimer.unref?.();
+    }
+    embed(text, o) {
+        if (this.state === 'disabled')
+            return Promise.reject(new GateDisabledError());
+        if (this.shuttingDown)
+            return Promise.reject(new GateNotReadyError(this.state));
+        if (this.state !== 'ready') {
+            const retryAfterMs = this.retryAt ? Math.max(0, Date.parse(this.retryAt) - Date.now()) : undefined;
+            return Promise.reject(new GateNotReadyError(this.state, retryAfterMs));
+        }
+        return new Promise((resolve, reject) => {
+            this.queue.push({
+                text, dims: o.dims ?? 1024, isQuery: o.isQuery ?? false,
+                prio: PRIO[o.priority], seq: this.seq++, gen: this.generation, resolve, reject,
+            });
+            this.queue.sort((a, b) => a.prio - b.prio || a.seq - b.seq);
+            this.pump();
+        });
+    }
+    pump() {
+        if (this.running || !this.embedFn)
+            return;
+        const job = this.queue.shift();
+        if (!job)
+            return;
+        this.running = true;
+        void this.embedFn(job.text, job.dims, job.isQuery)
+            .then(v => {
+            this.failedInputs.clear();
+            this.demotions = 0; // a real success resets escalation
+            if (job.gen === this.generation)
+                job.resolve(v);
+            else
+                job.reject(new Error('embedding discarded: gate shut down'));
+        })
+            .catch(e => {
+            // Systemic-failure detection (beta 2R B4): 3 DISTINCT failed inputs in
+            // this load epoch -> demote to failed + reload with ESCALATING backoff
+            // (demotions counter survives reloads; only an inference success
+            // resets it — so a persistently broken runtime backs off instead of
+            // hot-looping). Same-input repeats (A→A) and A→B→A count 2 distinct.
+            this.failedInputs.add(`${job.text}|${job.dims}|${job.isQuery}`);
+            if (this.failedInputs.size >= 3 && this.state === 'ready' && !this.shuttingDown) {
+                this.lastError = e instanceof Error ? e.message : String(e);
+                this.embedFn = null;
+                this.startPromise = null;
+                this.failedInputs.clear();
+                this.setState('failed');
+                this.scheduleRetry(this.demotions++);
+                for (const j of this.queue.splice(0))
+                    j.reject(new GateNotReadyError('failed'));
+            }
+            job.reject(e);
+        })
+            .finally(() => {
+            this.running = false;
+            this.pump();
+        });
+    }
+    // Was the load still in flight when shutdown settled? (index.ts uses this to
+    // decide whether a bounded exit is needed — see shutdownAll.)
+    get loadInFlight() {
+        return this.startPromise !== null && this.state !== 'ready' && this.state !== 'failed' && this.state !== 'disabled';
+    }
+    // Graceful shutdown (spec §3, beta B1): block new work, abort what we can
+    // (lock waits via this.abort), discard in-flight inference results via the
+    // generation token, clear retry timers, then wait (bounded) for BOTH the
+    // current inference and an in-flight model load to settle.
+    async shutdown(deadlineMs = 5000) {
+        this.shuttingDown = true;
+        this.generation++;
+        this.abort.abort();
+        if (this.retryTimer) {
+            clearTimeout(this.retryTimer);
+            this.retryTimer = null;
+        }
+        for (const j of this.queue.splice(0))
+            j.reject(new Error('gate shutdown'));
+        const deadline = Date.now() + deadlineMs;
+        if (this.startPromise) {
+            const remaining = () => Math.max(0, deadline - Date.now());
+            await Promise.race([
+                this.startPromise.catch(() => { }),
+                new Promise(r => setTimeout(r, remaining())),
+            ]);
+        }
+        while (this.running && Date.now() < deadline) {
+            await new Promise(r => setTimeout(r, 20));
+        }
+    }
+}

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,
@@ -570,5 +576,180 @@ export const migrations = [
             // No clean reversal: would need the original document content to recompute
             // UTF-16 indices, and we never recorded which chunks were touched. No-op.
         }
+    },
+    // v3.6 (spec 2026-07-18 lite-install v5 §6c): embedding provenance + narrowed FTS trigger.
+    // ADD COLUMN is guarded by PRAGMA table_info so re-runs are idempotent.
+    {
+        version: 12,
+        description: 'Embedding provenance (profiles, input_hash, provenance_state), backfill failures, narrowed chunks_fts_update trigger',
+        up: (db) => {
+            const hasCol = (table, col) => db.prepare(`PRAGMA table_info(${table})`).all().some(c => c.name === col);
+            for (const table of ['chunk_metadata', 'entity_embedding_metadata']) {
+                if (!hasCol(table, 'input_hash'))
+                    db.exec(`ALTER TABLE ${table} ADD COLUMN input_hash TEXT`);
+                if (!hasCol(table, 'profile_id'))
+                    db.exec(`ALTER TABLE ${table} ADD COLUMN profile_id INTEGER`);
+                if (!hasCol(table, 'provenance_state'))
+                    db.exec(`ALTER TABLE ${table} ADD COLUMN provenance_state TEXT`);
+            }
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS embedding_profiles (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          model_id TEXT NOT NULL,
+          revision TEXT NOT NULL,
+          dtype TEXT NOT NULL,
+          dims INTEGER NOT NULL,
+          pooling TEXT NOT NULL,
+          normalize INTEGER NOT NULL,
+          created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+          UNIQUE(model_id, revision, dtype, dims, pooling, normalize)
+        )
+      `);
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS embedding_backfill_failures (
+          kind TEXT NOT NULL,
+          target_id TEXT NOT NULL,
+          input_hash TEXT,
+          profile_id INTEGER,
+          attempts INTEGER NOT NULL DEFAULT 0,
+          last_error TEXT,
+          updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+          UNIQUE(kind, target_id)
+        )
+      `);
+            db.exec(`CREATE TABLE IF NOT EXISTS server_meta (key TEXT PRIMARY KEY, value TEXT)`);
+            // Narrow the broad AFTER UPDATE trigger (installed by v8) so provenance-only
+            // updates do not rewrite the FTS index (advisor 4R must-fix 1).
+            db.exec(`DROP TRIGGER IF EXISTS chunks_fts_update`);
+            db.exec(`
+        CREATE TRIGGER chunks_fts_update AFTER UPDATE OF text, chunk_id ON chunk_metadata BEGIN
+          INSERT INTO chunks_fts(chunks_fts, rowid, text, chunk_id)
+            VALUES ('delete', old.rowid, old.text, old.chunk_id);
+          INSERT INTO chunks_fts(rowid, text, chunk_id)
+            VALUES (new.rowid, new.text, new.chunk_id);
+        END
+      `);
+        },
+        down: (db) => {
+            // Restore the broad v8 trigger; drop v12 tables. Added columns are left in
+            // place (SQLite DROP COLUMN restrictions with dependent objects) — pre-v12
+            // code ignores unknown columns, so rollback stays safe (spec §8-4).
+            db.exec(`DROP TRIGGER IF EXISTS chunks_fts_update`);
+            db.exec(`
+        CREATE TRIGGER chunks_fts_update AFTER UPDATE ON chunk_metadata BEGIN
+          INSERT INTO chunks_fts(chunks_fts, rowid, text, chunk_id)
+            VALUES ('delete', old.rowid, old.text, old.chunk_id);
+          INSERT INTO chunks_fts(rowid, text, chunk_id)
+            VALUES (new.rowid, new.text, new.chunk_id);
+        END
+      `);
+            db.exec(`DROP TABLE IF EXISTS embedding_backfill_failures`);
+            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`);
+        }
     }
 ];