@n2world/orchestrator 1.1.0

package/dist/p6-governance.js

@@ -0,0 +1,252 @@
+"use strict";
+// ============================================================================
+// P6 — 거버넌스 이벤트 버스 · 헌법 롤백 · 정온 시간 게이트 · v2.x 완료 종합 점검
+// ----------------------------------------------------------------------------
+// (계획서 v2.4 §7 P6, §6 완료 정의, 헌법 §0 반-mock 정직성)
+//
+// 정직 고지(제1계명): 모든 집계는 **실 이벤트**에서 온다. `Math.random` 가짜 텔레메트리 금지.
+//   v2.x 완료 점검은 **베타 미가동 항목을 정직하게 unmet 으로 표기**한다(억지 통과 금지).
+//
+// 재사용: `governance.ts`의 GovernanceController(킬스위치)를 롤백의 중단 경로로 사용한다.
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuietTimeGate = exports.DEFAULT_QUIET_CONFIG = exports.ConstitutionalRollback = exports.DEFAULT_ROLLBACK_CONFIG = exports.GovernanceEventBus = exports.DEFAULT_MAX_RETAINED_EVENTS = void 0;
+exports.v2DoDReport = v2DoDReport;
+/** 기본 이벤트 보관 상한(링버퍼). 장수명 대시보드에서 메모리 무한 증가 방지. */
+exports.DEFAULT_MAX_RETAINED_EVENTS = 1000;
+/**
+ * 위반/차단 이벤트 버스 — 실 이벤트만 집계·구독 배포(가짜 텔레메트리 0).
+ *
+ * 메모리: 최근 `maxRetained` 건만 링버퍼로 보관(표시용 `recent`/`all`). **누적 집계(`counts`)는
+ * 보관과 독립적으로 증분 카운터에 유지**되므로, 보관을 상한해도 all-time 통계(특히 안전 핵심인
+ * `tier0ExfilEscaped`)는 정확하다. 장수명 서버에서 `events` 가 무한 증가하던 문제 해소.
+ */
+class GovernanceEventBus {
+    listeners = [];
+    events = []; // 최근 maxRetained 건만(링버퍼)
+    maxRetained;
+    // 누적 집계(보관 상한과 독립 — all-time 정확).
+    agg = {
+        total: 0,
+        blocked: 0,
+        t0attempt: 0,
+        t0escaped: 0,
+        denyDefault: 0,
+        hardFail: 0,
+        criticCalls: 0,
+        tokens: 0,
+    };
+    constructor(maxRetained = exports.DEFAULT_MAX_RETAINED_EVENTS) {
+        this.maxRetained = Math.max(1, maxRetained);
+    }
+    subscribe(fn) {
+        this.listeners.push(fn);
+        return () => {
+            const i = this.listeners.indexOf(fn);
+            if (i >= 0)
+                this.listeners.splice(i, 1);
+        };
+    }
+    publish(e) {
+        // 누적 집계 증분(보관 상한과 독립 — 이전엔 counts() 가 events 전체를 순회했다).
+        this.agg.total++;
+        if (!e.allowed)
+            this.agg.blocked++;
+        if (e.dataTier === 0 && e.destination === 'external')
+            this.agg.t0attempt++;
+        if (e.tier0ExfilEscaped)
+            this.agg.t0escaped++;
+        if (e.layer === 'deny-by-default')
+            this.agg.denyDefault++;
+        if (e.hardGate === false)
+            this.agg.hardFail++;
+        if (e.cost?.criticCalls)
+            this.agg.criticCalls += e.cost.criticCalls;
+        if (e.cost?.tokens)
+            this.agg.tokens += e.cost.tokens;
+        // 최근 이벤트만 보관(메모리 상한) — ConstitutionalRollback.window 와 동일 링버퍼 관용구.
+        this.events.push(e);
+        if (this.events.length > this.maxRetained)
+            this.events.shift();
+        for (const fn of this.listeners)
+            fn(e);
+    }
+    recent(n = 50) {
+        return this.events.slice(-n);
+    }
+    /** 보관된(최근 maxRetained 건) 이벤트. all-time 누적이 필요하면 `counts()` 를 쓴다. */
+    all() {
+        return this.events;
+    }
+    /** 실측 누적 집계 — 대시보드가 표시할 안전·비용 지표(보관 상한과 무관하게 all-time). */
+    counts() {
+        const a = this.agg;
+        return {
+            total: a.total,
+            blocked: a.blocked,
+            blockRate: a.total ? +(a.blocked / a.total).toFixed(4) : 0,
+            tier0ExternalAttempts: a.t0attempt,
+            tier0ExfilEscaped: a.t0escaped,
+            denyByDefault: a.denyDefault,
+            hardGateFailures: a.hardFail,
+            criticCalls: a.criticCalls,
+            totalTokens: a.tokens,
+        };
+    }
+}
+exports.GovernanceEventBus = GovernanceEventBus;
+exports.DEFAULT_ROLLBACK_CONFIG = {
+    denyRateWindow: 20,
+    denyRateThreshold: 0.6,
+};
+/**
+ * 헌법 위반(① Tier-0 실유출 ② 차단율 급증)을 이벤트 버스로 구독해 **즉시 중단·롤백**한다.
+ * 중단은 GovernanceController.kill 로(재사용), 회귀는 권장 폴백 신호로 노출(P3.5 단순화 철회·개인화 OFF 등).
+ */
+class ConstitutionalRollback {
+    gov;
+    cfg;
+    state = { rolledBack: false, reason: '', at: null, recommendedFallback: null };
+    window = []; // 최근 이벤트의 blocked 여부
+    constructor(gov, cfg = exports.DEFAULT_ROLLBACK_CONFIG) {
+        this.gov = gov;
+        this.cfg = cfg;
+    }
+    /** 버스에 구독한다(반환: 구독 해제 함수). */
+    attach(bus) {
+        return bus.subscribe((e) => this.onEvent(e));
+    }
+    trigger(reason, fallback) {
+        if (this.state.rolledBack)
+            return; // 이미 롤백됨
+        this.state = { rolledBack: true, reason, at: Date.now(), recommendedFallback: fallback };
+        this.gov.kill(`constitutional-rollback: ${reason}`); // 즉시 중단(재사용)
+    }
+    onEvent(e) {
+        // ① Tier-0 데이터 실유출 — 단 1건이라도 즉시 롤백(헌법 최우선).
+        if (e.tier0ExfilEscaped) {
+            this.trigger('Tier-0 데이터 외부 유출 관측(헌법 위반)', 'Tier-0 외부 전송 전면 차단 + 운영자 확인');
+        }
+        // ② 차단율 급증(레드팀 거부·위반 폭주) — 슬라이딩 윈도우.
+        this.window.push(!e.allowed);
+        if (this.window.length > this.cfg.denyRateWindow)
+            this.window.shift();
+        if (this.window.length >= this.cfg.denyRateWindow) {
+            const rate = this.window.filter(Boolean).length / this.window.length;
+            if (rate >= this.cfg.denyRateThreshold) {
+                this.trigger(`차단율 급증(${(rate * 100).toFixed(0)}% ≥ ${(this.cfg.denyRateThreshold * 100).toFixed(0)}%)`, '능동성 강도 하향 + 개인화 OFF(부칙3) + P3.5 hard-gate 폴백');
+            }
+        }
+    }
+    status() {
+        return { ...this.state };
+    }
+    /** 운영자 확인 후 롤백 해제(킬스위치 리셋 포함). */
+    reset() {
+        this.state = { rolledBack: false, reason: '', at: null, recommendedFallback: null };
+        this.window = [];
+        this.gov.reset();
+    }
+}
+exports.ConstitutionalRollback = ConstitutionalRollback;
+exports.DEFAULT_QUIET_CONFIG = { startHour: 22, endHour: 7, intensity: 0.3 };
+const URGENCY_SCORE = { low: 0.2, normal: 0.5, high: 0.9 };
+class QuietTimeGate {
+    cfg;
+    constructor(cfg = {}) {
+        this.cfg = { ...exports.DEFAULT_QUIET_CONFIG, ...cfg };
+    }
+    setIntensity(x) {
+        this.cfg.intensity = Math.max(0, Math.min(1, x));
+    }
+    config() {
+        return { ...this.cfg };
+    }
+    /** 주어진 시각이 정온 시간대인가(자정 넘김 처리). */
+    isQuiet(date = new Date()) {
+        const h = date.getHours();
+        const { startHour, endHour } = this.cfg;
+        if (startHour === endHour)
+            return false;
+        if (startHour < endHour)
+            return h >= startHour && h < endHour; // 같은 날
+        return h >= startHour || h < endHour; // 자정 넘김(22→7)
+    }
+    /**
+     * 백그라운드 능동 작업을 허용할지. 정온 시간엔 억제하되, 긴급도와 능동성 강도로 조절한다.
+     * 규칙: 정온 아니면 허용. 정온이면 (urgencyScore + intensity ≥ 1.0) 일 때만 허용.
+     *  - intensity=0: 정온 중 전부 억제(high 도). intensity=1: 전부 허용.
+     *  - high(0.9)는 intensity≥0.1, normal(0.5)은 intensity≥0.5, low(0.2)는 intensity≥0.8 필요.
+     */
+    allowBackgroundAction(date = new Date(), urgency = 'normal') {
+        if (!this.isQuiet(date))
+            return { allowed: true, reason: '정온 시간 아님 — 허용' };
+        const allowed = URGENCY_SCORE[urgency] + this.cfg.intensity >= 1.0 - 1e-9;
+        return {
+            allowed,
+            reason: allowed
+                ? `정온이나 긴급도(${urgency})·강도(${this.cfg.intensity}) 충족 — 허용`
+                : `정온 시간 — 백그라운드 억제(긴급도 ${urgency}, 강도 ${this.cfg.intensity})`,
+        };
+    }
+}
+exports.QuietTimeGate = QuietTimeGate;
+/**
+ * v2.x 완료 정의 5개를 점검한다. **베타 미가동이면 ①②를 정직하게 unmet 으로** 표기한다
+ * (접지 영가설 — master §2: 바닥은 인간이다). 억지 통과 금지.
+ */
+function v2DoDReport(inp) {
+    const criteria = [
+        {
+            name: '① 출시(클로즈드 베타 N명 인도)',
+            status: inp.betaUsersDelivered > 0 ? 'met' : 'unmet',
+            evidence: inp.betaUsersDelivered > 0
+                ? `베타 ${inp.betaUsersDelivered}명 인도(코드·로그 증거).`
+                : 'B0 베타 인프라(동의·온보딩·피드백·Tier 가드)는 구현·검증됐으나 **실사용자 인도 0명** — 미가동(정직).',
+        },
+        {
+            name: '② 핵심 가설(실사용자 리프트 측정)',
+            status: inp.realUserLiftMeasured ? 'met' : 'unmet',
+            evidence: inp.realUserLiftMeasured
+                ? 'B1 MultiAxisLift 가 실사용자 데이터로 측정됨.'
+                : 'B1 MultiAxisLift 4축 측정 코드·통계 검정은 구현됐으나 **실사용자 라벨 부재 → (목표; 미측정)**. 만족 축 미반영.',
+        },
+        {
+            name: '③ 안전(거부율 분리 보고 + Tier-0 0/N)',
+            status: inp.safetySeparatedReported && inp.tier0ExfilObserved === 0 ? 'met' : 'partial',
+            evidence: `P4.7 위반 포착 규칙/비평 분리 보고 + P5 Tier-0 외부 반출 관측 ${inp.tier0ExfilObserved}/N. ` +
+                (inp.safetySeparatedReported && inp.tier0ExfilObserved === 0
+                    ? '합성/실제 일부 분리 — 인간-라벨 레드팀/베타 골드는 (목표; 미측정).'
+                    : '분리 보고 또는 Tier-0 보장 미충족.'),
+        },
+        {
+            name: '④ 정직성((목표;미측정) 준수·mock 0·명칭 인플레이션 0)',
+            status: inp.honestyHeld ? 'met' : 'unmet',
+            evidence: inp.honestyHeld
+                ? '전 단계 측정 전 주장은 (목표;미측정) 표기, 가짜 텔레메트리·시뮬 0, 실 LLM/오라클/HMAC 호출 증거 첨부.'
+                : '정직성 위반 발견.',
+        },
+        {
+            name: '⑤ 복잡도(영가설 준수 — 정당화 못 한 부품 0)',
+            status: inp.complexityWithinBudget ? 'met' : 'partial',
+            evidence: inp.complexityWithinBudget
+                ? '신규는 사실상 모델-비평 축소·SmoothSafetyAnneal·DurabilitySpec; ParetoFrontierKeeper 제거, 자가치유 연기. 영가설로 관리.'
+                : '복잡도 예산 초과 또는 정당화 미흡 부품 존재.',
+        },
+    ];
+    const metCount = criteria.filter((c) => c.status === 'met').length;
+    const partialCount = criteria.filter((c) => c.status === 'partial').length;
+    const unmetCount = criteria.filter((c) => c.status === 'unmet').length;
+    const complete = metCount === criteria.length;
+    return {
+        criteria,
+        metCount,
+        partialCount,
+        unmetCount,
+        complete,
+        verdict: complete
+            ? 'v2.x 완료 — 5개 정의 충족.'
+            : `v2.x **미완(정직)** — ${metCount}/5 met, ${partialCount} partial, ${unmetCount} unmet. ` +
+                '핵심 미충족은 ①출시·②실사용자 리프트(베타 미가동). 다음 산출물은 새 계획서가 아니라 **베타 실행**이다(접지 영가설).',
+    };
+}

