@n2world/orchestrator 1.1.0

package/dist/pglite-hnsw-bridge.js

@@ -0,0 +1,311 @@
+"use strict";
+// ============================================================================
+// P1.5 — PgliteHnswSyncBridge + DurabilitySpec (계획서 v2.4 §4.3)
+//   ack-after-WAL · epoch(RCU) HNSW 더블버퍼 · 검색/삽입 분리 · torn-read 차단
+// ----------------------------------------------------------------------------
+// 단순화 원칙: v1.2 wal-buffer(SQLiteWalBuffer)와 P1 PgliteVectorStore 를 **재사용**하고,
+//             신규는 **HNSW 더블버퍼(epoch 회수)** 만 추가한다.
+//
+// DurabilitySpec(3대 표기, 전부 측정값):
+//   1) `ack 유실 0/N`     — ack 는 WAL durable append 직후 반환. 크래시 후 WAL 재생으로 복구.
+//   2) `torn-read 0/N`    — 인덱스 교체는 원자 swap. 리더는 캡처한 버퍼 참조로만 검색(세대 일관 스냅샷).
+//   3) `임베딩 stale ≤ W` — insert → publish(검색 가시화) 윈도우 W 를 실측(0/즉시성 주장 없음).
+//
+// 메모리 비용: epoch 더블버퍼는 active + (리더가 남은) retired 버퍼를 동시 보유 → **메모리 ~2배**.
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PgliteHnswSyncBridge = void 0;
+const core_1 = require("@n2world/core");
+const pglite_store_1 = require("./pglite-store");
+const wal_buffer_1 = require("./wal-buffer");
+const now = () => {
+    const g = globalThis;
+    return typeof g.performance?.now === 'function' ? g.performance.now() : Date.now();
+};
+/**
+ * PGLite(영속) ↔ HNSW(검색) 동기화 브리지.
+ * - 쓰기: WAL durable append(ack) → PGLite 적용 → WAL ack(삭제) → (옵션) publish.
+ * - 읽기: active 버퍼 참조를 캡처(epoch guard)해 검색 — 삽입에 막히지 않음(분리).
+ * - 교체: 새 인덱스를 빌드 후 원자 swap, 구 버퍼는 리더가 빠질 때 epoch 회수(RCU).
+ */
+class PgliteHnswSyncBridge {
+    storeDir;
+    walPath;
+    store;
+    wal;
+    // 빠른 재빌드를 위한 인메모리 권위 사본(id→embedding). PGLite 가 durable 원본.
+    items = new Map();
+    // ── epoch(RCU) 더블버퍼 상태 ──
+    activeIndex;
+    activeEpoch = 0;
+    /** epoch → 활성 리더 수(active/retired 공통). */
+    readers = new Map();
+    /** 회수 대기 중인 구 버퍼(리더가 남아 아직 못 버림). epoch → index. */
+    retired = new Map();
+    /** 세대별 멤버십(torn-read 검증용): epoch → 그 세대에 보였던 id 집합. */
+    genIds = new Map();
+    // ── 측정 카운터(전부 실측, 스텁 금지) ──
+    ackedWrites = 0;
+    tornReadObserved = 0;
+    reclaimedBuffers = 0;
+    unsafeReclaimAttempts = 0;
+    peakLiveBuffers = 1;
+    staleSamplesMs = [];
+    /** publish 안 된(가시화 대기) 쓰기의 삽입 시각. id→t. */
+    pendingSince = new Map();
+    initialized = false;
+    constructor(storeDir, walPath) {
+        this.storeDir = storeDir;
+        this.walPath = walPath;
+        this.store = new pglite_store_1.PgliteVectorStore(storeDir);
+        this.wal = new wal_buffer_1.SQLiteWalBuffer(walPath);
+        this.activeIndex = new core_1.HnswIndex();
+        this.genIds.set(0, new Set());
+    }
+    async init() {
+        if (this.initialized)
+            return;
+        await this.store.init();
+        await this.wal.init();
+        // 시작 시 durable 원본(PGLite)에서 인메모리 사본·인덱스 복원.
+        const all = await this.store.all();
+        for (const r of all)
+            this.items.set(r.id, r.embedding);
+        this.rebuildAndSwap(); // 초기 publish(epoch 0→1)
+        this.initialized = true;
+    }
+    storeMode() {
+        return this.store.mode_();
+    }
+    /**
+     * 벡터 쓰기. **ack 는 WAL durable append 직후 반환된다**(인메모리 직후 아님).
+     * 반환 시점 = 내구 보장 시점. 이후 PGLite 적용·publish.
+     */
+    async insert(w, opts = {}) {
+        if (!this.initialized)
+            await this.init();
+        const tInsert = now();
+        // (1) WAL durable append — 여기서 내구성이 확정되고 ack 가 정당화된다.
+        await this.wal.pushMessage('vec', JSON.stringify(w));
+        this.ackedWrites += 1;
+        // 테스트: ack 후 적용 전 크래시 모사 — WAL 에만 남기고 반환(미적용).
+        if (opts.simulateCrashBeforeApply) {
+            return { acked: true };
+        }
+        // (2) PGLite(durable) 적용 + 인메모리 사본 갱신.
+        await this.applyWrite(w);
+        // (3) 적용 완료 → 해당 WAL 항목 ack(삭제). WAL 은 in-flight 만 보유한다.
+        await this.ackApplied(w.id);
+        // (4) 가시화: publish 면 즉시 swap, 아니면 stale 로 둔다(W 측정 대상).
+        this.pendingSince.set(w.id, tInsert);
+        if (opts.publish !== false) {
+            this.publish();
+        }
+        return { acked: true };
+    }
+    /** WAL 의 in-flight 항목을 PGLite 에 재생(크래시 복구). 복구된 건수 반환. */
+    async recover() {
+        if (!this.initialized)
+            await this.init();
+        const pending = await this.wal.peekMessages();
+        let recovered = 0;
+        const ackIds = [];
+        for (const m of pending) {
+            try {
+                const w = JSON.parse(m.content);
+                if (!this.items.has(w.id)) {
+                    await this.applyWrite(w);
+                    recovered += 1;
+                }
+                if (m.id !== undefined)
+                    ackIds.push(m.id);
+            }
+            catch {
+                /* 손상 항목은 건너뜀(다음 단계에서 별도 격리 가능) */
+            }
+        }
+        await this.wal.ackMessages(ackIds);
+        this.publish();
+        return recovered;
+    }
+    /**
+     * 검색. active 버퍼 참조를 epoch 가드로 캡처해 **동기** 검색한다.
+     * 캡처한 참조는 검색 동안 불변 → 부분/혼합 세대(torn-read) 불가.
+     */
+    async search(query, k = 5) {
+        if (!this.initialized)
+            await this.init();
+        const g = this.acquireRead();
+        try {
+            return this.snapshotSearch(g, query, k);
+        }
+        finally {
+            this.releaseRead(g);
+        }
+    }
+    /**
+     * P2 인계 — 안정적 읽기 스냅샷 인터페이스. `openSnapshot()` → `snapshotSearch()`* → `closeSnapshot()`.
+     * 스냅샷이 열려 있는 동안 그 세대(epoch) 버퍼는 RCU 로 보호되어 회수되지 않는다(관계 추출 등
+     * 다단계 읽기가 일관된 단일 세대 위에서 동작하도록 보장). 닫으면 회수 가능해진다.
+     */
+    openSnapshot() {
+        return this.acquireRead();
+    }
+    /** 스냅샷 안의 검색(동기). 결과는 캡처한 세대의 멤버여야 한다 — 아니면 torn-read 로 카운트. */
+    snapshotSearch(g, query, k = 5) {
+        const results = g.index.search(query, k);
+        const gen = this.genIds.get(g.epoch);
+        if (gen) {
+            for (const id of results) {
+                if (!gen.has(id)) {
+                    this.tornReadObserved += 1;
+                    break;
+                }
+            }
+        }
+        return results;
+    }
+    closeSnapshot(g) {
+        this.releaseRead(g);
+    }
+    /** 가시화: 인메모리 사본으로 새 인덱스를 빌드해 원자 swap(검색 경로를 막지 않음). */
+    publish() {
+        this.rebuildAndSwap();
+        // 가시화된 쓰기의 stale 윈도우(insert→publish) 확정.
+        const tVisible = now();
+        for (const [, tIns] of this.pendingSince) {
+            this.staleSamplesMs.push(tVisible - tIns);
+        }
+        this.pendingSince.clear();
+    }
+    durability() {
+        return {
+            storeMode: this.store.mode_(),
+            ackedWrites: this.ackedWrites,
+            tornReadObserved: this.tornReadObserved,
+            reclaimedBuffers: this.reclaimedBuffers,
+            unsafeReclaimAttempts: this.unsafeReclaimAttempts,
+            peakLiveBuffers: this.peakLiveBuffers,
+            staleWindowMs: this.staleSamplesMs.length
+                ? +Math.max(...this.staleSamplesMs).toFixed(3)
+                : 0,
+        };
+    }
+    async count() {
+        if (!this.initialized)
+            await this.init();
+        return this.items.size;
+    }
+    /**
+     * 내구성 실측: ack 반환된 id 들이 **durable PGLite 원본**에 실제로 존재하는지 확인한다.
+     * `ack 유실 0/N` 은 이 검증의 missing.length === 0 으로 증명한다(스텁 아님 — 원본 조회).
+     */
+    async verifyDurable(expectedIds) {
+        if (!this.initialized)
+            await this.init();
+        const missing = [];
+        let present = 0;
+        for (const id of expectedIds) {
+            const rec = await this.store.get(id);
+            if (rec)
+                present += 1;
+            else
+                missing.push(id);
+        }
+        return { present, missing };
+    }
+    async close() {
+        await this.store.close();
+        await this.wal.close();
+        this.initialized = false;
+    }
+    // ────────────────────────────────────────────────────────────────────────
+    // 내부
+    // ────────────────────────────────────────────────────────────────────────
+    async applyWrite(w) {
+        await this.store.upsert(w.id, w.content, w.embedding);
+        this.items.set(w.id, w.embedding.slice());
+    }
+    /** 적용 완료된 id 의 WAL 항목을 ack(삭제). */
+    async ackApplied(id) {
+        const pending = await this.wal.peekMessages();
+        const ackIds = [];
+        for (const m of pending) {
+            try {
+                const w = JSON.parse(m.content);
+                if (w.id === id && m.id !== undefined)
+                    ackIds.push(m.id);
+            }
+            catch {
+                /* skip */
+            }
+        }
+        if (ackIds.length)
+            await this.wal.ackMessages(ackIds);
+    }
+    /** 인메모리 사본으로 새 인덱스를 빌드하고 원자 swap + 구 버퍼 retire(RCU). */
+    rebuildAndSwap() {
+        const next = new core_1.HnswIndex();
+        const ids = new Set();
+        for (const [id, emb] of this.items) {
+            next.addItem(id, emb);
+            ids.add(id);
+        }
+        const oldEpoch = this.activeEpoch;
+        const oldIndex = this.activeIndex;
+        // 원자 swap: 단일 대입(JS 단일 스레드 — 이벤트 루프 틱 사이 분할 없음).
+        this.activeIndex = next;
+        this.activeEpoch = oldEpoch + 1;
+        this.genIds.set(this.activeEpoch, ids);
+        // 구 버퍼 retire: 리더가 없으면 즉시 회수, 있으면 회수 대기.
+        if ((this.readers.get(oldEpoch) ?? 0) > 0) {
+            this.retired.set(oldEpoch, oldIndex);
+        }
+        else {
+            this.safeReclaim(oldEpoch); // 리더 0 → 즉시 회수(빈 초기 버퍼 포함)
+        }
+        this.trackPeakBuffers();
+    }
+    /**
+     * RCU 회수 — **리더가 0 인 epoch 만** 버퍼/세대를 회수한다.
+     * 리더가 남았는데 호출되면 회수하지 않고 위반으로 카운트한다(불변식 가드).
+     */
+    safeReclaim(epoch) {
+        if ((this.readers.get(epoch) ?? 0) > 0) {
+            this.unsafeReclaimAttempts += 1;
+            return;
+        }
+        this.retired.delete(epoch);
+        this.genIds.delete(epoch);
+        this.reclaimedBuffers += 1;
+    }
+    acquireRead() {
+        const epoch = this.activeEpoch;
+        this.readers.set(epoch, (this.readers.get(epoch) ?? 0) + 1);
+        return { index: this.activeIndex, epoch };
+    }
+    releaseRead(g) {
+        const n = (this.readers.get(g.epoch) ?? 1) - 1;
+        if (n <= 0) {
+            this.readers.delete(g.epoch);
+            // 이 epoch 가 retired 면(이미 swap 됨) 이제 리더 0 → 안전하게 회수.
+            if (this.retired.has(g.epoch))
+                this.safeReclaim(g.epoch);
+        }
+        else {
+            this.readers.set(g.epoch, n);
+        }
+    }
+    trackPeakBuffers() {
+        // 동시 보유 = active(1) + retired(회수 대기) 수.
+        const live = 1 + this.retired.size;
+        if (live > this.peakLiveBuffers)
+            this.peakLiveBuffers = live;
+        // RCU 불변식: retired 버퍼는 리더가 남았을 때만 존재해야 한다(리더 0 이면 회수 누락 → 정리).
+        for (const epoch of [...this.retired.keys()]) {
+            if ((this.readers.get(epoch) ?? 0) === 0)
+                this.safeReclaim(epoch);
+        }
+    }
+}
+exports.PgliteHnswSyncBridge = PgliteHnswSyncBridge;

