stellavault 0.1.0

package/packages/core/src/federation/sharing.ts

@@ -0,0 +1,165 @@
+// Federation: Sharing Control
+// 노드별 공유 범위 관리 — 태그/폴더/문서 단위로 공개/비공개 설정
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+export interface SharingConfig {
+  mode: 'whitelist' | 'blacklist';  // whitelist=명시적 공개만, blacklist=명시적 비공개만
+
+  // 태그 기반
+  allowedTags: string[];     // whitelist 모드: 이 태그가 있는 문서만 공개
+  blockedTags: string[];     // blacklist 모드: 이 태그가 있는 문서 제외
+
+  // 폴더 기반
+  allowedFolders: string[];  // whitelist 모드: 이 폴더만 공개
+  blockedFolders: string[];  // blacklist 모드: 이 폴더 제외
+
+  // 문서 단위
+  blockedDocIds: string[];   // 개별 문서 ID 차단 (둘 다 적용)
+
+  // 콘텐츠 필터
+  blockSensitivePatterns: boolean;  // 이메일, 전화번호, API키 패턴 자동 감지→차단
+}
+
+const SHARING_FILE = join(homedir(), '.stellavault', 'federation', 'sharing.json');
+
+const DEFAULT_CONFIG: SharingConfig = {
+  mode: 'blacklist',
+  allowedTags: [],
+  blockedTags: ['personal', 'private', 'secret', 'diary', 'salary', 'password', 'credential'],
+  allowedFolders: [],
+  blockedFolders: ['03_Daily', '06_Archive', '.obsidian'],
+  blockedDocIds: [],
+  blockSensitivePatterns: true,
+};
+
+// 민감 패턴
+const SENSITIVE_PATTERNS = [
+  /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/,  // 이메일
+  /\b\d{3}[-.]?\d{4}[-.]?\d{4}\b/,    // 전화번호
+  /\b(sk-|pk-|api[_-]?key|token|secret)[a-zA-Z0-9_-]{10,}\b/i,  // API 키
+  /\bpassword\s*[:=]\s*\S+/i,         // password=xxx
+  /\b\d{6}[-]\d{7}\b/,                // 주민번호 패턴
+];
+
+export function loadSharingConfig(): SharingConfig {
+  if (existsSync(SHARING_FILE)) {
+    const raw = JSON.parse(readFileSync(SHARING_FILE, 'utf-8'));
+    return { ...DEFAULT_CONFIG, ...raw };
+  }
+  return { ...DEFAULT_CONFIG };
+}
+
+export function saveSharingConfig(config: SharingConfig): void {
+  mkdirSync(join(homedir(), '.stellavault', 'federation'), { recursive: true });
+  writeFileSync(SHARING_FILE, JSON.stringify(config, null, 2), 'utf-8');
+}
+
+// 문서가 공유 가능한지 확인
+export function isDocumentShareable(
+  doc: { tags: string[]; filePath: string; id: string; content: string },
+  config?: SharingConfig,
+): boolean {
+  const cfg = config ?? loadSharingConfig();
+
+  // 1. 개별 차단 확인
+  if (cfg.blockedDocIds.includes(doc.id)) return false;
+
+  // 2. 폴더 기반 필터
+  const folder = doc.filePath.split('/')[0] ?? '';
+  if (cfg.mode === 'whitelist') {
+    if (cfg.allowedFolders.length > 0 && !cfg.allowedFolders.some(f => doc.filePath.startsWith(f))) {
+      return false;
+    }
+  } else {
+    if (cfg.blockedFolders.some(f => doc.filePath.startsWith(f))) {
+      return false;
+    }
+  }
+
+  // 3. 태그 기반 필터
+  const docTags = doc.tags.map(t => t.toLowerCase());
+  if (cfg.mode === 'whitelist') {
+    if (cfg.allowedTags.length > 0 && !cfg.allowedTags.some(t => docTags.includes(t.toLowerCase()))) {
+      return false;
+    }
+  } else {
+    if (cfg.blockedTags.some(t => docTags.includes(t.toLowerCase()))) {
+      return false;
+    }
+  }
+
+  // 4. 민감 패턴 감지
+  if (cfg.blockSensitivePatterns) {
+    for (const pattern of SENSITIVE_PATTERNS) {
+      if (pattern.test(doc.content)) return false;
+    }
+  }
+
+  return true;
+}
+
+// 스니펫에서 민감 정보 제거
+export function sanitizeSnippet(snippet: string): string {
+  let safe = snippet;
+  for (const pattern of SENSITIVE_PATTERNS) {
+    safe = safe.replace(pattern, '[REDACTED]');
+  }
+  return safe;
+}
+
+// CLI 헬퍼: 현재 공유 설정 요약
+export function getSharingSummary(config?: SharingConfig): string {
+  const cfg = config ?? loadSharingConfig();
+  const lines: string[] = [];
+  lines.push(`Mode: ${cfg.mode}`);
+  if (cfg.mode === 'blacklist') {
+    lines.push(`Blocked tags: ${cfg.blockedTags.join(', ') || 'none'}`);
+    lines.push(`Blocked folders: ${cfg.blockedFolders.join(', ') || 'none'}`);
+  } else {
+    lines.push(`Allowed tags: ${cfg.allowedTags.join(', ') || 'all'}`);
+    lines.push(`Allowed folders: ${cfg.allowedFolders.join(', ') || 'all'}`);
+  }
+  lines.push(`Blocked docs: ${cfg.blockedDocIds.length}`);
+  lines.push(`Sensitive pattern filter: ${cfg.blockSensitivePatterns ? 'ON' : 'OFF'}`);
+  return lines.join('\n');
+}
+
+// 태그 추가/제거 헬퍼
+export function addBlockedTag(tag: string): void {
+  const cfg = loadSharingConfig();
+  if (!cfg.blockedTags.includes(tag.toLowerCase())) {
+    cfg.blockedTags.push(tag.toLowerCase());
+    saveSharingConfig(cfg);
+  }
+}
+
+export function removeBlockedTag(tag: string): void {
+  const cfg = loadSharingConfig();
+  cfg.blockedTags = cfg.blockedTags.filter(t => t !== tag.toLowerCase());
+  saveSharingConfig(cfg);
+}
+
+export function addBlockedFolder(folder: string): void {
+  const cfg = loadSharingConfig();
+  if (!cfg.blockedFolders.includes(folder)) {
+    cfg.blockedFolders.push(folder);
+    saveSharingConfig(cfg);
+  }
+}
+
+export function blockDocument(docId: string): void {
+  const cfg = loadSharingConfig();
+  if (!cfg.blockedDocIds.includes(docId)) {
+    cfg.blockedDocIds.push(docId);
+    saveSharingConfig(cfg);
+  }
+}
+
+export function unblockDocument(docId: string): void {
+  const cfg = loadSharingConfig();
+  cfg.blockedDocIds = cfg.blockedDocIds.filter(id => id !== docId);
+  saveSharingConfig(cfg);
+}

