rag-memory-epf-mcp 3.5.2 → 4.0.0

package/dist/src/modelCache.d.ts

@@ -0,0 +1,33 @@
+export declare function resolveModelCacheDir(env: Record<string, string | undefined>, platform: string, homedir: string): string;
+export declare function preflightCacheDir(dir: string): {
+    ok: boolean;
+    error?: string;
+};
+export declare function artifactKey(modelId: string, revision: string, dtype: string): string;
+export declare class ModelDownloadLock {
+    readonly lockPath: string;
+    readonly markerPath: string;
+    private held;
+    constructor(cacheDir: string, key: string);
+    private tryAcquire;
+    private isStale;
+    private holderPid;
+    invalidateMarker(): void;
+    acquireOrWait(opts: {
+        pollMs?: number;
+        timeoutMs: number;
+        signal?: AbortSignal;
+    }): Promise<'owner' | 'ready'>;
+    markComplete(): void;
+    release(): void;
+}
+export declare function isCacheIntegrityError(e: unknown, cacheDir?: string): boolean;
+export declare function handleLoaderFailure(opts: {
+    role: 'owner' | 'ready';
+    error: unknown;
+    lock: ModelDownloadLock;
+    cacheDir: string;
+    modelId: string;
+    terminal: boolean;
+}): 'none' | 'marker-invalidated' | 'quarantined';
+export declare function quarantinePartialCache(cacheDir: string, modelId: string): void;

package/dist/src/modelCache.js