package/dist/pglite-store.d.ts

@@ -0,0 +1,59 @@
+export interface VectorRecord {
+    id: string;
+    content: string;
+    embedding: number[];
+    updatedAt: number;
+}
+export interface SearchHit {
+    id: string;
+    content: string;
+    score: number;
+}
+export type StoreMode = 'pglite-durable' | 'pglite-memory' | 'fallback-memory';
+export interface StoreStats {
+    mode: StoreMode;
+    count: number;
+    /** 경계-staleness 헤드라인: 임베딩 갱신→검색가능 윈도우의 최댓값(측정값, ms). 0/즉시성 주장 아님. */
+    staleWindowMs: number;
+    staleMeanMs: number;
+    staleSamples: number;
+}
+/**
+ * PGLite 기반 영속 벡터 저장. 공개 API 는 비동기(WASM 부팅·디스크 I/O 때문).
+ * - `dataDir` 지정 → 파일 백업(durable, 프로세스 재시작 후에도 잔존).
+ * - `dataDir` 생략 → 인메모리 pglite(비영속).
+ * - pglite 부팅 실패 → 인메모리 Map 폴백(비-Linux/제약 환경에서도 동작 보장).
+ */
+export declare class PgliteVectorStore {
+    private readonly dataDir?;
+    private db;
+    private fallback;
+    private mode;
+    private initialized;
+    private staleSamplesMs;
+    constructor(dataDir?: string | undefined);
+    init(): Promise<void>;
+    mode_(): StoreMode;
+    /**
+     * 벡터 upsert(영속 쓰기). 쓰기 완료 후 **즉시 read-back** 으로 가시성을 확인하고
+     * (갱신 시작 → 검색가능)까지의 윈도우를 실측해 staleness 샘플로 적재한다.
+     */
+    upsert(id: string, content: string, embedding: number[]): Promise<void>;
+    /** id 로 단건 조회. 없으면 null. */
+    get(id: string): Promise<VectorRecord | null>;
+    /**
+     * 코사인 유사도 상위 k 검색. pgvector ANN 이 아니라 **TS 선형 스캔**(정직: O(N)).
+     * 작은 스킬 라이브러리 규모에서 정확·충분하며, 가짜 색인을 흉내내지 않는다.
+     */
+    search(queryEmbedding: number[], k?: number): Promise<SearchHit[]>;
+    /** 전체 레코드. */
+    all(): Promise<VectorRecord[]>;
+    count(): Promise<number>;
+    /**
+     * 경계-staleness 헤드라인 값(측정값, ms): 갱신→검색가능 윈도우의 최댓값.
+     * 표기 규약: `임베딩 stale 윈도우 ≤ W (측정값)`. **0/즉시성 주장 금지.**
+     */
+    staleWindowMs(): number;
+    stats(): StoreStats;
+    close(): Promise<void>;
+}