package/packages/core/src/federation/trust.ts

@@ -0,0 +1,76 @@
+// Federation Phase 2: Web of Trust
+// vouch/revoke/block — 노드 간 상호 신뢰 관리
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+export interface TrustEntry {
+  peerId: string;
+  displayName: string;
+  level: 'vouched' | 'neutral' | 'blocked';
+  reason?: string;
+  updatedAt: string;
+}
+
+const TRUST_FILE = join(homedir(), '.stellavault', 'federation', 'trust.json');
+
+function loadTrustDb(): Map<string, TrustEntry> {
+  if (!existsSync(TRUST_FILE)) return new Map();
+  const raw = JSON.parse(readFileSync(TRUST_FILE, 'utf-8')) as TrustEntry[];
+  return new Map(raw.map(e => [e.peerId, e]));
+}
+
+function saveTrustDb(db: Map<string, TrustEntry>): void {
+  mkdirSync(join(homedir(), '.stellavault', 'federation'), { recursive: true });
+  writeFileSync(TRUST_FILE, JSON.stringify([...db.values()], null, 2), 'utf-8');
+}
+
+export function vouch(peerId: string, displayName: string, reason?: string): TrustEntry {
+  const db = loadTrustDb();
+  const entry: TrustEntry = { peerId, displayName, level: 'vouched', reason, updatedAt: new Date().toISOString() };
+  db.set(peerId, entry);
+  saveTrustDb(db);
+  return entry;
+}
+
+export function revoke(peerId: string): boolean {
+  const db = loadTrustDb();
+  const entry = db.get(peerId);
+  if (!entry) return false;
+  entry.level = 'neutral';
+  entry.updatedAt = new Date().toISOString();
+  saveTrustDb(db);
+  return true;
+}
+
+export function block(peerId: string, displayName: string, reason?: string): TrustEntry {
+  const db = loadTrustDb();
+  const entry: TrustEntry = { peerId, displayName, level: 'blocked', reason, updatedAt: new Date().toISOString() };
+  db.set(peerId, entry);
+  saveTrustDb(db);
+  return entry;
+}
+
+export function getTrustLevel(peerId: string): TrustEntry['level'] {
+  const db = loadTrustDb();
+  return db.get(peerId)?.level ?? 'neutral';
+}
+
+export function isBlocked(peerId: string): boolean {
+  return getTrustLevel(peerId) === 'blocked';
+}
+
+export function listTrusted(): TrustEntry[] {
+  return [...loadTrustDb().values()];
+}
+
+// 신뢰 점수 계산 (0-100)
+export function computeTrustScore(peerId: string): number {
+  const level = getTrustLevel(peerId);
+  switch (level) {
+    case 'vouched': return 80;
+    case 'neutral': return 50;
+    case 'blocked': return 0;
+  }
+}