@@ -0,0 +1,235 @@
+// v3.6 lite install (spec 2026-07-18 v5 §7): version-independent model cache.
+// The transformers.js default cache lives INSIDE the package directory, which is
+// npx-slot scoped — every engine version bump re-downloads ~1.2GB. This module
+// resolves a user-level cache dir and provides a cross-process download lock so
+// concurrent MCP servers on one machine never write the same model concurrently
+// (transformers' FileCache.put is not atomic).
+//
+// Lock/marker keys use ONLY cache-artifact fields (model id, revision, dtype) —
+// never retrieval config (spec §6c layer 1).
+import { mkdirSync, writeFileSync, readFileSync, unlinkSync, existsSync, renameSync, rmSync, readdirSync } from 'node:fs';
+import { join, sep } from 'node:path';
+import { createHash } from 'node:crypto';
+export function resolveModelCacheDir(env, platform, homedir) {
+    if (env.RAG_MEMORY_MODEL_CACHE_DIR)
+        return env.RAG_MEMORY_MODEL_CACHE_DIR;
+    if (env.XDG_CACHE_HOME)
+        return join(env.XDG_CACHE_HOME, 'rag-memory-epf-mcp');
+    if (platform === 'darwin')
+        return join(homedir, 'Library', 'Caches', 'rag-memory-epf-mcp');
+    if (platform === 'win32' && env.LOCALAPPDATA)
+        return join(env.LOCALAPPDATA, 'rag-memory-epf-mcp');
+    return join(homedir, '.cache', 'rag-memory-epf-mcp');
+}
+// mkdir -p + write probe. On failure the caller must transition the gate to
+// `failed` — silently falling back to the package-internal cache is forbidden.
+export function preflightCacheDir(dir) {
+    try {
+        mkdirSync(dir, { recursive: true });
+        const probe = join(dir, `.write-probe-${process.pid}`);
+        writeFileSync(probe, 'ok');
+        unlinkSync(probe);
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+export function artifactKey(modelId, revision, dtype) {
+    return createHash('sha1').update(`${modelId}@${revision}#${dtype}`).digest('hex').slice(0, 12);
+}
+const STALE_LOCK_MS = 30 * 60_000;
+export class ModelDownloadLock {
+    lockPath;
+    markerPath;
+    held = false;
+    constructor(cacheDir, key) {
+        this.lockPath = join(cacheDir, `.download-${key}.lock`);
+        this.markerPath = join(cacheDir, `.complete-${key}`);
+    }
+    tryAcquire() {
+        try {
+            writeFileSync(this.lockPath, JSON.stringify({ pid: process.pid, startedAt: Date.now() }), { flag: 'wx' });
+            this.held = true;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // Stale = holder pid is dead or the lock is unreadable. A LIVE pid is never
+    // reclaimed by age alone (beta B5): a slow 1.2GB download has no heartbeat,
+    // so an mtime rule would mint a second concurrent owner — the exact failure
+    // this lock exists to prevent. A hung-but-alive holder instead surfaces as a
+    // waiter timeout -> gate 'failed' + backoff, with the lock path and holder
+    // pid in the error so an operator can verify and remove it manually (the
+    // recovery procedure lives in docs/UPDATING.md). No pid-reuse heuristic:
+    // there is no portable process-start identity to compare against (beta 2R).
+    isStale() {
+        try {
+            const info = JSON.parse(readFileSync(this.lockPath, 'utf-8'));
+            try {
+                process.kill(info.pid, 0);
+            }
+            catch {
+                return true;
+            } // pid dead
+            return false;
+        }
+        catch {
+            return true; // unreadable lock = stale
+        }
+    }
+    holderPid() {
+        try {
+            return JSON.parse(readFileSync(this.lockPath, 'utf-8')).pid;
+        }
+        catch {
+            return null;
+        }
+    }
+    // Corrupted-cache recovery (beta B5): a marker only proves a PAST verified
+    // load. When a marker-holder ('ready' role) later fails to load, the caller
+    // must invalidate the marker so the next attempt becomes a locked owner.
+    invalidateMarker() {
+        try {
+            unlinkSync(this.markerPath);
+        }
+        catch { /* already gone */ }
+    }
+    // (beta 4R M1) Quarantine decisions are made by ERROR CLASS, not by failure
+    // count — see isCacheIntegrityError below.
+    // Returns 'owner' (caller must download, then markComplete + release) or
+    // 'ready' (a completed, verified cache already exists). Async polling only —
+    // never blocks the event loop (spec §7 / 3R M14).
+    async acquireOrWait(opts) {
+        const poll = opts.pollMs ?? 500;
+        const deadline = Date.now() + opts.timeoutMs;
+        for (;;) {
+            // Abort FIRST (beta 2R B5): a shutdown-aborted waiter must never become
+            // an owner or report 'ready' and start a pipeline load.
+            if (opts.signal?.aborted)
+                throw new Error('model download lock wait aborted');
+            if (existsSync(this.markerPath))
+                return 'ready';
+            if (this.tryAcquire())
+                return 'owner';
+            if (this.isStale()) {
+                try {
+                    unlinkSync(this.lockPath);
+                }
+                catch { /* raced with another reclaimer */ }
+                continue;
+            }
+            if (Date.now() > deadline) {
+                throw new Error(`model download lock wait timed out — holder pid=${this.holderPid() ?? 'unknown'}, lock=${this.lockPath}. If that process is hung, verify and remove the lock file manually (see docs/UPDATING.md).`);
+            }
+            // Abortable sleep with symmetric listener cleanup (beta 3R M4): a
+            // 10-minute wait at 500ms polls must not accumulate ~1200 abort
+            // listeners on the shared shutdown signal.
+            await new Promise(resolve => {
+                const onAbort = () => { clearTimeout(t); resolve(); };
+                const t = setTimeout(() => {
+                    opts.signal?.removeEventListener('abort', onAbort);
+                    resolve();
+                }, poll);
+                opts.signal?.addEventListener('abort', onAbort, { once: true });
+            });
+        }
+    }
+    // Only call after a verified cache load — a memory-only load success without
+    // durable cache files must NOT produce a marker (3R M14).
+    markComplete() {
+        const tmp = `${this.markerPath}.tmp.${process.pid}`;
+        writeFileSync(tmp, new Date().toISOString());
+        renameSync(tmp, this.markerPath);
+    }
+    release() {
+        if (this.held) {
+            try {
+                unlinkSync(this.lockPath);
+            }
+            catch { /* already gone */ }
+            this.held = false;
+        }
+    }
+}
+// (beta 4R M1 -> 5R M2) Error classification for cache handling: ONLY strong
+// serialization/truncation/corruption signatures justify quarantining a 1.2GB
+// cache. Generic words (parse, invalid model, byte length) and bare ENOENT
+// match far too much outside the cache — ENOENT counts only when the message
+// points INSIDE the model cache directory. OOM / allocation / network errors
+// preserve the cache regardless of repetition. Residual risk (documented): a
+// corruption with no matching signature stays put; docs/UPDATING.md tells the
+// operator to delete the model cache directory manually.
+const CACHE_INTEGRITY_SIGNATURES = [
+    /protobuf/i, /corrupt/i, /unexpected end/i, /deseriali[sz]e/i,
+    /magic number/i, /truncated/i, /checksum/i,
+];
+const CACHE_PRESERVE_SIGNATURES = [
+    /out of memory/i, /bad_alloc/i, /allocation/i, /OOM/i, /ETIMEDOUT/, /ECONNRESET/, /fetch/i, /network/i,
+];
+export function isCacheIntegrityError(e, cacheDir) {
+    const msg = e instanceof Error ? `${e.name}: ${e.message}` : String(e);
+    if (CACHE_PRESERVE_SIGNATURES.some(re => re.test(msg)))
+        return false;
+    if (CACHE_INTEGRITY_SIGNATURES.some(re => re.test(msg)))
+        return true;
+    // Missing-file errors are integrity ONLY when they point INSIDE the cache
+    // dir (path-boundary-safe: '/cache' must not match '/cache-old' — 6R note).
+    if (cacheDir && (/ENOENT/.test(msg) || /no such file/i.test(msg))
+        && (msg.includes(cacheDir + sep) || msg.includes(cacheDir + '/')))
+        return true;
+    return false;
+}
+// (beta 5R M1) Loader-failure cache policy, extracted for unit testing.
+// Quarantine requires EXCLUSIVITY: only the lock-holding OWNER may rename or
+// delete shared cache files — a ready-role process (no lock) racing other
+// readers must never touch the directory; it only drops the marker so the
+// next retry becomes a locked owner and re-proves the same integrity error
+// before any destructive action.
+export function handleLoaderFailure(opts) {
+    if (opts.terminal)
+        return 'none'; // config error: cache is fine
+    if (!isCacheIntegrityError(opts.error, opts.cacheDir)) {
+        // OOM / network / unknown: preserve everything (marker included — a
+        // transient error does not disprove a verified cache).
+        return 'none';
+    }
+    if (opts.role === 'ready') {
+        opts.lock.invalidateMarker();
+        return 'marker-invalidated';
+    }
+    opts.lock.invalidateMarker();
+    quarantinePartialCache(opts.cacheDir, opts.modelId);
+    return 'quarantined';
+}
+// Owner-side failure handling: partially downloaded model dirs are quarantined
+// (renamed aside) rather than left in place, so the next attempt starts clean.
+// transformers.js FileCache keys are `<org>/<model>/...` — the on-disk layout
+// nests the model id's path segments under cacheDir (beta B5: a flattened
+// `org_model` path would miss the real files entirely).
+export function quarantinePartialCache(cacheDir, modelId) {
+    const dir = join(cacheDir, ...modelId.split('/'));
+    if (existsSync(dir)) {
+        try {
+            renameSync(dir, `${dir}.quarantine.${Date.now()}`);
+        }
+        catch {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    }
+    // Retention (beta 2R B3): keep only the newest quarantine — repeated failures
+    // must not accumulate 1.2GB directories.
+    try {
+        const parent = join(cacheDir, ...modelId.split('/').slice(0, -1));
+        const leaf = modelId.split('/').pop();
+        const quarantines = readdirSync(parent)
+            .filter(f => f.startsWith(`${leaf}.quarantine.`))
+            .sort();
+        for (const old of quarantines.slice(0, -1)) {
+            rmSync(join(parent, old), { recursive: true, force: true });
+        }
+    }
+    catch { /* parent may not exist */ }
+}

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

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