package/dist/pairing.d.ts

@@ -0,0 +1,22 @@
+export interface PairingChallenge {
+    qrToken: string;
+    pin: string;
+    expiresAt: number;
+}
+export interface PairingResult {
+    ok: boolean;
+    reason: string;
+    companionToken?: string;
+}
+export declare class PairingManager {
+    private ttlMs;
+    private pending;
+    constructor(ttlMs?: number);
+    /** PC가 QR+PIN 발급. */
+    issue(now?: number): PairingChallenge;
+    /**
+     * 모바일이 QR 스캔 + PIN 입력으로 페어링 시도. 일회성·만료·PIN·루프백 검증.
+     * @param loopbackOrLan 동일 LAN/루프백 경로 여부(외부 릴레이는 옵트인 — 기본 false 거부)
+     */
+    redeem(qrToken: string, pin: string, loopbackOrLan: boolean, now?: number): PairingResult;
+}

package/dist/pairing.js

@@ -0,0 +1,81 @@
+"use strict";
+// ============================================================================
+// P4 — 모바일↔PC 페어링 계약 (앱 v1.2 §4.3) — TS측(검증 가능)
+// ----------------------------------------------------------------------------
+// QR 토큰(일회성·만료·PIN 바인딩)으로 폰을 PC 상주 에이전트의 리모컨으로 페어링.
+// 성공 시 companion 토큰을 교환한다. 위조/만료/재사용/PIN 불일치는 거부.
+//
+// 정직 고지(제1계명): 본 모듈은 *페어링 핸드셰이크 계약*(테스트 가능). 모바일 앱·
+// 카메라 QR·mDNS는 네이티브(이 환경 미빌드 — companions/mobile 스캐폴드).
+// ============================================================================
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PairingManager = void 0;
+const crypto = __importStar(require("crypto"));
+class PairingManager {
+    ttlMs;
+    pending = new Map();
+    constructor(ttlMs = 2 * 60 * 1000) {
+        this.ttlMs = ttlMs;
+    }
+    /** PC가 QR+PIN 발급. */
+    issue(now = Date.now()) {
+        const qrToken = crypto.randomBytes(16).toString('base64url');
+        const pin = String(crypto.randomInt(100000, 999999)); // 6자리
+        this.pending.set(qrToken, { pin, expiresAt: now + this.ttlMs });
+        return { qrToken, pin, expiresAt: now + this.ttlMs };
+    }
+    /**
+     * 모바일이 QR 스캔 + PIN 입력으로 페어링 시도. 일회성·만료·PIN·루프백 검증.
+     * @param loopbackOrLan 동일 LAN/루프백 경로 여부(외부 릴레이는 옵트인 — 기본 false 거부)
+     */
+    redeem(qrToken, pin, loopbackOrLan, now = Date.now()) {
+        const p = this.pending.get(qrToken);
+        if (!p)
+            return { ok: false, reason: '토큰 없음/이미 사용됨' };
+        if (now > p.expiresAt) {
+            this.pending.delete(qrToken);
+            return { ok: false, reason: '만료' };
+        }
+        if (!loopbackOrLan)
+            return { ok: false, reason: '로컬(LAN/루프백) 경로 아님 — 외부 릴레이는 옵트인' };
+        if (pin !== p.pin)
+            return { ok: false, reason: 'PIN 불일치' };
+        this.pending.delete(qrToken); // 일회성 소모
+        const companionToken = crypto.randomBytes(24).toString('base64url');
+        return { ok: true, reason: 'ok', companionToken };
+    }
+}
+exports.PairingManager = PairingManager;