package/packages/core/src/federation/types.ts

@@ -0,0 +1,25 @@
+// Design Ref: §2.2 — Federation 공유 타입 정의
+
+export interface PeerInfo {
+  peerId: string;
+  displayName: string;
+  documentCount: number;
+  topTopics: string[];
+  joinedAt: string;
+  lastSeen: string;
+}
+
+export interface FederatedSearchResult {
+  title: string;
+  similarity: number;
+  snippet: string;       // 원문 첫 50자
+  peerId: string;
+  peerName: string;
+}
+
+// Design Ref: §7 — 메시지 프로토콜 (JSON + newline delimiter)
+export type FederationMessage =
+  | { type: 'handshake'; peerId: string; displayName: string; version: string; documentCount: number; topTopics: string[] }
+  | { type: 'search_query'; queryId: string; embedding: number[]; limit: number }
+  | { type: 'search_result'; queryId: string; results: Array<{ title: string; similarity: number; snippet: string }> }
+  | { type: 'leave'; peerId: string };

package/packages/core/src/i18n/index.ts

@@ -0,0 +1,85 @@
+// i18n Foundation (F-A19)
+// Simple string externalization for CLI and Graph UI
+
+export type Locale = 'en' | 'ko' | 'ja' | 'zh';
+
+const strings: Record<Locale, Record<string, string>> = {
+  en: {
+    'init.welcome': 'Stellavault Setup Wizard',
+    'init.tagline': "Notes die in folders. Let's bring yours to life.",
+    'init.step1': 'Where is your Obsidian vault?',
+    'init.step2': 'Indexing your vault',
+    'init.step3': 'Try your first search',
+    'init.done': 'Setup complete!',
+    'index.complete': 'Indexing complete',
+    'search.no_results': 'No results found.',
+    'decay.report_title': 'Knowledge Decay Report',
+    'decay.tip': 'Search a topic to refresh decaying knowledge',
+    'learn.title': 'Your Learning Path',
+    'learn.all_clear': 'All clear! Your knowledge is in great shape.',
+    'contradictions.title': 'potential contradictions found',
+    'contradictions.none': 'No contradictions detected. Your knowledge is consistent!',
+    'graph.title': 'Stellavault',
+    'graph.subtitle': 'Neural Knowledge Graph',
+    'error.vault_not_found': 'Vault not found',
+    'error.db_init_failed': 'Database initialization failed',
+    'error.embedder_failed': 'Embedding model failed to load',
+  },
+  ko: {
+    'init.welcome': 'Stellavault 설정 마법사',
+    'init.tagline': '노트는 폴더에서 죽습니다. 당신의 지식을 살려봅시다.',
+    'init.step1': 'Obsidian vault 경로가 어디인가요?',
+    'init.step2': 'vault 인덱싱 중',
+    'init.step3': '첫 번째 검색을 해보세요',
+    'init.done': '설정 완료!',
+    'index.complete': '인덱싱 완료',
+    'search.no_results': '검색 결과가 없습니다.',
+    'decay.report_title': '지식 감쇠 리포트',
+    'decay.tip': '검색하면 감쇠 중인 지식이 리프레시됩니다',
+    'learn.title': '당신의 학습 경로',
+    'learn.all_clear': '모든 지식이 건강합니다!',
+    'contradictions.title': '개의 잠재적 모순 발견',
+    'contradictions.none': '모순이 없습니다. 지식이 일관됩니다!',
+    'graph.title': 'Stellavault',
+    'graph.subtitle': '뉴럴 지식 그래프',
+    'error.vault_not_found': 'vault를 찾을 수 없습니다',
+    'error.db_init_failed': '데이터베이스 초기화 실패',
+    'error.embedder_failed': '임베딩 모델 로딩 실패',
+  },
+  ja: {
+    'init.welcome': 'Stellavault セットアップウィザード',
+    'init.tagline': 'ノートはフォルダで死にます。あなたの知識を生かしましょう。',
+    'graph.title': 'Stellavault',
+    'graph.subtitle': 'ニューラルナレッジグラフ',
+    'search.no_results': '検索結果がありません。',
+  },
+  zh: {
+    'init.welcome': 'Stellavault 设置向导',
+    'init.tagline': '笔记在文件夹中消亡。让你的知识活起来。',
+    'graph.title': 'Stellavault',
+    'graph.subtitle': '神经知识图谱',
+    'search.no_results': '没有搜索结果。',
+  },
+};
+
+let currentLocale: Locale = 'en';
+
+export function setLocale(locale: Locale): void {
+  currentLocale = locale;
+}
+
+export function getLocale(): Locale {
+  return currentLocale;
+}
+
+export function t(key: string, fallback?: string): string {
+  return strings[currentLocale]?.[key] ?? strings.en[key] ?? fallback ?? key;
+}
+
+export function detectLocale(): Locale {
+  const env = process.env.LANG || process.env.LANGUAGE || process.env.LC_ALL || '';
+  if (env.startsWith('ko')) return 'ko';
+  if (env.startsWith('ja')) return 'ja';
+  if (env.startsWith('zh')) return 'zh';
+  return 'en';
+}