package/dist/pglite-store.js

@@ -0,0 +1,180 @@
+"use strict";
+// ============================================================================
+// P1 — PGLite 영속 벡터 저장 + 단일 경계-staleness 임베딩 (계획서 v2.4 §3·§4.3)
+// ----------------------------------------------------------------------------
+// 정직 고지(제1계명·구현강도 상한):
+//  1) 이 pglite 빌드(0.5.3)에는 pgvector 확장이 없다(contrib 부재 확인). 따라서 ANN을
+//     pgvector로 한다고 연기(mock)하지 않는다. PGLite 는 **영속 저장 계층**으로 쓰고,
+//     최근접 랭킹은 TS 코사인(O(N) 선형 스캔)으로 한다 — 작은 스킬 라이브러리에 정직한 선택.
+//  2) **2-속도(TwoSpeed) 일관성 기계장치를 추가하지 않는다**(단순화 영가설). 단일 경계-
+//     staleness 모델: 임베딩 갱신→검색가능까지의 윈도우 W 를 **실측**하고, "0/즉시성"을
+//     주장하지 않는다. (Karpathy: 0 staleness 는 키워드 검색뿐. 의미(임베딩) 검색은 본질적 stale.)
+//  3) durable 모드 = 파일 백업(`dataDir` 지정). 인메모리 모드는 비영속임을 명시한다.
+//     pglite 부팅 실패(폴백 환경) 시 인메모리 Map 으로 폴백하되 모드를 정직히 보고한다.
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PgliteVectorStore = void 0;
+const text_embedding_1 = require("./text-embedding");
+// ts-jest(CJS 트랜스파일) 환경에서도 ESM 전용 pglite 를 **진짜** dynamic import 하기 위한 우회.
+// (tsc/ts-jest 가 import() 를 require() 로 바꾸면 ERR_REQUIRE_ESM 이 난다. Function 으로 감싸 회피.)
+const esmImport = new Function('spec', 'return import(spec)');
+/**
+ * PGLite 기반 영속 벡터 저장. 공개 API 는 비동기(WASM 부팅·디스크 I/O 때문).
+ * - `dataDir` 지정 → 파일 백업(durable, 프로세스 재시작 후에도 잔존).
+ * - `dataDir` 생략 → 인메모리 pglite(비영속).
+ * - pglite 부팅 실패 → 인메모리 Map 폴백(비-Linux/제약 환경에서도 동작 보장).
+ */
+class PgliteVectorStore {
+    dataDir;
+    db = null;
+    fallback = new Map();
+    mode = 'fallback-memory';
+    initialized = false;
+    // 경계-staleness 실측(갱신→검색가능 윈도우, ms). 가짜 난수 금지 — 전부 실측.
+    staleSamplesMs = [];
+    constructor(dataDir) {
+        this.dataDir = dataDir;
+    }
+    async init() {
+        if (this.initialized)
+            return;
+        try {
+            const mod = await esmImport('@electric-sql/pglite');
+            const PGlite = mod.PGlite ?? mod.default?.PGlite ?? mod.default;
+            this.db = this.dataDir ? new PGlite(this.dataDir) : new PGlite();
+            await this.db.waitReady;
+            await this.db.exec(`
+        CREATE TABLE IF NOT EXISTS skill_vectors (
+          id          TEXT PRIMARY KEY,
+          content     TEXT NOT NULL,
+          embedding   TEXT NOT NULL,          -- JSON float[] (pgvector 부재 → TEXT 직렬화)
+          updated_at  DOUBLE PRECISION NOT NULL
+        );
+      `);
+            this.mode = this.dataDir ? 'pglite-durable' : 'pglite-memory';
+        }
+        catch (_e) {
+            // pglite 부팅 불가 환경(WASM 미지원 등) → 인메모리 Map 폴백. 모드를 숨기지 않는다.
+            this.db = null;
+            this.mode = 'fallback-memory';
+        }
+        this.initialized = true;
+    }
+    mode_() {
+        return this.mode;
+    }
+    /**
+     * 벡터 upsert(영속 쓰기). 쓰기 완료 후 **즉시 read-back** 으로 가시성을 확인하고
+     * (갱신 시작 → 검색가능)까지의 윈도우를 실측해 staleness 샘플로 적재한다.
+     */
+    async upsert(id, content, embedding) {
+        if (!this.initialized)
+            await this.init();
+        const t0 = nowMs();
+        const updatedAt = Date.now();
+        const embJson = JSON.stringify(embedding);
+        if (this.db) {
+            await this.db.query(`INSERT INTO skill_vectors (id, content, embedding, updated_at)
+         VALUES ($1, $2, $3, $4)
+         ON CONFLICT (id) DO UPDATE SET content = $2, embedding = $3, updated_at = $4;`, [id, content, embJson, updatedAt]);
+            // read-after-write: 방금 쓴 행이 조회 경로에서 보이는 순간까지의 실제 지연 측정.
+            await this.db.query(`SELECT id FROM skill_vectors WHERE id = $1;`, [id]);
+        }
+        else {
+            this.fallback.set(id, { id, content, embedding: embedding.slice(), updatedAt });
+        }
+        this.staleSamplesMs.push(nowMs() - t0);
+    }
+    /** id 로 단건 조회. 없으면 null. */
+    async get(id) {
+        if (!this.initialized)
+            await this.init();
+        if (this.db) {
+            const r = await this.db.query(`SELECT id, content, embedding, updated_at FROM skill_vectors WHERE id = $1;`, [id]);
+            if (r.rows.length === 0)
+                return null;
+            return rowToRecord(r.rows[0]);
+        }
+        return this.fallback.get(id) ?? null;
+    }
+    /**
+     * 코사인 유사도 상위 k 검색. pgvector ANN 이 아니라 **TS 선형 스캔**(정직: O(N)).
+     * 작은 스킬 라이브러리 규모에서 정확·충분하며, 가짜 색인을 흉내내지 않는다.
+     */
+    async search(queryEmbedding, k = 5) {
+        if (!this.initialized)
+            await this.init();
+        const records = await this.all();
+        const hits = records.map((rec) => ({
+            id: rec.id,
+            content: rec.content,
+            score: (0, text_embedding_1.cosineSimilarity)(rec.embedding, queryEmbedding),
+        }));
+        hits.sort((a, b) => b.score - a.score);
+        return hits.slice(0, Math.max(0, k));
+    }
+    /** 전체 레코드. */
+    async all() {
+        if (!this.initialized)
+            await this.init();
+        if (this.db) {
+            const r = await this.db.query(`SELECT id, content, embedding, updated_at FROM skill_vectors;`);
+            return r.rows.map(rowToRecord);
+        }
+        return [...this.fallback.values()];
+    }
+    async count() {
+        if (!this.initialized)
+            await this.init();
+        if (this.db) {
+            const r = await this.db.query(`SELECT COUNT(*)::int AS n FROM skill_vectors;`);
+            return Number(r.rows[0]?.n ?? 0);
+        }
+        return this.fallback.size;
+    }
+    /**
+     * 경계-staleness 헤드라인 값(측정값, ms): 갱신→검색가능 윈도우의 최댓값.
+     * 표기 규약: `임베딩 stale 윈도우 ≤ W (측정값)`. **0/즉시성 주장 금지.**
+     */
+    staleWindowMs() {
+        return this.staleSamplesMs.length ? Math.max(...this.staleSamplesMs) : 0;
+    }
+    stats() {
+        const n = this.staleSamplesMs.length;
+        const mean = n ? this.staleSamplesMs.reduce((a, b) => a + b, 0) / n : 0;
+        return {
+            mode: this.mode,
+            count: this.db ? -1 : this.fallback.size, // db 카운트는 비동기 count() 사용
+            staleWindowMs: +this.staleWindowMs().toFixed(3),
+            staleMeanMs: +mean.toFixed(3),
+            staleSamples: n,
+        };
+    }
+    async close() {
+        if (this.db) {
+            try {
+                await this.db.close();
+            }
+            catch (_e) {
+                /* 폐기 중 오류는 무시 */
+            }
+            this.db = null;
+        }
+        this.initialized = false;
+    }
+}
+exports.PgliteVectorStore = PgliteVectorStore;
+function rowToRecord(row) {
+    return {
+        id: String(row.id),
+        content: String(row.content),
+        embedding: JSON.parse(String(row.embedding)),
+        updatedAt: Number(row.updated_at),
+    };
+}
+// 고해상도 시계(있으면 performance.now, 없으면 Date.now). staleness 실측용.
+function nowMs() {
+    // Node 의 perf_hooks 가 항상 있으나, 환경 방어를 위해 가드.
+    const g = globalThis;
+    return typeof g.performance?.now === 'function' ? g.performance.now() : Date.now();
+}