package/dist/personalization.d.ts

@@ -0,0 +1,35 @@
+export interface SkillCandidate {
+    id: string;
+    content: string;
+}
+export interface PriorWeight {
+    id: string;
+    weight: number;
+}
+export interface PersonalizationOptions {
+    /** A/B 토글. false면 균등 사전확률(개인화 OFF = baseline). */
+    enabled: boolean;
+    /** softmax 온도(>0). 낮을수록 상위 후보에 집중. */
+    temperature?: number;
+}
+/**
+ * 사용자 컨텍스트로 후보 스킬에 가중한 사전확률(합=1)을 만든다.
+ * enabled=false면 균등 분포(개인화 OFF). enabled=true면 임베딩 코사인 유사도 softmax.
+ * 후보가 비면 빈 배열을 반환한다.
+ */
+export declare function personalizedPrior(candidates: SkillCandidate[], userContext: string, opts: PersonalizationOptions): PriorWeight[];
+/**
+ * 사용자 프로필: 베타 사용자가 자주 쓴 컨텍스트/스킬을 누적. (로컬에만 머문다 — 헌법 제4조.)
+ * 개인화 컨텍스트 문자열을 만든다(최근 사용 가중).
+ */
+export declare class UserProfile {
+    readonly userId: string;
+    private maxTerms;
+    private terms;
+    constructor(userId: string, maxTerms?: number);
+    /** 사용자가 실행/선택한 컨텍스트를 누적(최근 것 우선 유지). */
+    observe(contextText: string): void;
+    /** 개인화 컨텍스트 주입 문자열(누적 토큰). 비면 ''. */
+    contextString(): string;
+    termCount(): number;
+}