package/packages/core/src/index.ts

@@ -0,0 +1,133 @@
+// Design Ref: §4.2 — Core Internal API (Facade)
+// Design Ref: §9.3 — Dependency Injection Pattern
+
+export { loadConfig } from './config.js';
+export type { StellavaultConfig } from './config.js';
+
+// Types
+export type { Document } from './types/document.js';
+export type { Chunk, ScoredChunk } from './types/chunk.js';
+export type {
+  SearchResult,
+  SearchOptions,
+  TopicInfo,
+  StoreStats,
+} from './types/search.js';
+
+// Interfaces
+export type { VectorStore } from './store/types.js';
+export type { Embedder } from './indexer/embedder.js';
+
+// Store
+export { createSqliteVecStore } from './store/index.js';
+
+// Indexer
+export { indexVault, scanVault, chunkDocument, createLocalEmbedder } from './indexer/index.js';
+export type { IndexResult, IndexerOptions } from './indexer/index.js';
+
+// Search
+export { createSearchEngine } from './search/index.js';
+export type { SearchEngine } from './search/index.js';
+
+// MCP
+export { createMcpServer } from './mcp/index.js';
+
+// Pack (Phase 3)
+export { createPack, exportPack, importPack, packToSummary, maskPII } from './pack/index.js';
+export type { KnowledgePack, PackChunk, PackInfo, CreatePackOptions, ImportResult, MaskResult } from './pack/index.js';
+
+// API (Phase 2)
+export { createApiServer } from './api/server.js';
+export type { ApiServerOptions } from './api/server.js';
+export type { GraphNode, GraphEdge, Cluster, GraphData, GraphResponse } from './types/graph.js';
+
+// Intelligence (Phase 4b)
+export { DecayEngine } from './intelligence/decay-engine.js';
+export type { DecayState, AccessEvent, DecayReport } from './intelligence/types.js';
+export { computeRetrievability, updateStability, estimateInitialStability, elapsedDays } from './intelligence/fsrs.js';
+export { detectDuplicates } from './intelligence/duplicate-detector.js';
+export { detectKnowledgeGaps } from './intelligence/gap-detector.js';
+export { detectContradictions } from './intelligence/contradiction-detector.js';
+export type { ContradictionPair } from './intelligence/contradiction-detector.js';
+export { computeSemanticDrift, findMostDrifted, hashEmbedding } from './intelligence/semantic-versioning.js';
+export type { SemanticChangelog, SemanticVersion } from './intelligence/semantic-versioning.js';
+export { predictKnowledgeGaps } from './intelligence/predictive-gaps.js';
+export type { PredictedGap } from './intelligence/predictive-gaps.js';
+export type { DuplicatePair } from './intelligence/duplicate-detector.js';
+export { generateLearningPath } from './intelligence/learning-path.js';
+export type { LearningPath, LearningItem, LearningPathInput } from './intelligence/learning-path.js';
+export { checkNotifications } from './intelligence/notifications.js';
+export type { Notification, NotificationConfig } from './intelligence/notifications.js';
+
+// Multi-Vault
+export { addVault, removeVault, listVaults, getVault, searchAllVaults } from './multi-vault/index.js';
+export type { VaultEntry, CrossVaultSearchResult } from './multi-vault/index.js';
+
+// Voice Capture
+export { captureVoice, transcribeAudio, isWhisperAvailable } from './capture/voice.js';
+export type { CaptureResult, CaptureOptions } from './capture/voice.js';
+
+// Dashboard + PWA
+export { mountDashboard } from './api/dashboard.js';
+export { mountPWA } from './api/pwa.js';
+
+// Agentic Graph
+export { createAgenticGraphTools } from './mcp/tools/agentic-graph.js';
+
+// Cloud
+export { syncToCloud, restoreFromCloud, getSyncState, encrypt, decrypt, getOrCreateEncryptionKey } from './cloud/index.js';
+export type { CloudConfig, SyncResult } from './cloud/index.js';
+
+// Team
+export { inviteMember, authenticateMember, hasPermission, listMembers, removeMember, createAuthMiddleware, loadTeamConfig, generateToken } from './team/index.js';
+export type { TeamMember, TeamRole, TeamConfig } from './team/index.js';
+
+// Pack Marketplace
+export { searchMarketplace, createPackageJson, getPublishInstructions } from './pack/marketplace.js';
+export type { PackListing } from './pack/marketplace.js';
+
+// Federation
+export { FederationNode, FederatedSearch, getOrCreateIdentity } from './federation/index.js';
+export type { PeerInfo, FederatedSearchResult, FederationMessage, NodeIdentity } from './federation/index.js';
+export { vouch, revoke, block, getTrustLevel, isBlocked, listTrusted, computeTrustScore } from './federation/trust.js';
+export { loadSharingConfig, saveSharingConfig, isDocumentShareable, sanitizeSnippet, getSharingSummary, addBlockedTag, removeBlockedTag, addBlockedFolder, blockDocument, unblockDocument } from './federation/sharing.js';
+export type { SharingConfig } from './federation/sharing.js';
+export { computeReputation, verifyConsensus, recordInteraction, recordConsistency, recordFeedback, recordConsensus, getReputationBoard, filterByReputation } from './federation/reputation.js';
+export type { ReputationRecord } from './federation/reputation.js';
+export type { TrustEntry } from './federation/trust.js';
+export { addDPNoise, addDPNoiseNormalized, maskSnippet } from './federation/privacy.js';
+export type { DPConfig } from './federation/privacy.js';
+export { getBalance, getAccount, earn, spend, earnForSearchResponse, spendForSearch, getRecentTransactions } from './federation/credits.js';
+export type { CreditAccount, CreditTransaction } from './federation/credits.js';
+
+// Plugin SDK
+export { PluginManager } from './plugins/index.js';
+export type { StellavaultPlugin, PluginManifest, PluginEvent, PluginContext } from './plugins/index.js';
+export { WebhookManager } from './plugins/webhooks.js';
+export type { WebhookConfig, WebhookDelivery } from './plugins/webhooks.js';
+export { loadCustomTools } from './mcp/custom-tools.js';
+export type { CustomToolDef, LoadedCustomTool } from './mcp/custom-tools.js';
+
+// i18n
+export { t, setLocale, getLocale, detectLocale } from './i18n/index.js';
+export type { Locale } from './i18n/index.js';
+
+// Error Recovery
+export { withRetry, StellavaultError, wrapError, errors } from './utils/retry.js';
+export type { RetryOptions } from './utils/retry.js';
+
+// Factory — 전체 조립
+import { createSqliteVecStore as _createStore } from './store/index.js';
+import { createLocalEmbedder as _createEmbedder } from './indexer/index.js';
+import { createSearchEngine as _createSearch } from './search/index.js';
+import { createMcpServer as _createMcp } from './mcp/index.js';
+
+export function createKnowledgeHub(config: import('./config.js').StellavaultConfig) {
+  const embedder = _createEmbedder(config.embedding.localModel);
+  const dims = embedder.dimensions;
+  const store = _createStore(config.dbPath, dims);
+  const searchEngine = _createSearch({ store, embedder, rrfK: config.search.rrfK });
+  const mcpServer = _createMcp({ store, searchEngine, vaultPath: config.vaultPath });
+
+  return { store, embedder, searchEngine, mcpServer, config };
+}