package/dist/playbook.d.ts

@@ -0,0 +1,79 @@
+import { Tier } from './tier-classifier';
+import { GovernedAgent } from './governed-llm';
+export type FieldTier = 'pii' | 'sensitive' | 'public';
+export interface PlaybookField {
+    key: string;
+    label: string;
+    required: boolean;
+    tier: FieldTier;
+}
+export interface CrossCheckContext<R = any> {
+    record: R;
+    store: RecordStore<R>;
+}
+export interface CrossCheckRule<R = any> {
+    id: string;
+    /** null=통과. {severity:'block'}=차단, 'warn'=경고(사람 확인). */
+    check: (ctx: CrossCheckContext<R>) => null | {
+        flag: string;
+        severity: 'block' | 'warn';
+    };
+}
+/** LLM 산출 단계(예: 요약·안내문). tier 로 로컬/빠른경로를 가른다. */
+export interface PlaybookLlmStep {
+    id: string;
+    /** 'pii' → 로컬 강제(Tier-0). 'public' → 빠른 경로(외부 허용). */
+    tier: FieldTier;
+    /** record → 프롬프트. */
+    prompt: (record: any) => string;
+}
+export interface Playbook<R = any> {
+    id: string;
+    name: string;
+    domain: string;
+    fields: PlaybookField[];
+    crossChecks: CrossCheckRule<R>[];
+    llmSteps: PlaybookLlmStep[];
+    /** 임상·법률·금융 등 고위험 → 사람 확인 강제(liability). */
+    clinicalScope: boolean;
+    /** 임상 판단을 요하는지 판정(있으면 humanInLoop 강제). */
+    needsHumanReview?: (record: R) => boolean;
+}
+export interface RecordStore<R = any> {
+    add(r: R): void;
+    findDuplicate(r: R): R | null;
+}
+export interface PlaybookFlag {
+    id: string;
+    flag: string;
+    severity: 'block' | 'warn';
+}
+export interface StepOutput {
+    id: string;
+    tier: Tier;
+    provider: 'local' | 'external' | 'none';
+    text: string;
+}
+export interface PlaybookResult {
+    ok: boolean;
+    overallTier: Tier;
+    missingFields: string[];
+    flags: PlaybookFlag[];
+    steps: StepOutput[];
+    humanInLoopRequired: boolean;
+    blockedExternalForPii: boolean;
+    phasesRun: string[];
+    metrics: {
+        ms: number;
+        llmCalls: number;
+    };
+}
+export declare class PlaybookRuntime {
+    private gov?;
+    constructor(gov?: GovernedAgent | undefined);
+    /** 입력 레코드에 PII/민감 필드가 채워져 있으면 전체 Tier-0. */
+    private overallTier;
+    run<R extends Record<string, any>>(pb: Playbook<R>, record: R, store: RecordStore<R>, opts?: {
+        consent?: boolean;
+    }): Promise<PlaybookResult>;
+}