package/dist/personalization.js

@@ -0,0 +1,73 @@
+"use strict";
+// ============================================================================
+// B0 / Week-1 최소 개인화 MVP — 임베딩 가중 사전확률 + 컨텍스트 주입
+// ----------------------------------------------------------------------------
+// 정직 고지(구현강도 상한): 이것은 **얕은 개인화**다 — 사용자 컨텍스트와 후보 스킬의
+// 해시 bag-of-tokens 임베딩 코사인 유사도로 사전확률을 가중할 뿐이다(neural latent 아님).
+// B1 의 MultiAxisLift 가 죽지 않을 "최소 두께"만 구현한다(과한 두께는 단순화 원칙 위반).
+// A/B 토글(enabled): OFF면 균등 사전확률(비교군 baseline), ON이면 임베딩 가중.
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserProfile = void 0;
+exports.personalizedPrior = personalizedPrior;
+const text_embedding_1 = require("./text-embedding");
+/**
+ * 사용자 컨텍스트로 후보 스킬에 가중한 사전확률(합=1)을 만든다.
+ * enabled=false면 균등 분포(개인화 OFF). enabled=true면 임베딩 코사인 유사도 softmax.
+ * 후보가 비면 빈 배열을 반환한다.
+ */
+function personalizedPrior(candidates, userContext, opts) {
+    const n = candidates.length;
+    if (n === 0)
+        return [];
+    // 개인화 OFF: 균등 사전확률(비교군).
+    if (!opts.enabled) {
+        const w = 1 / n;
+        return candidates.map((c) => ({ id: c.id, weight: w }));
+    }
+    const temp = opts.temperature && opts.temperature > 0 ? opts.temperature : 0.25;
+    const ctxVec = (0, text_embedding_1.textEmbedding)(userContext);
+    // 코사인 유사도∈[-1,1] → softmax. 컨텍스트가 비면 유사도 0(균등으로 수렴).
+    const sims = candidates.map((c) => (0, text_embedding_1.cosineSimilarity)((0, text_embedding_1.textEmbedding)(c.content), ctxVec));
+    const maxSim = Math.max(...sims);
+    const exps = sims.map((s) => Math.exp((s - maxSim) / temp)); // 수치 안정화
+    const z = exps.reduce((a, b) => a + b, 0);
+    if (z <= 0 || !isFinite(z)) {
+        const w = 1 / n;
+        return candidates.map((c) => ({ id: c.id, weight: w }));
+    }
+    return candidates.map((c, i) => ({ id: c.id, weight: exps[i] / z }));
+}
+/**
+ * 사용자 프로필: 베타 사용자가 자주 쓴 컨텍스트/스킬을 누적. (로컬에만 머문다 — 헌법 제4조.)
+ * 개인화 컨텍스트 문자열을 만든다(최근 사용 가중).
+ */
+class UserProfile {
+    userId;
+    maxTerms;
+    terms = [];
+    constructor(userId, maxTerms = 64) {
+        this.userId = userId;
+        this.maxTerms = maxTerms;
+    }
+    /** 사용자가 실행/선택한 컨텍스트를 누적(최근 것 우선 유지). */
+    observe(contextText) {
+        const toks = (contextText || '')
+            .toLowerCase()
+            .split(/[^a-z0-9가-힣]+/)
+            .filter((t) => t.length > 1);
+        for (const t of toks)
+            this.terms.push(t);
+        if (this.terms.length > this.maxTerms) {
+            this.terms = this.terms.slice(this.terms.length - this.maxTerms);
+        }
+    }
+    /** 개인화 컨텍스트 주입 문자열(누적 토큰). 비면 ''. */
+    contextString() {
+        return this.terms.join(' ');
+    }
+    termCount() {
+        return this.terms.length;
+    }
+}
+exports.UserProfile = UserProfile;