package/packages/core/src/indexer/chunker.ts

@@ -0,0 +1,180 @@
+// Design Ref: §6.1 — Chunking Strategy (heading 기반 + 오버랩)
+
+import type { Chunk } from '../types/chunk.js';
+
+export interface ChunkOptions {
+  maxTokens: number;   // default: 300
+  overlap: number;     // default: 50
+  minTokens: number;   // default: 50
+}
+
+const DEFAULT_OPTIONS: ChunkOptions = {
+  maxTokens: 300,
+  overlap: 50,
+  minTokens: 50,
+};
+
+/**
+ * 문서를 heading 기반으로 청킹합니다.
+ * Step 1: heading 분할 → Step 2: 길이 검사 → Step 3: 메타데이터 → Step 4: 짧은 청크 병합
+ */
+export function chunkDocument(
+  documentId: string,
+  content: string,
+  options: Partial<ChunkOptions> = {},
+): Chunk[] {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const lines = content.split('\n');
+
+  // Step 1: heading 기반 섹션 분할
+  const sections = splitByHeadings(lines);
+
+  // Step 2-3: 길이 검사 + 메타데이터
+  const rawChunks: Chunk[] = [];
+  for (const section of sections) {
+    const tokenCount = estimateTokens(section.content);
+
+    if (tokenCount <= opts.maxTokens) {
+      rawChunks.push(makeChunk(documentId, rawChunks.length, section));
+    } else {
+      // 긴 섹션은 문장 단위로 재분할 + 오버랩
+      const subChunks = splitByTokenLimit(section, opts.maxTokens, opts.overlap);
+      for (const sub of subChunks) {
+        rawChunks.push(makeChunk(documentId, rawChunks.length, sub));
+      }
+    }
+  }
+
+  // Step 4: 짧은 청크 병합
+  return mergeShortChunks(rawChunks, opts.minTokens);
+}
+
+interface Section {
+  heading: string;
+  content: string;
+  startLine: number;
+  endLine: number;
+}
+
+function splitByHeadings(lines: string[]): Section[] {
+  const sections: Section[] = [];
+  let currentHeading = '';
+  let currentLines: string[] = [];
+  let startLine = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^#{1,6}\s/.test(line)) {
+      if (currentLines.length > 0) {
+        sections.push({
+          heading: currentHeading,
+          content: currentLines.join('\n').trim(),
+          startLine,
+          endLine: i - 1,
+        });
+      }
+      currentHeading = line.replace(/^#{1,6}\s+/, '').trim();
+      currentLines = [line];
+      startLine = i;
+    } else {
+      currentLines.push(line);
+    }
+  }
+
+  if (currentLines.length > 0) {
+    sections.push({
+      heading: currentHeading,
+      content: currentLines.join('\n').trim(),
+      startLine,
+      endLine: lines.length - 1,
+    });
+  }
+
+  return sections.filter(s => s.content.length > 0);
+}
+
+function splitByTokenLimit(section: Section, maxTokens: number, overlap: number): Section[] {
+  const sentences = section.content.split(/(?<=[.!?。]\s)/);
+  const results: Section[] = [];
+  let current: string[] = [];
+  let currentTokens = 0;
+
+  for (const sentence of sentences) {
+    const sentenceTokens = estimateTokens(sentence);
+    if (currentTokens + sentenceTokens > maxTokens && current.length > 0) {
+      results.push({
+        heading: section.heading,
+        content: current.join('').trim(),
+        startLine: section.startLine,
+        endLine: section.endLine,
+      });
+      // 오버랩: 마지막 문장들을 다음 청크에 포함
+      const overlapText = getOverlapText(current, overlap);
+      current = overlapText ? [overlapText, sentence] : [sentence];
+      currentTokens = estimateTokens(current.join(''));
+    } else {
+      current.push(sentence);
+      currentTokens += sentenceTokens;
+    }
+  }
+
+  if (current.length > 0) {
+    results.push({
+      heading: section.heading,
+      content: current.join('').trim(),
+      startLine: section.startLine,
+      endLine: section.endLine,
+    });
+  }
+
+  return results;
+}
+
+function getOverlapText(sentences: string[], overlapTokens: number): string {
+  let tokens = 0;
+  const overlap: string[] = [];
+  for (let i = sentences.length - 1; i >= 0; i--) {
+    const t = estimateTokens(sentences[i]);
+    if (tokens + t > overlapTokens) break;
+    overlap.unshift(sentences[i]);
+    tokens += t;
+  }
+  return overlap.join('');
+}
+
+function mergeShortChunks(chunks: Chunk[], minTokens: number): Chunk[] {
+  if (chunks.length <= 1) return chunks;
+  const result: Chunk[] = [];
+
+  for (const chunk of chunks) {
+    if (result.length > 0 && chunk.tokenCount < minTokens) {
+      const prev = result[result.length - 1];
+      prev.content += '\n\n' + chunk.content;
+      prev.endLine = chunk.endLine;
+      prev.tokenCount += chunk.tokenCount;
+    } else {
+      result.push({ ...chunk });
+    }
+  }
+
+  return result;
+}
+
+function makeChunk(documentId: string, index: number, section: Section): Chunk {
+  return {
+    id: `${documentId}#${index}`,
+    documentId,
+    content: section.content,
+    heading: section.heading,
+    startLine: section.startLine,
+    endLine: section.endLine,
+    tokenCount: estimateTokens(section.content),
+  };
+}
+
+/** 간단한 토큰 수 추정 (영어: ~4chars/token, 한국어: ~2chars/token) */
+export function estimateTokens(text: string): number {
+  const koreanChars = (text.match(/[가-힣]/g) || []).length;
+  const otherChars = text.length - koreanChars;
+  return Math.ceil(koreanChars / 2 + otherChars / 4);
+}

package/packages/core/src/indexer/embedder.ts

@@ -0,0 +1,9 @@
+// Design Ref: §3.2 — 교체 가능 설계 (Embedder 인터페이스)
+
+export interface Embedder {
+  initialize(): Promise<void>;
+  embed(text: string): Promise<number[]>;
+  embedBatch(texts: string[]): Promise<number[][]>;
+  readonly dimensions: number;
+  readonly modelName: string;
+}