@zipbul/gildash 0.6.0 → 0.8.0

package/README.ko.md

@@ -49,7 +49,7 @@ gildash는 TypeScript 코드베이스를 로컬 SQLite 데이터베이스에 인
 bun add @zipbul/gildash
 ```
 
-> **피어 의존성** — [`@zipbul/result`](https://www.npmjs.com/package/@zipbul/result)가 필요합니다. 모든 public 메서드는 `Result<T, GildashError>`를 반환합니다.
+> **선택적 피어 의존성** — `typescript` (>=5.0.0)는 `semantic: true` 사용 시에만 필요합니다.
 
 <br>
 
@@ -57,7 +57,6 @@ bun add @zipbul/gildash
 
 ```ts
 import { Gildash } from '@zipbul/gildash';
-import { isErr } from '@zipbul/result';
 
 // 1. 열기 — 최초 실행 시 전체 .ts 파일 인덱싱, 이후 파일 변경 감시
 const ledger = await Gildash.open({
@@ -65,10 +64,8 @@ const ledger = await Gildash.open({
 });
 
 // 2. 검색 — 이름으로 심볼 찾기
-const result = ledger.searchSymbols({ text: 'UserService', kind: 'class' });
-if (!isErr(result)) {
-  result.forEach(s => console.log(`${s.name} → ${s.filePath}`));
-}
+const symbols = ledger.searchSymbols({ text: 'UserService', kind: 'class' });
+symbols.forEach(s => console.log(`${s.name} → ${s.filePath}`));
 
 // 3. 종료 — 리소스 해제
 await ledger.close();
@@ -201,16 +198,18 @@ await ledger.close({ cleanup: true });   // DB 파일까지 삭제
 
 ## ❌ 에러 처리
 
-모든 public 메서드는 [`@zipbul/result`](https://www.npmjs.com/package/@zipbul/result)의 `Result<T, GildashError>`를 반환합니다. `isErr()`로 에러를 분기합니다:
+public 메서드는 값을 직접 반환하고, 실패 시 `GildashError`를 throw합니다. `instanceof`로 분기합니다:
 
 ```ts
-import { isErr } from '@zipbul/result';
-
-const result = ledger.searchSymbols({ text: 'foo' });
-if (isErr(result)) {
-  console.error(result.data.type, result.data.message);
-} else {
-  console.log(`${result.length}개 심볼 발견`);
+import { Gildash, GildashError } from '@zipbul/gildash';
+
+try {
+  const symbols = ledger.searchSymbols({ text: 'foo' });
+  console.log(`${symbols.length}개 심볼 발견`);
+} catch (e) {
+  if (e instanceof GildashError) {
+    console.error(`[${e.type}] ${e.message}`);
+  }
 }
 ```
 
@@ -230,9 +229,9 @@ if (isErr(result)) {
 | `watchMode` | `boolean` | `true` | `false`이면 파일 워처 비활성화 (스캔 전용 모드) |
 | `semantic` | `boolean` | `false` | tsc TypeChecker 기반 시맨틱 분석 활성화 |
 
-**반환**: `Promise<Gildash>` (`Result`로 래핑됨)
+**반환**: `Promise<Gildash>`. 실패 시 `GildashError`를 throw합니다.
 
-> **참고:** `semantic: true`는 프로젝트 루트에 `tsconfig.json`이 필요합니다. 없으면 `Gildash.open()`이 `GildashError`를 반환합니다.
+> **참고:** `semantic: true`는 프로젝트 루트에 `tsconfig.json`이 필요합니다. 없으면 `Gildash.open()`이 `GildashError`를 throw합니다.
 
 <br>
 
@@ -242,34 +241,34 @@ if (isErr(result)) {
 
 | 메서드 | 반환 타입 | 설명 |
 |--------|-----------|------|
-| `searchSymbols(query)` | `Result<SymbolSearchResult[]>` | FTS5 전문검색 + exact/regex/decorator 필터 |
-| `searchRelations(query)` | `Result<StoredCodeRelation[]>` | 파일, 심볼, 관계 유형 필터 |
-| `searchAllSymbols(query)` | `Result<SymbolSearchResult[]>` | 전체 프로젝트 심볼 검색 |
-| `searchAllRelations(query)` | `Result<StoredCodeRelation[]>` | 전체 프로젝트 관계 검색 |
-| `listIndexedFiles(project?)` | `Result<FileRecord[]>` | 인덱싱된 파일 목록 |
-| `getSymbolsByFile(filePath)` | `Result<SymbolSearchResult[]>` | 단일 파일의 모든 심볼 |
+| `searchSymbols(query)` | `SymbolSearchResult[]` | FTS5 전문검색 + exact/regex/decorator 필터 |
+| `searchRelations(query)` | `StoredCodeRelation[]` | 파일, 심볼, 관계 유형 필터 |
+| `searchAllSymbols(query)` | `SymbolSearchResult[]` | 전체 프로젝트 심볼 검색 |
+| `searchAllRelations(query)` | `StoredCodeRelation[]` | 전체 프로젝트 관계 검색 |
+| `listIndexedFiles(project?)` | `FileRecord[]` | 인덱싱된 파일 목록 |
+| `getSymbolsByFile(filePath)` | `SymbolSearchResult[]` | 단일 파일의 모든 심볼 |
 
 ### 의존성 그래프
 
 | 메서드 | 반환 타입 | 설명 |
 |--------|-----------|------|
-| `getDependencies(filePath)` | `Result<string[]>` | `filePath`가 import하는 파일 목록 |
-| `getDependents(filePath)` | `Result<string[]>` | `filePath`를 import하는 파일 목록 |
-| `getAffected(changedFiles)` | `Promise<Result<string[]>>` | 전이적 영향 범위 |
-| `hasCycle(project?)` | `Promise<Result<boolean>>` | 순환 의존성 감지 |
-| `getCyclePaths(project?, opts?)` | `Promise<Result<string[][]>>` | 모든 순환 경로 (Tarjan SCC + Johnson's). `opts.maxCycles`로 개수 제한 가능. |
-| `getImportGraph(project?)` | `Promise<Result<Map>>` | 전체 인접 리스트 |
-| `getTransitiveDependencies(filePath)` | `Promise<Result<string[]>>` | 전방 전이적 BFS |
+| `getDependencies(filePath)` | `string[]` | `filePath`가 import하는 파일 목록 |
+| `getDependents(filePath)` | `string[]` | `filePath`를 import하는 파일 목록 |
+| `getAffected(changedFiles)` | `Promise<string[]>` | 전이적 영향 범위 |
+| `hasCycle(project?)` | `Promise<boolean>` | 순환 의존성 감지 |
+| `getCyclePaths(project?, opts?)` | `Promise<string[][]>` | 모든 순환 경로 (Tarjan SCC + Johnson's). `opts.maxCycles`로 개수 제한 가능. |
+| `getImportGraph(project?)` | `Promise<Map>` | 전체 인접 리스트 |
+| `getTransitiveDependencies(filePath)` | `Promise<string[]>` | 전방 전이적 BFS |
 
 ### 분석
 
 | 메서드 | 반환 타입 | 설명 |
 |--------|-----------|------|
-| `getFullSymbol(name, filePath)` | `Result<FullSymbol>` | 멤버, jsDoc, 데코레이터, 타입 정보 |
-| `getFileStats(filePath)` | `Result<FileStats>` | 라인 수, 심볼 수, 파일 크기 |
-| `getFanMetrics(filePath)` | `Promise<Result<FanMetrics>>` | fan-in/fan-out 결합도 |
-| `getModuleInterface(filePath)` | `Result<ModuleInterface>` | 공개 export와 메타데이터 |
-| `getInternalRelations(filePath)` | `Result<StoredCodeRelation[]>` | 파일 내부 관계 |
+| `getFullSymbol(name, filePath)` | `FullSymbol \| null` | 멤버, jsDoc, 데코레이터, 타입 정보 |
+| `getFileStats(filePath)` | `FileStats` | 라인 수, 심볼 수, 파일 크기 |
+| `getFanMetrics(filePath)` | `Promise<FanMetrics>` | fan-in/fan-out 결합도 |
+| `getModuleInterface(filePath)` | `ModuleInterface` | 공개 export와 메타데이터 |
+| `getInternalRelations(filePath)` | `StoredCodeRelation[]` | 파일 내부 관계 |
 | `diffSymbols(before, after)` | `SymbolDiff` | 스냅샷 diff (추가/삭제/수정) |
 
 ### 시맨틱 (opt-in)
@@ -278,10 +277,10 @@ if (isErr(result)) {
 
 | 메서드 | 반환 타입 | 설명 |
 |--------|-----------|------|
-| `getResolvedType(name, filePath)` | `Result<ResolvedType \| null>` | tsc TypeChecker로 resolved type 조회 |
-| `getSemanticReferences(name, filePath)` | `Result<SemanticReference[]>` | 심볼의 모든 참조 위치 |
-| `getImplementations(name, filePath)` | `Result<Implementation[]>` | 인터페이스/추상 클래스 구현체 |
-| `getSemanticModuleInterface(filePath)` | `Result<SemanticModuleInterface>` | 모듈 export 목록 + resolved type |
+| `getResolvedType(name, filePath)` | `ResolvedType \| null` | tsc TypeChecker로 resolved type 조회 |
+| `getSemanticReferences(name, filePath)` | `SemanticReference[]` | 심볼의 모든 참조 위치 |
+| `getImplementations(name, filePath)` | `Implementation[]` | 인터페이스/추상 클래스 구현체 |
+| `getSemanticModuleInterface(filePath)` | `SemanticModuleInterface` | 모듈 export 목록 + resolved type |
 
 `getFullSymbol()`은 semantic 활성 시 자동으로 `resolvedType` 필드를 보강합니다.
 `searchSymbols({ resolvedType })`로 resolved type 문자열 기반 필터링이 가능합니다.
@@ -290,25 +289,28 @@ if (isErr(result)) {
 
 | 메서드 | 반환 타입 | 설명 |
 |--------|-----------|------|
-| `findPattern(pattern, opts?)` | `Promise<Result<PatternMatch[]>>` | AST 구조적 검색 (ast-grep) |
-| `resolveSymbol(name, filePath)` | `Result<ResolvedSymbol>` | re-export 체인을 따라 원본 추적 |
-| `getHeritageChain(name, filePath)` | `Promise<Result<HeritageNode>>` | extends/implements 트리 |
-| `batchParse(filePaths, opts?)` | `Promise<Result<Map>>` | 다중 파일 동시 파싱. `opts`: oxc-parser `ParserOptions`. |
+| `findPattern(pattern, opts?)` | `Promise<PatternMatch[]>` | AST 구조적 검색 (ast-grep) |
+| `resolveSymbol(name, filePath)` | `ResolvedSymbol` | re-export 체인을 따라 원본 추적 |
+| `getHeritageChain(name, filePath)` | `Promise<HeritageNode>` | extends/implements 트리 |
+| `batchParse(filePaths, opts?)` | `Promise<BatchParseResult>` | 다중 파일 동시 파싱. `{ parsed, failures }` 반환. `opts`: oxc-parser `ParserOptions`. |
 
 ### 라이프사이클 & 저수준
 
 | 메서드 | 반환 타입 | 설명 |
 |--------|-----------|------|
-| `reindex()` | `Promise<Result<IndexResult>>` | 강제 전체 재인덱싱 (owner만 가능) |
+| `reindex()` | `Promise<IndexResult>` | 강제 전체 재인덱싱 (owner만 가능) |
 | `onIndexed(callback)` | `() => void` | 인덱싱 완료 이벤트 구독 |
-| `parseSource(filePath, src, opts?)` | `Result<ParsedFile>` | 단일 파일 파싱 & 캐시. `opts`: oxc-parser `ParserOptions`. |
-| `extractSymbols(parsed)` | `Result<ExtractedSymbol[]>` | 파싱된 AST에서 심볼 추출 |
-| `extractRelations(parsed)` | `Result<CodeRelation[]>` | 파싱된 AST에서 관계 추출 |
+| `onFileChanged(callback)` | `() => void` | 파일 변경 이벤트 구독 |
+| `onError(callback)` | `() => void` | 에러 이벤트 구독 |
+| `onRoleChanged(callback)` | `() => void` | owner/reader 역할 변경 이벤트 구독 |
+| `parseSource(filePath, src, opts?)` | `ParsedFile` | 단일 파일 파싱 & 캐시. `opts`: oxc-parser `ParserOptions`. |
+| `extractSymbols(parsed)` | `ExtractedSymbol[]` | 파싱된 AST에서 심볼 추출 |
+| `extractRelations(parsed)` | `CodeRelation[]` | 파싱된 AST에서 관계 추출 |
 | `getParsedAst(filePath)` | `ParsedFile \| undefined` | 캐시된 AST 조회 (읽기 전용) |
-| `getFileInfo(filePath)` | `Result<FileRecord \| null>` | 파일 메타데이터 (해시, mtime, 크기) |
-| `getStats(project?)` | `Result<SymbolStats>` | 심볼/파일 통계 |
+| `getFileInfo(filePath)` | `FileRecord \| null` | 파일 메타데이터 (해시, mtime, 크기) |
+| `getStats(project?)` | `SymbolStats` | 심볼/파일 통계 |
 | `projects` | `ProjectBoundary[]` | 탐지된 프로젝트 경계 |
-| `close(opts?)` | `Promise<Result<void>>` | 종료 (`{ cleanup: true }`로 DB 삭제 가능) |
+| `close(opts?)` | `Promise<void>` | 종료 (`{ cleanup: true }`로 DB 삭제 가능) |
 
 <br>
 
@@ -362,10 +364,10 @@ interface IndexResult {
   };
 }
 
-interface GildashError {
-  type: GildashErrorType;
-  message: string;
-  cause?: unknown;
+class GildashError extends Error {
+  readonly type: GildashErrorType;
+  readonly message: string;
+  readonly cause?: unknown;          // Error에서 상속
 }
 ```
 
@@ -408,11 +410,44 @@ Gildash (파사드)
 동일 SQLite DB를 여러 프로세스가 공유할 때, 단일 writer를 보장합니다:
 
 - **Owner** — 파일 워처 실행, 인덱싱 수행, 30초 간격으로 heartbeat 전송
-- **Reader** — 읽기 전용 접근; 60초 간격으로 owner 상태 확인, owner가 stale 상태가 되면 reader 중 하나가 owner로 승격
+- **Reader** — 읽기 전용 접근; 15초 간격으로 owner 상태 확인, owner가 60초 이상 stale 상태이면 reader 중 하나가 owner로 승격
 
 <br>
 
-## ⬆️ 0.5.0에서 업그레이드
+## ⬆️ 업그레이드
+
+### 0.7.x → 0.8.0
+
+**Breaking:** `batchParse()`가 `Map<string, ParsedFile>` 대신 `BatchParseResult` (`parsed` + `failures` 필드)를 반환합니다.
+
+```diff
+- const parsed = await ledger.batchParse(filePaths);
+- const ast = parsed.get('src/app.ts');
++ const { parsed, failures } = await ledger.batchParse(filePaths);
++ const ast = parsed.get('src/app.ts');
++ if (failures.length > 0) console.warn('실패:', failures);
+```
+
+**새 이벤트 메서드:** `onFileChanged()`, `onError()`, `onRoleChanged()`가 `onIndexed()`와 함께 추가되었습니다.
+
+### 0.6.x → 0.7.0
+
+**Breaking:** `@zipbul/result`가 더 이상 public API의 일부가 아닙니다. 모든 메서드가 값을 직접 반환하고, 실패 시 `GildashError`를 throw합니다.
+
+```diff
+- import { isErr } from '@zipbul/result';
+- const result = ledger.searchSymbols({ text: 'foo' });
+- if (isErr(result)) { console.error(result.data.message); }
+- else { console.log(result); }
++ const symbols = ledger.searchSymbols({ text: 'foo' }); // 실패 시 GildashError throw
+```
+
+- `@zipbul/result`를 의존성에서 제거하세요 (더 이상 피어 의존성이 아닙니다)
+- `isErr()` 체크를 `try/catch` + `instanceof GildashError`로 교체하세요
+- `getFullSymbol()`, `getFileInfo()`, `getResolvedType()`은 찾지 못하면 에러 대신 `null`을 반환합니다
+- `resolveSymbol()`은 순환 re-export 시 throw 대신 `{ circular: true }`를 반환합니다
+
+### 0.4.x → 0.5.0
 
 데이터베이스 디렉토리가 `.zipbul/`에서 `.gildash/`로 변경되었습니다. 데이터베이스는 `<projectRoot>/.gildash/gildash.db`에 저장됩니다.
 

package/README.md

@@ -50,7 +50,7 @@ gildash indexes your TypeScript codebase into a local SQLite database, then lets
 bun add @zipbul/gildash
 ```
 
-> **Peer dependency** — [`@zipbul/result`](https://www.npmjs.com/package/@zipbul/result) is required. All public methods return `Result<T, GildashError>`.
+> **Optional peer** — `typescript` (>=5.0.0) is needed only when using `semantic: true`.
 
 <br>
 
@@ -58,7 +58,6 @@ bun add @zipbul/gildash
 
 ```ts
 import { Gildash } from '@zipbul/gildash';
-import { isErr } from '@zipbul/result';
 
 // 1. Open — indexes every .ts file on first run, then watches for changes
 const ledger = await Gildash.open({
@@ -66,10 +65,8 @@ const ledger = await Gildash.open({
 });
 
 // 2. Search — find symbols by name
-const result = ledger.searchSymbols({ text: 'UserService', kind: 'class' });
-if (!isErr(result)) {
-  result.forEach(s => console.log(`${s.name} → ${s.filePath}`));
-}
+const symbols = ledger.searchSymbols({ text: 'UserService', kind: 'class' });
+symbols.forEach(s => console.log(`${s.name} → ${s.filePath}`));
 
 // 3. Close — release resources
 await ledger.close();
@@ -202,16 +199,18 @@ await ledger.close({ cleanup: true });   // delete DB files after use
 
 ## ❌ Error Handling
 
-Every public method returns `Result<T, GildashError>` from [`@zipbul/result`](https://www.npmjs.com/package/@zipbul/result). Use `isErr()` to branch:
+Public methods return values directly and throw `GildashError` on failure. Use `instanceof` to branch:
 
 ```ts
-import { isErr } from '@zipbul/result';
-
-const result = ledger.searchSymbols({ text: 'foo' });
-if (isErr(result)) {
-  console.error(result.data.type, result.data.message);
-} else {
-  console.log(`Found ${result.length} symbols`);
+import { Gildash, GildashError } from '@zipbul/gildash';
+
+try {
+  const symbols = ledger.searchSymbols({ text: 'foo' });
+  console.log(`Found ${symbols.length} symbols`);
+} catch (e) {
+  if (e instanceof GildashError) {
+    console.error(`[${e.type}] ${e.message}`);
+  }
 }
 ```
 
@@ -231,9 +230,9 @@ if (isErr(result)) {
 | `watchMode` | `boolean` | `true` | `false` disables the file watcher (scan-only mode) |
 | `semantic` | `boolean` | `false` | Enable tsc TypeChecker-backed semantic analysis |
 
-Returns `Promise<Gildash>` (wrapped in `Result`).
+Returns `Promise<Gildash>`. Throws `GildashError` on failure.
 
-> **Note:** `semantic: true` requires a `tsconfig.json` in the project root. If not found, `Gildash.open()` returns a `GildashError`.
+> **Note:** `semantic: true` requires a `tsconfig.json` in the project root. If not found, `Gildash.open()` throws a `GildashError`.
 
 <br>
 
@@ -243,34 +242,34 @@ Returns `Promise<Gildash>` (wrapped in `Result`).
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `searchSymbols(query)` | `Result<SymbolSearchResult[]>` | FTS5 full-text + exact / regex / decorator filters |
-| `searchRelations(query)` | `Result<StoredCodeRelation[]>` | Filter by file, symbol, or relation type |
-| `searchAllSymbols(query)` | `Result<SymbolSearchResult[]>` | Cross-project symbol search |
-| `searchAllRelations(query)` | `Result<StoredCodeRelation[]>` | Cross-project relation search |
-| `listIndexedFiles(project?)` | `Result<FileRecord[]>` | All indexed files for a project |
-| `getSymbolsByFile(filePath)` | `Result<SymbolSearchResult[]>` | All symbols in a single file |
+| `searchSymbols(query)` | `SymbolSearchResult[]` | FTS5 full-text + exact / regex / decorator filters |
+| `searchRelations(query)` | `StoredCodeRelation[]` | Filter by file, symbol, or relation type |
+| `searchAllSymbols(query)` | `SymbolSearchResult[]` | Cross-project symbol search |
+| `searchAllRelations(query)` | `StoredCodeRelation[]` | Cross-project relation search |
+| `listIndexedFiles(project?)` | `FileRecord[]` | All indexed files for a project |
+| `getSymbolsByFile(filePath)` | `SymbolSearchResult[]` | All symbols in a single file |
 
 ### Dependency Graph
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `getDependencies(filePath)` | `Result<string[]>` | Files imported by `filePath` |
-| `getDependents(filePath)` | `Result<string[]>` | Files that import `filePath` |
-| `getAffected(changedFiles)` | `Promise<Result<string[]>>` | Transitive impact set |
-| `hasCycle(project?)` | `Promise<Result<boolean>>` | Circular dependency check |
-| `getCyclePaths(project?, opts?)` | `Promise<Result<string[][]>>` | All cycle paths (Tarjan SCC + Johnson's). `opts.maxCycles` limits results. |
-| `getImportGraph(project?)` | `Promise<Result<Map>>` | Full adjacency list |
-| `getTransitiveDependencies(filePath)` | `Promise<Result<string[]>>` | Forward transitive BFS |
+| `getDependencies(filePath)` | `string[]` | Files imported by `filePath` |
+| `getDependents(filePath)` | `string[]` | Files that import `filePath` |
+| `getAffected(changedFiles)` | `Promise<string[]>` | Transitive impact set |
+| `hasCycle(project?)` | `Promise<boolean>` | Circular dependency check |
+| `getCyclePaths(project?, opts?)` | `Promise<string[][]>` | All cycle paths (Tarjan SCC + Johnson's). `opts.maxCycles` limits results. |
+| `getImportGraph(project?)` | `Promise<Map>` | Full adjacency list |
+| `getTransitiveDependencies(filePath)` | `Promise<string[]>` | Forward transitive BFS |
 
 ### Analysis
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `getFullSymbol(name, filePath)` | `Result<FullSymbol>` | Members, jsDoc, decorators, type info |
-| `getFileStats(filePath)` | `Result<FileStats>` | Line count, symbol count, size |
-| `getFanMetrics(filePath)` | `Promise<Result<FanMetrics>>` | Fan-in / fan-out coupling |
-| `getModuleInterface(filePath)` | `Result<ModuleInterface>` | Public exports with metadata |
-| `getInternalRelations(filePath)` | `Result<StoredCodeRelation[]>` | Intra-file relations |
+| `getFullSymbol(name, filePath)` | `FullSymbol \| null` | Members, jsDoc, decorators, type info |
+| `getFileStats(filePath)` | `FileStats` | Line count, symbol count, size |
+| `getFanMetrics(filePath)` | `Promise<FanMetrics>` | Fan-in / fan-out coupling |
+| `getModuleInterface(filePath)` | `ModuleInterface` | Public exports with metadata |
+| `getInternalRelations(filePath)` | `StoredCodeRelation[]` | Intra-file relations |
 | `diffSymbols(before, after)` | `SymbolDiff` | Snapshot diff (added / removed / modified) |
 
 ### Semantic (opt-in)
@@ -279,10 +278,10 @@ Requires `semantic: true` at open time.
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `getResolvedType(name, filePath)` | `Result<ResolvedType \| null>` | Resolved type via tsc TypeChecker |
-| `getSemanticReferences(name, filePath)` | `Result<SemanticReference[]>` | All references to a symbol |
-| `getImplementations(name, filePath)` | `Result<Implementation[]>` | Interface / abstract class implementations |
-| `getSemanticModuleInterface(filePath)` | `Result<SemanticModuleInterface>` | Module exports with resolved types |
+| `getResolvedType(name, filePath)` | `ResolvedType \| null` | Resolved type via tsc TypeChecker |
+| `getSemanticReferences(name, filePath)` | `SemanticReference[]` | All references to a symbol |
+| `getImplementations(name, filePath)` | `Implementation[]` | Interface / abstract class implementations |
+| `getSemanticModuleInterface(filePath)` | `SemanticModuleInterface` | Module exports with resolved types |
 
 `getFullSymbol()` automatically enriches the result with a `resolvedType` field when semantic is enabled.
 `searchSymbols({ resolvedType })` filters symbols by their resolved type string.
@@ -291,25 +290,28 @@ Requires `semantic: true` at open time.
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `findPattern(pattern, opts?)` | `Promise<Result<PatternMatch[]>>` | AST structural search (ast-grep) |
-| `resolveSymbol(name, filePath)` | `Result<ResolvedSymbol>` | Follow re-export chain to original |
-| `getHeritageChain(name, filePath)` | `Promise<Result<HeritageNode>>` | extends / implements tree |
-| `batchParse(filePaths, opts?)` | `Promise<Result<Map>>` | Concurrent multi-file parsing. `opts`: oxc-parser `ParserOptions`. |
+| `findPattern(pattern, opts?)` | `Promise<PatternMatch[]>` | AST structural search (ast-grep) |
+| `resolveSymbol(name, filePath)` | `ResolvedSymbol` | Follow re-export chain to original |
+| `getHeritageChain(name, filePath)` | `Promise<HeritageNode>` | extends / implements tree |
+| `batchParse(filePaths, opts?)` | `Promise<BatchParseResult>` | Concurrent multi-file parsing. Returns `{ parsed, failures }`. `opts`: oxc-parser `ParserOptions`. |
 
 ### Lifecycle & Low-level
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `reindex()` | `Promise<Result<IndexResult>>` | Force full re-index (owner only) |
+| `reindex()` | `Promise<IndexResult>` | Force full re-index (owner only) |
 | `onIndexed(callback)` | `() => void` | Subscribe to index-complete events |
-| `parseSource(filePath, src, opts?)` | `Result<ParsedFile>` | Parse & cache a single file. `opts`: oxc-parser `ParserOptions`. |
-| `extractSymbols(parsed)` | `Result<ExtractedSymbol[]>` | Extract symbols from parsed AST |
-| `extractRelations(parsed)` | `Result<CodeRelation[]>` | Extract relations from parsed AST |
+| `onFileChanged(callback)` | `() => void` | Subscribe to file-change events |
+| `onError(callback)` | `() => void` | Subscribe to error events |
+| `onRoleChanged(callback)` | `() => void` | Subscribe to owner/reader role-change events |
+| `parseSource(filePath, src, opts?)` | `ParsedFile` | Parse & cache a single file. `opts`: oxc-parser `ParserOptions`. |
+| `extractSymbols(parsed)` | `ExtractedSymbol[]` | Extract symbols from parsed AST |
+| `extractRelations(parsed)` | `CodeRelation[]` | Extract relations from parsed AST |
 | `getParsedAst(filePath)` | `ParsedFile \| undefined` | Cached AST lookup (read-only) |
-| `getFileInfo(filePath)` | `Result<FileRecord \| null>` | File metadata (hash, mtime, size) |
-| `getStats(project?)` | `Result<SymbolStats>` | Symbol / file count statistics |
+| `getFileInfo(filePath)` | `FileRecord \| null` | File metadata (hash, mtime, size) |
+| `getStats(project?)` | `SymbolStats` | Symbol / file count statistics |
 | `projects` | `ProjectBoundary[]` | Discovered project boundaries |
-| `close(opts?)` | `Promise<Result<void>>` | Shutdown (pass `{ cleanup: true }` to delete DB) |
+| `close(opts?)` | `Promise<void>` | Shutdown (pass `{ cleanup: true }` to delete DB) |
 
 <br>
 
@@ -433,6 +435,7 @@ interface ResolvedSymbol {
   originalName: string;
   originalFilePath: string;
   reExportChain: Array<{ filePath: string; exportedAs: string }>;
+  circular: boolean;    // true when re-export chain contains a cycle
 }
 
 interface HeritageNode {
@@ -472,10 +475,10 @@ interface FileRecord {
 
 // ── Errors ──────────────────────────────────────────────────────────────
 
-interface GildashError {
-  type: GildashErrorType;   // see Error Types table below
-  message: string;
-  cause?: unknown;
+class GildashError extends Error {
+  readonly type: GildashErrorType;   // see Error Types table below
+  readonly message: string;
+  readonly cause?: unknown;          // inherited from Error
 }
 ```
 
@@ -518,11 +521,44 @@ Gildash (Facade)
 When multiple processes share the same SQLite database, gildash enforces a single-writer guarantee:
 
 - **Owner** — Runs the file watcher, performs indexing, sends a heartbeat every 30 s
-- **Reader** — Read-only access; polls owner health every 60 s and self-promotes if the owner goes stale
+- **Reader** — Read-only access; polls owner health every 15 s and self-promotes if the owner goes stale (60 s threshold)
 
 <br>
 
-## ⬆️ Upgrading from 0.5.0
+## ⬆️ Upgrading
+
+### From 0.7.x to 0.8.0
+
+**Breaking:** `batchParse()` now returns `BatchParseResult` (with `parsed` and `failures` fields) instead of `Map<string, ParsedFile>`.
+
+```diff
+- const parsed = await ledger.batchParse(filePaths);
+- const ast = parsed.get('src/app.ts');
++ const { parsed, failures } = await ledger.batchParse(filePaths);
++ const ast = parsed.get('src/app.ts');
++ if (failures.length > 0) console.warn('Failed:', failures);
+```
+
+**New event methods:** `onFileChanged()`, `onError()`, `onRoleChanged()` added alongside `onIndexed()`.
+
+### From 0.6.x to 0.7.0
+
+**Breaking:** `@zipbul/result` is no longer part of the public API. All methods now return values directly and throw `GildashError` on failure.
+
+```diff
+- import { isErr } from '@zipbul/result';
+- const result = ledger.searchSymbols({ text: 'foo' });
+- if (isErr(result)) { console.error(result.data.message); }
+- else { console.log(result); }
++ const symbols = ledger.searchSymbols({ text: 'foo' }); // throws GildashError
+```
+
+- Remove `@zipbul/result` from your dependencies (no longer a peer dependency)
+- Replace `isErr()` checks with `try/catch` using `instanceof GildashError`
+- `getFullSymbol()`, `getFileInfo()`, `getResolvedType()` return `null` instead of an error when not found
+- `resolveSymbol()` returns `{ circular: true }` for circular re-exports instead of throwing
+
+### From 0.4.x to 0.5.0
 
 The database directory was renamed from `.zipbul/` to `.gildash/`. The database is now stored at `<projectRoot>/.gildash/gildash.db`.