package/dist/pglite-hnsw-bridge.d.ts

@@ -0,0 +1,118 @@
+import { HnswIndex } from '@n2world/core';
+import { StoreMode } from './pglite-store';
+export interface VecWrite {
+    id: string;
+    content: string;
+    embedding: number[];
+}
+export interface InsertOptions {
+    /** 즉시 publish(검색 가시화). false 면 stale 상태로 두고 이후 publish() 로 일괄 가시화. */
+    publish?: boolean;
+    /**
+     * 테스트 전용: WAL durable append(=ack) **후, PGLite 적용 전** 크래시를 모사한다.
+     * ack 는 이미 반환됐고 WAL 에는 남아, recover() 의 재생 대상이 된다.
+     */
+    simulateCrashBeforeApply?: boolean;
+}
+/** epoch 읽기 가드 — 리더가 캡처한 버퍼와 그 세대(epoch). */
+export interface ReadGuard {
+    index: HnswIndex;
+    epoch: number;
+}
+export interface DurabilityReport {
+    storeMode: StoreMode;
+    /** ack 반환된 쓰기 수(= WAL durable append 성공 수). */
+    ackedWrites: number;
+    /** 관측된 torn-read(부분/혼합 세대 읽기). 0 이어야 함. */
+    tornReadObserved: number;
+    /** epoch 회수된 retired 버퍼 수(RCU 동작 증거). */
+    reclaimedBuffers: number;
+    /** RCU 위반 시도(리더가 남은 버퍼를 회수하려 한 횟수). 0 이어야 함. */
+    unsafeReclaimAttempts: number;
+    /** 동시 보유 버퍼 최대치(메모리 ~2배 근거). 정상이면 ≤ 2. */
+    peakLiveBuffers: number;
+    /** insert→publish 가시화 윈도우 최대치(ms, 측정값). `임베딩 stale ≤ W`. */
+    staleWindowMs: number;
+}
+/**
+ * PGLite(영속) ↔ HNSW(검색) 동기화 브리지.
+ * - 쓰기: WAL durable append(ack) → PGLite 적용 → WAL ack(삭제) → (옵션) publish.
+ * - 읽기: active 버퍼 참조를 캡처(epoch guard)해 검색 — 삽입에 막히지 않음(분리).
+ * - 교체: 새 인덱스를 빌드 후 원자 swap, 구 버퍼는 리더가 빠질 때 epoch 회수(RCU).
+ */
+export declare class PgliteHnswSyncBridge {
+    private readonly storeDir;
+    private readonly walPath;
+    private store;
+    private wal;
+    private items;
+    private activeIndex;
+    private activeEpoch;
+    /** epoch → 활성 리더 수(active/retired 공통). */
+    private readers;
+    /** 회수 대기 중인 구 버퍼(리더가 남아 아직 못 버림). epoch → index. */
+    private retired;
+    /** 세대별 멤버십(torn-read 검증용): epoch → 그 세대에 보였던 id 집합. */
+    private genIds;
+    private ackedWrites;
+    private tornReadObserved;
+    private reclaimedBuffers;
+    private unsafeReclaimAttempts;
+    private peakLiveBuffers;
+    private staleSamplesMs;
+    /** publish 안 된(가시화 대기) 쓰기의 삽입 시각. id→t. */
+    private pendingSince;
+    private initialized;
+    constructor(storeDir: string | undefined, walPath: string);
+    init(): Promise<void>;
+    storeMode(): StoreMode;
+    /**
+     * 벡터 쓰기. **ack 는 WAL durable append 직후 반환된다**(인메모리 직후 아님).
+     * 반환 시점 = 내구 보장 시점. 이후 PGLite 적용·publish.
+     */
+    insert(w: VecWrite, opts?: InsertOptions): Promise<{
+        acked: boolean;
+    }>;
+    /** WAL 의 in-flight 항목을 PGLite 에 재생(크래시 복구). 복구된 건수 반환. */
+    recover(): Promise<number>;
+    /**
+     * 검색. active 버퍼 참조를 epoch 가드로 캡처해 **동기** 검색한다.
+     * 캡처한 참조는 검색 동안 불변 → 부분/혼합 세대(torn-read) 불가.
+     */
+    search(query: number[], k?: number): Promise<string[]>;
+    /**
+     * P2 인계 — 안정적 읽기 스냅샷 인터페이스. `openSnapshot()` → `snapshotSearch()`* → `closeSnapshot()`.
+     * 스냅샷이 열려 있는 동안 그 세대(epoch) 버퍼는 RCU 로 보호되어 회수되지 않는다(관계 추출 등
+     * 다단계 읽기가 일관된 단일 세대 위에서 동작하도록 보장). 닫으면 회수 가능해진다.
+     */
+    openSnapshot(): ReadGuard;
+    /** 스냅샷 안의 검색(동기). 결과는 캡처한 세대의 멤버여야 한다 — 아니면 torn-read 로 카운트. */
+    snapshotSearch(g: ReadGuard, query: number[], k?: number): string[];
+    closeSnapshot(g: ReadGuard): void;
+    /** 가시화: 인메모리 사본으로 새 인덱스를 빌드해 원자 swap(검색 경로를 막지 않음). */
+    publish(): void;
+    durability(): DurabilityReport;
+    count(): Promise<number>;
+    /**
+     * 내구성 실측: ack 반환된 id 들이 **durable PGLite 원본**에 실제로 존재하는지 확인한다.
+     * `ack 유실 0/N` 은 이 검증의 missing.length === 0 으로 증명한다(스텁 아님 — 원본 조회).
+     */
+    verifyDurable(expectedIds: string[]): Promise<{
+        present: number;
+        missing: string[];
+    }>;
+    close(): Promise<void>;
+    private applyWrite;
+    /** 적용 완료된 id 의 WAL 항목을 ack(삭제). */
+    private ackApplied;
+    /** 인메모리 사본으로 새 인덱스를 빌드하고 원자 swap + 구 버퍼 retire(RCU). */
+    private rebuildAndSwap;
+    /**
+     * RCU 회수 — **리더가 0 인 epoch 만** 버퍼/세대를 회수한다.
+     * 리더가 남았는데 호출되면 회수하지 않고 위반으로 카운트한다(불변식 가드).
+     */
+    private safeReclaim;
+    private acquireRead;
+    private releaseRead;
+    private trackPeakBuffers;
+}