@im-nobsidian/core 0.1.11 → 0.2.0

package/dist/index.d.ts

@@ -129,19 +129,49 @@ declare const ConfigSchema: z.ZodObject<{
     }>;
     advanced: z.ZodObject<{
         concurrency: z.ZodDefault<z.ZodNumber>;
-        maxRetries: z.ZodDefault<z.ZodNumber>;
         timeoutMs: z.ZodDefault<z.ZodNumber>;
+        pageSize: z.ZodDefault<z.ZodNumber>;
         batchSize: z.ZodDefault<z.ZodNumber>;
+        rateLimitIntervalMs: z.ZodDefault<z.ZodNumber>;
+        maxRetries: z.ZodDefault<z.ZodNumber>;
+        retryBaseDelayMs: z.ZodDefault<z.ZodNumber>;
+        retryBackoffFactor: z.ZodDefault<z.ZodNumber>;
+        retryWaitMs: z.ZodDefault<z.ZodNumber>;
+        mediaConcurrency: z.ZodDefault<z.ZodNumber>;
+        mediaMaxRetries: z.ZodDefault<z.ZodNumber>;
+        mediaRetryBaseMs: z.ZodDefault<z.ZodNumber>;
+        fileConcurrency: z.ZodDefault<z.ZodNumber>;
+        maxFileSizeBytes: z.ZodDefault<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         concurrency: number;
-        maxRetries: number;
         timeoutMs: number;
+        pageSize: number;
         batchSize: number;
+        rateLimitIntervalMs: number;
+        maxRetries: number;
+        retryBaseDelayMs: number;
+        retryBackoffFactor: number;
+        retryWaitMs: number;
+        mediaConcurrency: number;
+        mediaMaxRetries: number;
+        mediaRetryBaseMs: number;
+        fileConcurrency: number;
+        maxFileSizeBytes: number;
     }, {
         concurrency?: number | undefined;
-        maxRetries?: number | undefined;
         timeoutMs?: number | undefined;
+        pageSize?: number | undefined;
         batchSize?: number | undefined;
+        rateLimitIntervalMs?: number | undefined;
+        maxRetries?: number | undefined;
+        retryBaseDelayMs?: number | undefined;
+        retryBackoffFactor?: number | undefined;
+        retryWaitMs?: number | undefined;
+        mediaConcurrency?: number | undefined;
+        mediaMaxRetries?: number | undefined;
+        mediaRetryBaseMs?: number | undefined;
+        fileConcurrency?: number | undefined;
+        maxFileSizeBytes?: number | undefined;
     }>;
 }, "strip", z.ZodTypeAny, {
     version: 1;
@@ -180,9 +210,19 @@ declare const ConfigSchema: z.ZodObject<{
     };
     advanced: {
         concurrency: number;
-        maxRetries: number;
         timeoutMs: number;
+        pageSize: number;
         batchSize: number;
+        rateLimitIntervalMs: number;
+        maxRetries: number;
+        retryBaseDelayMs: number;
+        retryBackoffFactor: number;
+        retryWaitMs: number;
+        mediaConcurrency: number;
+        mediaMaxRetries: number;
+        mediaRetryBaseMs: number;
+        fileConcurrency: number;
+        maxFileSizeBytes: number;
     };
 }, {
     version: 1;
@@ -221,9 +261,19 @@ declare const ConfigSchema: z.ZodObject<{
     };
     advanced: {
         concurrency?: number | undefined;
-        maxRetries?: number | undefined;
         timeoutMs?: number | undefined;
+        pageSize?: number | undefined;
         batchSize?: number | undefined;
+        rateLimitIntervalMs?: number | undefined;
+        maxRetries?: number | undefined;
+        retryBaseDelayMs?: number | undefined;
+        retryBackoffFactor?: number | undefined;
+        retryWaitMs?: number | undefined;
+        mediaConcurrency?: number | undefined;
+        mediaMaxRetries?: number | undefined;
+        mediaRetryBaseMs?: number | undefined;
+        fileConcurrency?: number | undefined;
+        maxFileSizeBytes?: number | undefined;
     };
 }>;
 type Config = z.infer<typeof ConfigSchema>;
@@ -279,28 +329,19 @@ interface ProgressItem {
     readonly operation: "create" | "update" | "delete";
 }
 type ProgressCallback = (current: number, total: number, item: ProgressItem) => void;
-interface PushOptions {
-    readonly paths?: string[];
-    readonly excludePaths?: string[];
-    readonly force?: boolean;
-    readonly dryRun?: boolean;
-    readonly onProgress?: ProgressCallback;
-    readonly signal?: AbortSignal;
-}
-interface PullOptions {
+/** push/pull/sync 가 공통으로 받는 동기화 옵션. */
+interface BaseSyncOptions {
     readonly paths?: string[];
     readonly force?: boolean;
     readonly dryRun?: boolean;
     readonly onProgress?: ProgressCallback;
     readonly signal?: AbortSignal;
 }
-interface SyncOptions {
-    readonly paths?: string[];
-    readonly force?: boolean;
-    readonly dryRun?: boolean;
-    readonly onProgress?: ProgressCallback;
-    readonly signal?: AbortSignal;
+interface PushOptions extends BaseSyncOptions {
+    readonly excludePaths?: string[];
 }
+type PullOptions = BaseSyncOptions;
+type SyncOptions = BaseSyncOptions;
 interface PushResult {
     readonly created: number;
     readonly updated: number;
@@ -478,10 +519,14 @@ interface IStateDB {
     setNotionLastEdited(id: string, lastEdited: string): void;
     updateStatCache(id: string, mtime: string, fileSize: number): void;
     setNotionParentId(id: string, parentId: string): void;
+    /** 레코드의 로컬 경로를 갱신한다 (파일 rename/move 추적용). */
+    updatePath(id: string, newPath: string): void;
     delete(id: string): void;
     resolveWikilink(text: string): WikilinkEntry | null;
     resolvePageId(pageId: string): WikilinkEntry | null;
     upsertWikilink(entry: WikilinkEntry): void;
+    /** 레코드 삭제 시 해당 경로의 wikilink 항목을 제거한다 (stale 링크 방지). */
+    deleteWikilink(obsidianPath: string): void;
     getMeta(key: string): string | null;
     setMeta(key: string, value: string): void;
     isFileRegistered(localPath: string): boolean;
@@ -489,6 +534,12 @@ interface IStateDB {
     getFilesByPageId(notionPageId: string): FileRegistryEntry[];
     registerFile(entry: RegisterFileInput): void;
     deleteFileRegistry(localPath: string): void;
+    recordPendingOperation(input: RecordPendingInput): string;
+    getIncompletePendingOperations(): PendingOperation[];
+    getIncompleteOpByState(syncStateId: string, operation: PendingOperation["operation"]): PendingOperation | null;
+    markPendingCompleted(id: string): void;
+    markPendingFailed(id: string, errorMessage: string): void;
+    clearCompletedOperations(): void;
     storePreserveMarkers(path: string, markers: PreserveMarker[]): void;
     getPreserveMarkers(path: string): PreserveMarker[];
     transaction<T>(fn: () => T): T;
@@ -511,10 +562,12 @@ declare class StateDB implements IStateDB {
     setNotionLastEdited(id: string, lastEdited: string): void;
     updateStatCache(id: string, mtime: string, fileSize: number): void;
     setNotionParentId(id: string, parentId: string): void;
+    updatePath(id: string, newPath: string): void;
     delete(id: string): void;
     resolveWikilink(text: string): WikilinkEntry | null;
     resolvePageId(pageId: string): WikilinkEntry | null;
     upsertWikilink(entry: WikilinkEntry): void;
+    deleteWikilink(obsidianPath: string): void;
     getMeta(key: string): string | null;
     setMeta(key: string, value: string): void;
     isFileRegistered(localPath: string): boolean;
@@ -523,6 +576,13 @@ declare class StateDB implements IStateDB {
     registerFile(entry: RegisterFileInput): void;
     deleteFileRegistry(localPath: string): void;
     private mapFileRegistryRow;
+    recordPendingOperation(input: RecordPendingInput): string;
+    getIncompletePendingOperations(): PendingOperation[];
+    getIncompleteOpByState(syncStateId: string, operation: PendingOperation["operation"]): PendingOperation | null;
+    markPendingCompleted(id: string): void;
+    markPendingFailed(id: string, errorMessage: string): void;
+    clearCompletedOperations(): void;
+    private mapPendingRow;
     storePreserveMarkers(path: string, markers: PreserveMarker[]): void;
     getPreserveMarkers(path: string): PreserveMarker[];
     transaction<T>(fn: () => T): T;
@@ -560,20 +620,71 @@ interface RegisterFileInput {
     readonly fileHash: string;
     readonly fileSize: number;
 }
+/** I12 크래시 복구 WAL 항목. push/pull 적용 전 기록되고, 적용 완료 시 completed 로 마감된다. */
+interface PendingOperation {
+    readonly id: string;
+    readonly syncStateId: string;
+    readonly operation: "create" | "update" | "delete" | "move";
+    readonly direction: "push" | "pull";
+    readonly payload: string | null;
+    readonly retryCount: number;
+    readonly errorMessage: string | null;
+    readonly status: "pending" | "processing" | "completed" | "failed";
+    readonly createdAt: string;
+    readonly completedAt: string | null;
+}
+interface RecordPendingInput {
+    readonly syncStateId: string;
+    readonly operation: PendingOperation["operation"];
+    readonly direction: PendingOperation["direction"];
+    readonly payload?: string | null;
+}
+
+type NotionPropertyValue = Record<string, unknown>;
+interface WikilinkResolver$1 {
+    resolve(title: string): string | null;
+    resolvePageId(pageId: string): string | null;
+}
+declare class PropertyMapper {
+    private schema;
+    private wikilinkResolver;
+    setWikilinkResolver(resolver: WikilinkResolver$1): void;
+    loadSchema(properties: Record<string, {
+        id: string;
+        type: string;
+    }>): void;
+    toNotionProperties(frontmatter: Record<string, unknown>, title: string): Record<string, NotionPropertyValue>;
+    fromNotionProperties(notionProps: Record<string, unknown>): Record<string, unknown>;
+    private convertBySchema;
+    private inferAndConvert;
+    private extractValue;
+}
 
 interface NotionClientOptions {
     readonly token: string;
     readonly concurrency?: number;
     readonly timeoutMs?: number;
+    readonly rateLimitIntervalMs?: number;
+    readonly maxRetries?: number;
+    readonly retryBaseDelayMs?: number;
+    readonly retryBackoffFactor?: number;
+    readonly pageSize?: number;
+    readonly batchSize?: number;
     readonly fetch?: typeof globalThis.fetch;
 }
 declare class NotionClient {
     private readonly client;
     private readonly sema;
-    private readonly token;
     private readonly propertyMapper;
-    private readonly customFetch?;
+    private readonly minRequestInterval;
+    private readonly maxRetries;
+    private readonly retryBaseDelayMs;
+    private readonly retryBackoffFactor;
+    private readonly defaultPageSize;
+    private readonly batchSize;
     constructor(options: NotionClientOptions);
+    /** config.advanced 의 운영 튜닝값으로 클라이언트를 생성한다 (매직넘버 단일 진실원). */
+    static fromConfig(config: Config, fetch?: typeof globalThis.fetch): NotionClient;
     getInternalClient(): Client;
     getPage(pageId: string): Promise<PageObjectResponse>;
     createPage(params: {
@@ -599,8 +710,29 @@ declare class NotionClient {
         replaceAll?: boolean;
     }>): Promise<PageMarkdownResponse>;
     movePage(pageId: string, newParentId: string, newParentType: "page" | "database"): Promise<PageObjectResponse>;
-    private fetchDatabaseLegacy;
+    /**
+     * 데이터베이스 1개를 신 모델(2025-09-03 data source 분리)로 조회한다.
+     * - title: database 객체에 그대로 존재한다.
+     * - properties(스키마): 신 모델에선 data source 에 있으므로 1차 data source 를 조회해 채운다.
+     *   data source 접근 불가(링크드 DB 등)면 database 객체의 properties 로 폴백한다(제목은 보존).
+     *
+     * 폐기한 레거시 raw fetch(`GET /v1/databases/{id}`, Notion-Version 2022-06-28)는 신 모델로
+     * 업그레이드된 다수 DB에 400 을 반환해 자동 발견 DB 가 통째 드롭(내용 손실)되던 원인이었다.
+     * SDK(`databases.retrieve`/`dataSources.retrieve`)는 동일 토큰으로 정상 동작한다.
+     */
+    private fetchDatabaseModern;
     getDatabaseTitle(databaseId: string): Promise<string>;
+    /**
+     * 발견된 DB 가 **동기화 가능한지**(접근 가능한 data source 가 있는지) 1회 호출로 판별한다.
+     * 신 모델(2025-09-03)에서 링크드 DB·미공유 데이터 소스·삭제 DB 는 `data_sources` 가
+     * 비어, 행 조회(`dataSources.query`)가 404 로 실패하고 그 전에 생성된 빈 폴더/`.base` 만
+     * 남긴다. 발견 단계에서 미리 걸러 **빈 폴더/.base 오염 + 매 pull 의 404 노이즈**를 차단한다.
+     * 제목은 함께 반환해 호출처가 추가 조회 없이 폴더명을 잡게 한다.
+     */
+    getDatabaseSyncability(databaseId: string): Promise<{
+        title: string;
+        queryable: boolean;
+    }>;
     getDatabaseSchema(databaseId: string): Promise<Record<string, {
         id: string;
         type: string;
@@ -618,6 +750,12 @@ declare class NotionClient {
             optionIds?: string[];
         }>;
     }>>;
+    /** 특정 data source 1개를 직접 쿼리한다(저수준). 다중 data source 순회의 빌딩블록. */
+    private queryDataSource;
+    /**
+     * database 의 1차 data source 1페이지를 쿼리한다(증분 detect 등 단일 소스 경로용).
+     * 전 행을 빠짐없이 받으려면 {@link queryAllDatabasePages} 를 쓴다(전 data source 순회).
+     */
     queryDatabase(databaseId: string, options?: {
         startCursor?: string;
         pageSize?: number;
@@ -626,8 +764,24 @@ declare class NotionClient {
         results: PageObjectResponse[];
         nextCursor: string | null;
     }>;
+    /**
+     * database 의 **모든 data source** 행을 빠짐없이 조회한다(2025-09-03 신 모델).
+     * 한 database 가 2개 이상의 data source(각자 행 집합)를 가질 수 있어, 1차 data source 만
+     * 페이지네이션하면 2번째+ 의 행이 통째 침묵 유실된다. 전 data source 를 순회·페이지네이션
+     * 하고 page_id 로 디듀프(소스 간 동일 페이지 방어)한 뒤 합친다. 다중 소스면 1회 경고해
+     * "소스별 탭 구분이 한 폴더로 병합"되는 점을 비침묵으로 알린다.
+     */
     queryAllDatabasePages(databaseId: string, filter?: unknown): Promise<PageObjectResponse[]>;
+    /** database 의 1차 data source id(없으면 databaseId 폴백). 단일 소스 경로 호환용. */
     getDataSourceId(databaseId: string): Promise<string>;
+    /**
+     * database 의 전 data source 메타(id + 이름)를 반환한다. data source 가 없으면(레거시/단일)
+     * databaseId 자체를 단일 소스로 폴백해 호출처가 항상 ≥1 개를 받게 한다.
+     */
+    getDataSourceMetas(databaseId: string): Promise<Array<{
+        id: string;
+        name: string;
+    }>>;
     archivePage(pageId: string): Promise<void>;
     getFileBlockUrl(blockId: string): Promise<string | null>;
     getBlock(blockId: string): Promise<BlockObjectResponse>;
@@ -661,17 +815,53 @@ declare class NotionClient {
         last_edited_time: string;
     }>>;
     getChildPages(parentId: string): Promise<PageObjectResponse[]>;
+    /** 페이지가 휴지통(in_trash)이거나 보관(archived) 상태인지 판정한다. */
+    private static isTrashedOrArchived;
     getChildDatabaseIds(parentId: string): Promise<string[]>;
-    getChildPagesRecursive(parentId: string): Promise<PageObjectResponse[]>;
+    /**
+     * root 서브트리를 직접 BFS 순회해 하위 페이지를 모두 수집한다(중첩 깊이 무관·무손실).
+     * 비용은 서브트리 전체 블록 수에 비례한다.
+     *
+     * @param opts.deadlineMs `Date.now()` 기준 마감 시각. 각 페이지 처리 전 초과를 검사해
+     *   초과 시 {@link DiscoveryTooLargeError}를 던진다(대규모 서브트리 → search 폴백 유도).
+     *   미지정 시 무제한(기존 동작 유지 — 테스트 mock 경로는 영향 없음).
+     */
+    getChildPagesRecursive(parentId: string, opts?: {
+        deadlineMs?: number;
+    }): Promise<PageObjectResponse[]>;
+    /** 워크스페이스에서 통합에 공유된 모든 페이지를 bulk search 로 열거한다(100/요청). */
+    searchAllPages(): Promise<PageObjectResponse[]>;
+    /**
+     * root 하위 페이지를 **search 기반**으로 디스커버리한다(대규모 서브트리용 폴백).
+     *
+     * 전략: 워크스페이스 전체 페이지를 1회 bulk search 로 열거(비용 ∝ 워크스페이스 페이지 수,
+     * 예측가능·유한)한 뒤, 각 페이지의 부모 체인을 따라 root 도달 여부를 판정한다. page_id
+     * 부모는 메모리 맵으로 추가 호출 없이 즉시 해석하고, block_id 부모(컬럼·토글 등 레이아웃에
+     * 중첩된 페이지)만 getBlock 으로 소유 페이지를 해석(memo)한다. search 는 중첩 깊이와 무관하게
+     * 모든 페이지를 반환하므로 직접 순회와 동일하게 **무손실**이다.
+     *
+     * getChildPagesRecursive 와 동일 집합을 보장하기 위해:
+     *  - DB 행(parent=data_source_id/database_id)은 child_page 로 도달 불가 → 제외
+     *  - 휴지통/보관(in_trash/archived) 페이지 제외
+     *  - root 자신은 제외(직접 순회도 root 의 *자식*부터 수집)
+     */
+    getPagesUnderRootViaSearch(rootId: string): Promise<PageObjectResponse[]>;
     listDatabaseViews(databaseId: string): Promise<ViewConfig[]>;
     getView(viewId: string): Promise<ViewConfig | null>;
     getDatabaseViewsConfig(databaseId: string): Promise<DatabaseViewsConfig>;
     extractCover(page: PageObjectResponse): PageCover | null;
     extractIcon(page: PageObjectResponse): PageIcon | null;
     extractTitle(page: PageObjectResponse): string;
+    /**
+     * 페이지 모드 pull(extractProperties)의 relation/people 속성을 raw Notion UUID 가
+     * 아니라 [[제목]] 위키링크로 해소하도록 resolver 를 주입한다. 주입하지 않으면 매
+     * pull 마다 relation 이 raw UUID 로 재생성돼, 후처리(resolveNotionLinks)에만 의존하는
+     * 2-write churn 이 남는다(M1). DB 모드는 orchestrator/DatabaseSyncer 의 자체 mapper 가
+     * 이미 resolver 를 주입받아 면역이다.
+     */
+    setWikilinkResolver(resolver: WikilinkResolver$1): void;
     extractProperties(page: PageObjectResponse): Record<string, unknown>;
     private lastRequestTime;
-    private readonly minRequestInterval;
     private withRateLimit;
     private executeWithRetry;
 }
@@ -780,26 +970,6 @@ declare class NotionBlockBuilder {
     static table(rows: string[][], hasColumnHeader?: boolean, hasRowHeader?: boolean): NotionBlock;
 }
 
-type NotionPropertyValue = Record<string, unknown>;
-interface WikilinkResolver$1 {
-    resolve(title: string): string | null;
-    resolvePageId(pageId: string): string | null;
-}
-declare class PropertyMapper {
-    private schema;
-    private wikilinkResolver;
-    setWikilinkResolver(resolver: WikilinkResolver$1): void;
-    loadSchema(properties: Record<string, {
-        id: string;
-        type: string;
-    }>): void;
-    toNotionProperties(frontmatter: Record<string, unknown>, title: string): Record<string, NotionPropertyValue>;
-    fromNotionProperties(notionProps: Record<string, unknown>): Record<string, unknown>;
-    private convertBySchema;
-    private inferAndConvert;
-    private extractValue;
-}
-
 interface FileInfo {
     readonly path: string;
     readonly content: string;
@@ -838,6 +1008,27 @@ interface VaultFS {
     getFileStat(path: string): Promise<FileStatInfo | null>;
 }
 
+type ResolutionChoice = "local" | "remote" | "merge" | "duplicate";
+interface ResolutionResult {
+    readonly path: string;
+    readonly choice: ResolutionChoice;
+    readonly success: boolean;
+    readonly mergeHadConflicts?: boolean;
+}
+declare class ConflictResolver {
+    private readonly stateDb;
+    private readonly vaultFs;
+    constructor(stateDb: IStateDB, vaultFs: VaultFS);
+    resolve(conflict: Conflict, choice: ResolutionChoice): Promise<ResolutionResult>;
+    resolveByStrategy(conflict: Conflict, strategy: ConflictStrategy): Promise<ResolutionResult>;
+    resolveAll(conflicts: Conflict[], strategy: ConflictStrategy): Promise<ResolutionResult[]>;
+    private resolveLocal;
+    private resolveRemote;
+    private resolveMerge;
+    private resolveDuplicate;
+    generateDiff(conflict: Conflict): string;
+}
+
 declare class SyncOrchestrator {
     private readonly config;
     private readonly stateDb;
@@ -850,9 +1041,13 @@ declare class SyncOrchestrator {
     private readonly fileHandler;
     private readonly databaseSyncer;
     private readonly propertyMapper;
+    private readonly conflictResolver;
     private dbSchemaLoaded;
     private _pullImageCount;
     private _pullFileCount;
+    private _inlineDbRefs;
+    private _childParentIds;
+    private static readonly DISCOVERY_RECURSIVE_BUDGET_MS;
     constructor(config: Config, stateDb: IStateDB, notionClient: NotionClient, vaultFs: VaultFS, customFetch?: typeof globalThis.fetch);
     push(options?: PushOptions): Promise<PushResult>;
     pull(options?: PullOptions): Promise<PullResult>;
@@ -868,17 +1063,65 @@ declare class SyncOrchestrator {
     private buildConflictsFromRecords;
     private get isDatabaseMode();
     private discoverChildDatabases;
+    /**
+     * 자동 발견된 child_database 1개를 DatabaseSyncer 설정으로 변환한다.
+     * 블록 스캔/markdown 양쪽 발견 경로에서 공통으로 사용한다.
+     * - localFolder: 부모 페이지의 obsidianPath 기준으로 폴더를 잡아 원본 중첩 구조를 보존
+     *   (예: 부모 "AI Engineer (1).md" + DB "Minirecord Project" → "AI Engineer (1)/Minirecord-Project")
+     * - 제목 취득 실패 시 부모 폴더명 기반 안전 이름으로 폴백
+     */
+    private buildDiscoveredDbConfig;
+    /** 접근 불가 DB denylist 를 상태 메타에서 로드한다(하이픈 정규화). */
+    private loadInaccessibleDbIds;
     private pullDiscoveredDatabases;
     private resolveNotionLinks;
     private ensureDbSchema;
     private pushCreate;
     private pushUpdate;
+    /** 단일 충돌을 사용자가 고른 선택지(local/remote/merge/duplicate)로 해소 + Notion 전파. */
+    resolveConflict(conflict: Conflict, choice: ResolutionChoice): Promise<ResolutionResult>;
+    /** 단일 충돌을 전략(manual/local-first/remote-first/duplicate)으로 해소 + Notion 전파. */
+    resolveConflictByStrategy(conflict: Conflict, strategy: ConflictStrategy): Promise<ResolutionResult>;
+    /** 여러 충돌을 동일 전략으로 일괄 해소 + Notion 전파. */
+    resolveAllConflicts(conflicts: Conflict[], strategy: ConflictStrategy): Promise<ResolutionResult[]>;
+    /** 충돌 미리보기용 통합 diff(원본 vs 로컬 vs 원격). 해소 없이 표시 전용. */
+    generateConflictDiff(conflict: Conflict): string;
+    /**
+     * 해소 결과를 Notion 으로 전파해 로컬↔원격 일관성을 봉합한다.
+     * - remote 선택: 로컬이 원격으로 갱신됐을 뿐이므로 push 불필요. notionLastEdited 만
+     *   원격 변경의 lastEdited 로 재조정 → 다음 pull 이 같은 변경을 재충돌로 보지 않음.
+     * - merge 실패(충돌 마커 잔존): 사용자가 직접 풀어야 하므로 conflict 상태 유지·push 안 함.
+     * - local / merge(성공) / duplicate: 해소된 로컬 내용을 Notion 에 재push(pushUpdate 가
+     *   변환·이미지·속성·해시·notionLastEdited 를 한 트랜잭션으로 재조정) → 무손실 수렴.
+     */
+    private propagateResolution;
     private pushDelete;
     private pushMove;
     private detectRemoteChanges;
+    /**
+     * 증분 원격 변경 감지 — `since` 이후 수정된 페이지만 search 로 받아 created/modified 만
+     * 만든다. **삭제는 의도적으로 감지하지 않는다**: search API 는 in_trash/archived 페이지를
+     * 반환하지 않아(=사라진 것을 증분만으로는 구분 불가) 삭제 판정에는 전체 enumeration 이
+     * 필수다. 따라서 호출부는 `deleteSync` 가 켜진 경우 이 fast-path 를 쓰지 않고
+     * `detectRemoteChanges`(전체 스캔, 삭제 diff 포함)로 우회한다. (I10)
+     */
     private detectRemoteChangesIncremental;
     private isTrackedParent;
     private pullCreate;
+    /**
+     * 페이지가 폴더(자식 페이지·자식 DB 보유)인지 신뢰성 있게 판정한다.
+     *
+     * 결함(폴더노트 본문분리)의 근본 원인은 얕은 판정이었다 — 최상위 블록 첫 페이지에서
+     * child_page 만 검사하면 callout·column·toggle 안에 중첩된 자식 페이지나 child_database 를
+     * 놓쳐 폴더노트가 file 로 오분류되고, 본문이 폴더 밖 최상위로 밀려 resolveUniqueFilePath
+     * 충돌(' (1).md')로 쪼개졌다.
+     *
+     * 1차: 발견 단계(서브트리 순회/증분)에서 전 페이지의 부모를 해소하며 만든
+     *      _childParentIds 집합으로 O(1) 판정(추가 API 호출 0, 처리 순서 무관) — 전체 pull 경로.
+     * 폴백: 집합에 없을 때만(증분 pull 의 신규 폴더 등) fetchAllChildrenDeep 로 컨테이너를
+     *       재귀 탐색해 child_page·child_database 를 직접 확인한다.
+     */
+    private pageHasChildContainers;
     private pullUpdate;
     private pullDelete;
     private ensureFolderPage;
@@ -887,11 +1130,32 @@ declare class SyncOrchestrator {
     private isFolderNote;
     private resolveParentPath;
     private pushCreatePage;
+    private pageHasLiveChildren;
     private pushUpdatePage;
     private fetchPageMarkdown;
+    private collectInlineDbRefs;
+    private resolveNotionIdWikilinks;
     private extractParentId;
     private resolveBlockToPageId;
     private cleanupInterruptedSync;
+    /**
+     * I12 — 중단된 push create 작업 재개.
+     *
+     * pending_operations 에 미완료(create·push) 항목이 있으면:
+     *  - state 에 notion_page_id 가 이미 있으면 → 생성·매핑까지는 끝났고 markCompleted 직전에
+     *    중단된 것 → 완료 처리(잔여 본문/이미지는 다음 변경감지가 pushUpdate 로 마무리).
+     *  - notion_page_id 가 비어 있으면(Window A: 생성 적용됐으나 매핑 기록 전 중단) → 부모에서
+     *    제목으로 child_page 를 검색해 고아 페이지를 입양(중복 생성 차단). 없으면 자리표시
+     *    레코드를 제거(FK CASCADE 로 op 도 삭제)해 다음 push 가 새로 생성하게 한다.
+     *
+     * 한계(문서화): Notion 은 idempotency key 가 없어 "생성 요청 적용 직후 같은 호출 내 재시도"
+     * 로 인한 중복은 완전히 차단하지 못한다. 429 는 적용 전 거절이라 안전하고, 프로세스 재시작
+     * 후 재개는 본 검색-입양으로 중복을 막는다. DB 모드(부모가 database)는 child_page 검색이
+     * 불가하므로 자리표시 제거 후 재생성으로 폴백한다.
+     */
+    private recoverInterruptedPushOps;
+    /** 부모 페이지의 직속 자식 중 제목이 일치하는(보관/휴지통 제외) child_page id 를 찾는다. */
+    private findChildPageByTitle;
     private resolveUniqueFilePath;
 }
 
@@ -924,6 +1188,13 @@ declare class NodeVaultFS implements VaultFS {
     private walkDir;
 }
 
+/** 미디어(이미지/파일) 다운로드 운영 튜닝값. 미지정 시 기존 동작과 동일한 기본값 사용. */
+interface MediaOptions {
+    readonly concurrency?: number;
+    readonly maxRetries?: number;
+    readonly retryBaseMs?: number;
+    readonly maxFileSizeBytes?: number;
+}
 interface ImageDownloadResult {
     readonly originalUrl: string;
     readonly localPath: string;
@@ -933,13 +1204,21 @@ interface ImageDownloadResult {
 interface ImageUploadResult {
     readonly localPath: string;
     readonly fileUploadId: string;
+    /** 업로드한 이미지의 전체 sha256 — file_registry 비교 키(FileHandler 와 동일 산식). */
+    readonly fileHash: string;
+    readonly fileSize: number;
 }
 declare class ImageHandler {
     private readonly vaultFs;
     private readonly attachmentFolder;
     private readonly notionClient?;
+    private readonly stateDb?;
     private readonly customFetch?;
-    constructor(vaultFs: VaultFS, attachmentFolder?: string, notionClient?: NotionClient | undefined, customFetch?: typeof globalThis.fetch);
+    private readonly concurrency;
+    private readonly maxRetries;
+    private readonly retryBaseMs;
+    private readonly maxFileSizeBytes;
+    constructor(vaultFs: VaultFS, attachmentFolder?: string, notionClient?: NotionClient | undefined, customFetch?: typeof globalThis.fetch, options?: MediaOptions, stateDb?: IStateDB | undefined);
     private get fetchFn();
     downloadImage(url: string, pageTitle: string): Promise<ImageDownloadResult>;
     downloadAllImages(markdown: string, pageTitle: string): Promise<{
@@ -979,7 +1258,7 @@ declare class FileHandler {
     private readonly notionClient;
     private readonly stateDb;
     private readonly sema;
-    constructor(vaultFs: VaultFS, notionClient: NotionClient, stateDb: IStateDB);
+    constructor(vaultFs: VaultFS, notionClient: NotionClient, stateDb: IStateDB, concurrency?: number);
     pushFilesForFolder(folderPageId: string, folderPath: string): Promise<FileUploadResult[]>;
     pushAllFiles(): Promise<FileUploadResult[]>;
     downloadFileBlock(url: string, filename: string, targetFolder: string): Promise<FileDownloadResult>;
@@ -1006,7 +1285,16 @@ declare class ConversionPipeline {
 interface DatabaseSyncResult {
     created: number;
     updated: number;
+    /** Pull 시 로컬·리모트 동시 수정으로 발생한 충돌 (push 는 항상 빈 배열). */
+    conflicts: Conflict[];
     failed: FailedOperation[];
+    /**
+     * 이번 pull 에서 실제로 디스크에 기록한 db-row 파일 경로(SSOT).
+     * 오케스트레이터의 링크 해소(resolveNotionLinks) 대상은 반드시 이 목록으로 정한다 —
+     * 과거의 `getByStatus("synced").slice(-N)` 휴리스틱은 ORDER BY 가 없어 증분 pull 에서
+     * 엉뚱한 행을 골라 정작 바뀐 행의 relation UUID 를 영영 해소하지 못했다(M3). push 경로는 항상 빈 배열.
+     */
+    writtenPaths: string[];
 }
 declare class DatabaseSyncer {
     private readonly config;
@@ -1017,14 +1305,33 @@ declare class DatabaseSyncer {
     private readonly imageHandler;
     private readonly propertyMapper;
     private readonly baseFileGenerator;
+    private readonly sidecarGenerator;
     constructor(config: Config, stateDb: IStateDB, notionClient: NotionClient, vaultFs: VaultFS, pipeline: ConversionPipeline, imageHandler: ImageHandler);
     pullAll(): Promise<DatabaseSyncResult>;
     pushAll(): Promise<DatabaseSyncResult>;
     pullDatabase(dbConfig: DatabaseSyncConfig): Promise<DatabaseSyncResult>;
     private pullDatabaseViews;
     private generateBaseFile;
+    /**
+     * DB 제목이 바뀌면 `.base`/`.notion.json` 파일명(safeName)이 바뀌어 옛 이름의 산출물이
+     * 같은 폴더에 고아로 잔존한다(drift·부활 원인). DB 폴더 **직속**의 산출물 중 현재 이름이
+     * 아닌 것을 삭제해 멱등을 보장한다. 하위 폴더(중첩 DB)의 산출물은 보호한다.
+     */
+    private cleanupStaleDbArtifacts;
+    /**
+     * `.base` 가 표현하지 못하는 Notion DB 메타데이터(미지원 뷰·필터식·커버크기 등)를
+     * 사이드카 `<db>.notion.json` 으로 무손실 보존하고, degrade 된 항목을 정직하게 로그한다.
+     * 결정적 직렬화라 동일 DB 상태 → 동일 바이트 → 멱등(drift/churn 0).
+     */
+    private generateSidecar;
     private pullDatabasePage;
     private pushDatabase;
+    /**
+     * rename 감지를 위한 고아 레코드 인덱스(내용 해시 → 레코드)를 만든다.
+     * 고아 = 해당 DB 소속 db-row 레코드 중 로컬 파일이 더 이상 존재하지 않는(livePaths 에 없는) 것.
+     * 같은 해시가 여러 고아에 걸리면 첫 항목을 유지한다(희박한 케이스).
+     */
+    private buildOrphanHashIndex;
 }
 
 declare class BlockConverter {
@@ -1032,6 +1339,19 @@ declare class BlockConverter {
     private client;
     initNotionToMd(client: Client): void;
     private registerCustomTransformers;
+    /**
+     * `numbered_list_item` 을 `1.` 마크다운으로 내보내 **번호 목록 타입을 보존**한다(I2 블록 라운드트립).
+     *
+     * notion-to-md 기본 렌더는 `md.bullet(text, block.numbered_list_item.number)` 를 쓰는데
+     * Notion API 는 list item 에 `.number` 를 채워주지 않아 `undefined` → 불릿(`- `)으로 **강등**된다.
+     * 그러면 블록 폴백 경로(notionBlocksToMarkdown)로 pull 한 뒤 다시 push 하면 numbered_list_item 이
+     * bulleted_list_item 으로 **타입 유실**된다(기본 markdown-api 경로는 영향 없음).
+     *
+     * 항상 `1.` 로 내보내면 마크다운이 시각적으로 자동 재번호하므로 표시는 동일하고, martian 이 다시
+     * numbered_list_item 으로 파싱해 타입이 보존된다. 커스텀 트랜스포머 등록은 notion-to-md 의 기본
+     * 자식 처리를 끄므로(라이브러리 설계), 자식은 toggle/callout 과 동일하게 직접 fetch·들여쓰기한다.
+     */
+    private registerNumberedListTransformer;
     private registerToggleTransformer;
     private registerToggleHeadingTransformers;
     private registerColumnTransformer;
@@ -1055,6 +1375,14 @@ declare class BlockConverter {
     private toggleCounter;
     private columnCounter;
     private preProcessMarkdown;
+    /**
+     * compact underline/color 보존마커를 평문으로 강등 — block(martian) 폴백 경로 전용.
+     *
+     * 무손실 underline/color 복원은 기본 경로인 Markdown API({@link obsidianToNotionEnhanced})가
+     * 전담한다. martian 은 이 서식을 표현할 수 없으므로, Markdown API 가 실패해 이 폴백을 탈 때는
+     * 마커 텍스트가 본문에 리터럴로 새지 않도록 텍스트만 남기고 마커를 제거한다(서식 degrade).
+     */
+    private stripInlineAnnotationMarkers;
     private replaceDividers;
     private extractToggleBlocks;
     private extractColumnBlocks;
@@ -1062,9 +1390,41 @@ declare class BlockConverter {
     private convertTogglePlaceholder;
     private convertColumnPlaceholder;
     private convertDividerPlaceholder;
+    /**
+     * 단일 라인 보존 마커(목차·breadcrumb)를 원래 블록으로 복원한다.
+     * pull 시 마크다운 표현이 없는 블록을 `%%im-nobsidian:toc%%` /
+     * `%%im-nobsidian:breadcrumb%%` 마커 문단으로 남겨두므로, push 시 이 문단을
+     * 감지해 table_of_contents / breadcrumb 블록으로 되돌린다. 그러지 않으면
+     * 마커 텍스트가 일반 문단으로 Notion 에 기록되는 잠재 손실이 된다.
+     */
+    private convertSingleLineMarker;
     private convertImageToVideoOrEmbed;
+    /**
+     * `@tryfabric/martian` 의 blockquote 표현을 **평탄화**한다(I2/I3 무손실 push).
+     *
+     * martian 의 parseBlockquote 는 `notion.blockquote([], children)` 로 본문을 quote 의
+     * **자식 paragraph** 로 내려보내고 quote.rich_text 를 비운다(라이브러리 설계). 그 결과
+     * `> 인용문` 을 push 하면 Notion 에 "빈 인용 줄 + 들여쓴 자식 문단"이 만들어지고, 다시
+     * pull 하면 `> `(빈 줄) 아래에 자식 문단이 매달려 **원문과 구조가 갈라진다**(라운드트립 손실).
+     * 또한 quote.rich_text[0] 이 항상 비어 callout 이모지 감지({@link convertQuoteToCallout})도
+     * 무력화됐다.
+     *
+     * 선두의 연속된 paragraph 자식을 quote.rich_text 로 끌어올리고(문단 사이는 줄바꿈 rich_text
+     * 로 연결 — Notion 네이티브 멀티라인 인용 표현), paragraph 가 아닌 자식(중첩 리스트 등)은
+     * children 으로 남겨 구조를 보존한다. 이미 rich_text 에 본문이 있거나 끌어올릴 paragraph 가
+     * 없으면 원본을 그대로 반환한다(안전 no-op).
+     */
+    private flattenMartianBlockquote;
     private convertQuoteToCallout;
     notionBlocksToMarkdown(pageId: string): Promise<string>;
+    /**
+     * **in-memory** 블록 배열을 마크다운으로 변환한다(페이지 fetch 없음). notion-to-md 의
+     * blocksToMarkdown 을 직접 호출하므로, `has_children:false` 인 평면 블록은 Notion 클라이언트를
+     * 전혀 건드리지 않는다 → 고정 픽스처로 **오프라인 결정론** 블록 라운드트립(I2)을 잠글 수 있는
+     * 정식 테스트 시임. children 이 있는 블록(table 행·callout 자식 등)은 클라이언트를 호출하므로
+     * 호출 측이 평면 블록만 넣어야 오프라인이 보장된다.
+     */
+    notionBlockArrayToMarkdown(blocks: Array<Record<string, unknown>>): Promise<string>;
 }
 
 declare class FrontmatterExtractor implements Processor {
@@ -1124,8 +1484,26 @@ declare class PropertiesTableInjector implements Processor {
     process(input: ProcessorInput): ProcessorOutput;
 }
 
-declare class HtmlAnnotationStripper implements Processor {
-    readonly name = "HtmlAnnotationStripper";
+/**
+ * 인라인 annotation(underline·color) 무손실 보존기 — push 전처리(order 5).
+ *
+ * 과거에는 underline/color 표기를 **제거**(strip)했으나, 그러면 Notion 으로 push 할 때
+ * 서식이 영구 소실됐다(I3 손실점). Notion 의 Enhanced Markdown 은 underline/color 를
+ * `<span underline="true">` / `<span color="X">` 로 **무손실 표현**하므로, 여기서는 제거 대신
+ * 프로젝트 정본인 **compact 보존마커**(`%%im-nobsidian:underline%%…%%/underline%%`,
+ * `%%im-nobsidian:color:C%%…%%/color%%`)로 **승격**만 한다. 실제 Notion span 복원은
+ * push 직전 단일 SSOT 인 {@link obsidianToNotionEnhanced} 가 담당한다.
+ *
+ * 입력 표기는 pull 경로별로 다르다.
+ * - Markdown API 경로: 이미 compact 마커 → 무변경 통과(여기 정규식에 걸리지 않음).
+ * - notion-to-md(block) 경로: `<u>` + 공백형 색상 마커 → compact 마커로 정규화.
+ * - 사용자가 직접 작성한 `<u>` / 레거시 `<span class="notion-*">` → compact 마커로 승격.
+ *
+ * compact 마커는 공백이 없어 PreserveMarkerCollector(공백형만 수집)·기타 전처리기를
+ * 무손상 통과한다(기존 underline/color 왕복이 이를 실증).
+ */
+declare class InlineAnnotationPreserver implements Processor {
+    readonly name = "InlineAnnotationPreserver";
     readonly order = 5;
     process(input: ProcessorInput): ProcessorOutput;
 }
@@ -1184,29 +1562,26 @@ interface MergeConflictRegion {
     readonly localLines: string[];
     readonly remoteLines: string[];
 }
+/**
+ * 3-way 병합 (diff3). base 를 공통 조상으로 보고 local/remote 의 변경을 합친다.
+ *
+ * 표준 diff3 알고리즘:
+ *   1. base↔local, base↔remote 각각의 LCS 로 "변경 조각(hunk)"을 추출한다.
+ *      (hunk = base 의 어떤 구간 [baseStart, baseEnd) 을 새 내용으로 치환·삭제·삽입)
+ *   2. 모든 hunk 를 base 위치순으로 정렬하고, **base 구간이 겹치는** hunk 들을
+ *      하나의 region 으로 묶는다. 겹치지 않는 hunk 사이의 base 줄은 양쪽 공통이므로 그대로 출력.
+ *   3. 각 region 에서 local/remote 가 만들어낸 내용을 비교해 판정한다.
+ *      - local 결과 == base       → local 미변경 → remote 채택
+ *      - remote 결과 == base      → remote 미변경 → local 채택
+ *      - local 결과 == remote 결과 → 동일 변경 → 한쪽 채택
+ *      - 그 외                     → 충돌 (양쪽이 같은 구간을 다르게 변경)
+ *
+ * 핵심은 hunk 의 base 구간이 **실제로 겹칠 때만** 충돌로 본다는 점이다. 서로 다른(인접
+ * 포함) 줄을 고친 삽입·삭제·수정은 충돌 없이 합쳐진다. (이전 단순 라인-치환 구현은
+ * 삽입/삭제를 오정렬해 거짓 충돌을 만들거나 무한 루프에 빠질 수 있었다.)
+ */
 declare function threeWayMerge(base: string, local: string, remote: string): MergeResult;
 
-type ResolutionChoice = "local" | "remote" | "merge" | "duplicate";
-interface ResolutionResult {
-    readonly path: string;
-    readonly choice: ResolutionChoice;
-    readonly success: boolean;
-    readonly mergeHadConflicts?: boolean;
-}
-declare class ConflictResolver {
-    private readonly stateDb;
-    private readonly vaultFs;
-    constructor(stateDb: IStateDB, vaultFs: VaultFS);
-    resolve(conflict: Conflict, choice: ResolutionChoice): Promise<ResolutionResult>;
-    resolveByStrategy(conflict: Conflict, strategy: ConflictStrategy): Promise<ResolutionResult>;
-    resolveAll(conflicts: Conflict[], strategy: ConflictStrategy): Promise<ResolutionResult[]>;
-    private resolveLocal;
-    private resolveRemote;
-    private resolveMerge;
-    private resolveDuplicate;
-    generateDiff(conflict: Conflict): string;
-}
-
 interface NotionPageNode {
     readonly id: string;
     readonly title: string;
@@ -1260,12 +1635,12 @@ declare class FileWatcher {
     private watcher;
     constructor(rootPath: string, callback: WatchCallback);
     start(): void;
+    private toVaultPath;
     stop(): Promise<void>;
 }
 
 interface WatchSyncOptions {
     readonly debounceMs?: number;
-    readonly syncDirection?: "push" | "pull" | "both";
     readonly onSyncStart?: () => void;
     readonly onSyncComplete?: (result: SyncResult) => void;
     readonly onSyncError?: (error: Error) => void;
@@ -1376,6 +1751,18 @@ interface BaseFileOptions {
     readonly viewsConfig: DatabaseViewsConfig;
     readonly folderPath: string;
 }
+type BasesViewType = "table" | "cards" | "list";
+/**
+ * Notion 뷰 타입 → Obsidian Bases 뷰 타입 매핑(SSOT).
+ *
+ * `null` = Bases 에 대응 뷰가 없어 `.base` 로 표현 불가. 이 경우 해당 뷰는 `.base` 에서
+ * 누락되므로, 사이드카(`<db>.notion.json`)가 원본 뷰 설정을 무손실 보존한다
+ * (Notion API 는 뷰 생성/수정을 지원하지 않아 뷰는 pull-authoritative — push 로 되돌릴 수
+ * 없으므로 "조용한 유실 금지"는 곧 "보존 + 정직한 degrade 리포트"를 의미한다).
+ */
+declare const NOTION_TO_BASES_VIEW: Record<string, BasesViewType | null>;
+/** Notion 뷰 타입의 Bases 대응 타입을 돌려준다. 미지원/미상 타입은 `null`. */
+declare function basesViewTypeOf(notionType: string): BasesViewType | null;
 declare class BaseFileGenerator {
     generate(options: BaseFileOptions): string;
     private writeFilters;
@@ -1383,13 +1770,104 @@ declare class BaseFileGenerator {
     private writeFormulas;
     private writePropertyDisplayNames;
     private writeViews;
+    /**
+     * 뷰 이름을 Bases 요구사항대로 유일화한다(in-place). 동명 충돌 시 ' 2',' 3'… 를 붙이되
+     * 이미 존재하는 이름과 다시 충돌하지 않을 때까지 증가시킨다.
+     */
+    private dedupeViewNames;
     private convertView;
     private toNoteRef;
+    /**
+     * 속성 참조(order/sort/groupBy/image)를 YAML로 안전하게 출력한다.
+     * `file.name`·`formula.coverImage`·`note.cover` 같은 접두사 식별자와 공백 포함 일반 속성명은
+     * 평문 스칼라로 안전하므로 그대로 두고, 콜론·해시·따옴표 등 YAML 메타문자가 있을 때만 인용한다.
+     */
+    private propRef;
     private resolvePropertyName;
+    private decodeId;
     private yamlKey;
     private yamlValue;
 }
 
+/**
+ * DB 사이드카(`<db>.notion.json`) — `.base` 로 표현할 수 없는 Notion DB 메타데이터를
+ * 무손실 보존하는 단일 파일.
+ *
+ * ## 왜 필요한가 (I4·I7 "조용한 유실 금지")
+ *
+ * Obsidian Bases(`.base`)는 Notion DB 뷰의 일부만 표현한다:
+ *   · 미지원 뷰(calendar/timeline/form/chart/map/dashboard)는 `.base` 에서 통째 누락.
+ *   · 표현되는 뷰도 Notion **필터식·커버 크기/비율·컬럼 width/wrap·빈그룹 숨김** 등은
+ *     Bases 문법에 대응이 없어 손실된다.
+ *
+ * Notion API 는 뷰 생성/수정을 지원하지 않으므로(뷰는 pull-authoritative) 이 메타데이터는
+ * push 로 Notion 에 되돌릴 수 없다. 따라서 "무손실"의 의미는 **로컬에 완전·정직하게
+ * 보존하고, 무엇이 degrade 됐는지 명시 리포트**하는 것이다. 사이드카는 이를 `.base` 와
+ * 같은 폴더에 co-locate 해 사람이 발견 가능하고 도구가 재사용 가능하게 만든다.
+ *
+ * ## 멱등성
+ *
+ * 매 pull 마다 재생성되므로 **결정적**이어야 한다(타임스탬프·실행시각 금지, 키 정렬).
+ * 동일 DB 상태 → 동일 바이트 → drift 0 / churn 0.
+ */
+interface NotionSidecar {
+    readonly generator: "im-nobsidian";
+    readonly schemaVersion: 1;
+    readonly databaseId: string;
+    readonly databaseName: string;
+    /** 속성 스키마 — 이름 정렬. `.base` displayName 만으로는 잃는 타입/옵션을 보존. */
+    readonly properties: SidecarProperty[];
+    /** 모든 뷰(표현/미표현 공통) — Notion 순서 유지. */
+    readonly views: SidecarView[];
+    /** 정직한 손실 리포트 — 무엇이 `.base` 에서 누락/degrade 됐는가. */
+    readonly degraded: DegradeNote[];
+}
+interface SidecarProperty {
+    readonly name: string;
+    readonly id: string;
+    readonly type: string;
+    /** select/multi_select/status 옵션명(있으면). */
+    readonly options?: string[];
+}
+interface SidecarView {
+    readonly id: string;
+    readonly name: string;
+    readonly notionType: string;
+    /** Bases 대응 타입. `null` = `.base` 미표현(사이드카가 유일 보존처). */
+    readonly basesType: BasesViewType | null;
+    /** 원본 뷰 설정 중 의미 있는 항목(키 정렬). 빈 값은 생략. */
+    readonly config: Record<string, unknown>;
+}
+interface DegradeNote {
+    readonly view: string;
+    readonly kind: "view-unrepresentable" | "setting-dropped";
+    readonly detail: string;
+}
+declare class SidecarGenerator {
+    /**
+     * 사이드카 객체를 빌드한다(순수 — I/O 없음). 직렬화는 {@link serialize} 가 담당.
+     */
+    build(options: {
+        databaseId: string;
+        databaseName: string;
+        schema: Record<string, BasePropertySchema>;
+        viewsConfig: DatabaseViewsConfig;
+    }): NotionSidecar;
+    /**
+     * 사이드카를 결정적 JSON 문자열로 직렬화한다(키 재귀 정렬 + 말미 개행).
+     * 동일 입력 → 동일 바이트 → 멱등(drift/churn 0).
+     */
+    serialize(sidecar: NotionSidecar): string;
+    private buildProperties;
+    private buildView;
+    /**
+     * 뷰 설정 중 의미 있는 항목을 추출한다. `.base` 가 표현 못하는 항목(필터·커버크기 등)은
+     * config 에 보존하면서 동시에 degrade 리포트에 1줄씩 기록한다(표현되는 뷰에 한해 —
+     * 미표현 뷰는 이미 view-unrepresentable 로 통째 보고됨).
+     */
+    private extractConfig;
+}
+
 declare function sortEntries(entries: DBEntry[], sorts: NonNullable<ViewConfig["sorts"]>): DBEntry[];
 declare function groupEntries(entries: DBEntry[], groupByProperty: string, options?: {
     sort?: "ascending" | "descending";
@@ -1414,12 +1892,95 @@ declare function getNotionColor(color: NotionColor | string): string;
 declare function getNotionBgColor(color: NotionColor | string): string;
 declare function generateColorCSS(): string;
 
+/**
+ * 본문 링크 충실도(fidelity) 분류기 — 회귀 상시 잠금용 측정 인프라.
+ *
+ * pull 결과물(.md 본문)에 남은 notion 링크/멘션을 네 부류로 분류한다:
+ *
+ *   1. preservedMarkers — `[text](url)%%im-nobsidian:...%%` 형태의 의도된 무손실
+ *      보존 마커(copy_indicator 등). push 라운드트립 복원용으로 *일부러* 남긴 것이라
+ *      결함이 아니다.
+ *   2. externalLinks    — 동기화 코퍼스에 없는 외부 notion.so 링크. 위키링크로 환원할
+ *      대상이 없으므로 맨 링크로 두는 게 정당하다.
+ *   3. selfReferences   — 자기 자신 페이지를 가리키는 링크/멘션(블록 앵커 등). 정당.
+ *   4. defects          — 동기화된 *다른* 페이지로의 미해소 링크/멘션. 이것만이 진짜
+ *      충실도 결함이다(M2/M3/M4/M6 가 봉합한 대상).
+ *
+ * 변환 파이프라인이 완전하면 `defects.length === 0` 이어야 한다. 이 분류기를 픽스처로
+ * 잠가(unit test) 두면 변환기 회귀가 즉시 드러나고, 실제 vault 에 대고 돌리면(아래
+ * scripts/audit-vault.mjs) 코퍼스 전체의 충실도를 정량 측정할 수 있다.
+ *
+ * 마커/ID 판별은 SSOT 를 재사용한다 — 마커 브랜드는 {@link MARKER_BRAND},
+ * 정규 id 는 {@link compactNotionId}. 별도 헬퍼를 만들지 않는다.
+ */
+/** 미해소로 남은 링크/멘션의 형태. */
+type FidelityDefectForm = "md-link" | "mention-page";
+/** 진짜 충실도 결함 — 동기화된 다른 페이지로의 미해소 링크/멘션. */
+interface FidelityDefect {
+    /** 미해소 형태(맨 마크다운 링크 / 미변환 mention-page 태그). */
+    form: FidelityDefectForm;
+    /** 대상 페이지의 정규(compact) id. */
+    targetPageId: string;
+    /** 대상 페이지 제목(맵에 있으면). */
+    targetTitle: string | null;
+    /** 결함 원문 조각(진단용). */
+    raw: string;
+}
+/** {@link classifyBodyFidelity} 분류 결과. */
+interface FidelityClassification {
+    /** `[text](url)%%im-nobsidian:...%%` — 의도된 무손실 보존 마커(결함 아님). */
+    preservedMarkers: number;
+    /** 코퍼스에 없는 외부 notion.so 링크(정당). */
+    externalLinks: number;
+    /** 자기 자신 페이지를 가리키는 링크/멘션(정당). */
+    selfReferences: number;
+    /** 동기화된 다른 페이지로의 미해소 링크/멘션 — 진짜 결함. */
+    defects: FidelityDefect[];
+}
+/** 분류에 필요한 코퍼스 컨텍스트. */
+interface FidelityContext {
+    /** 동기화된 전체 페이지의 정규(compact) id 집합. */
+    knownPageIds: ReadonlySet<string>;
+    /** 정규 id → 제목. 선택(결함 진단용). */
+    titleById?: ReadonlyMap<string, string>;
+    /** 이 본문이 속한 페이지의 정규 id. 자기참조 판별용. 선택. */
+    ownPageId?: string;
+}
+/**
+ * 본문 문자열의 notion 링크/멘션 충실도를 분류한다. 순수 함수 — I/O 없음.
+ *
+ * @param body  분석할 마크다운 본문(프론트매터 포함 가능; 보존 마커·위키링크는 무시됨).
+ * @param ctx   코퍼스 컨텍스트(알려진 페이지 id 집합 등).
+ */
+declare function classifyBodyFidelity(body: string, ctx: FidelityContext): FidelityClassification;
+/** 여러 본문의 분류 결과를 합산한 코퍼스 단위 요약. */
+interface FidelitySummary {
+    files: number;
+    preservedMarkers: number;
+    externalLinks: number;
+    selfReferences: number;
+    defects: number;
+    /** 결함이 1건 이상인 파일 경로 → 결함 목록. */
+    defectsByFile: Record<string, FidelityDefect[]>;
+}
+/** 파일별 분류 결과(경로 + 분류)를 코퍼스 요약으로 합산한다. */
+declare function summarizeFidelity(perFile: ReadonlyArray<{
+    path: string;
+    classification: FidelityClassification;
+}>): FidelitySummary;
+
 declare function computeHash(content: string): string;
 declare function computeBufferHash(buffer: Buffer): string;
 
 declare function generateId(): string;
 declare function normalizeNotionId(id: string): string;
 declare function notionIdsEqual(a: string, b: string): boolean;
+/**
+ * 멘션 위키링크용 정규 id — 하이픈 제거 + 소문자. 오케스트레이터의 멘션 해소 정규식
+ * (`[[notion:<32hex>]]`)이 인식하는 유일한 형태다. 블록 폴백 경로(formatMention)와
+ * markdown-api 경로(convertPageMentions)가 동일 형태로 수렴하도록 한다(rank20/I3).
+ */
+declare function compactNotionId(id: string): string;
 
 declare function sanitizeFileName(name: string): string;
 
@@ -1437,4 +1998,47 @@ interface PipelineOptions {
 }
 declare function createDefaultPipeline(options?: PipelineOptions): ConversionPipeline;
 
-export { BaseFileGenerator, type BaseFileOptions, type BasePropertySchema, BlockConverter, type CalendarEntry, CalloutRestorer, CalloutTransformer, ChangeDetector, ColorAnnotator, type Config, ConfigManager, ConfigSchema, type Conflict, ConflictResolver, type ConflictStrategy, type ConversionContext, type ConversionPath, ConversionPipeline, type ConversionResult, type CoverConfig, type DBEntry, DEFAULT_CONFIG, type DatabaseSyncConfig, type DatabaseSyncResult, DatabaseSyncer, type DatabaseViewsConfig, EmbedResolver, EntryEditor, type FailedOperation, type FileDownloadResult, FileHandler, type FileInfo, type FileRegistryEntry, type FileStatInfo, type FileSystemEntry, type FileType, type FileUploadResult, FileWatcher, type FilterCondition, FrontmatterExtractor, FrontmatterGenerator, type GroupByConfig, type GroupedEntries, HtmlAnnotationStripper, type IStateDB, type ImageDownloadResult, ImageHandler, type ImageReference, InlineDBParser, type LocalChange, LocalImageRestorer, type Logger, type MappingResult, type MappingType, MathNormalizer, MentionToWikilink, type MergeConflictRegion, type MergeResult, NodeVaultFS, type NonMdFileInfo, type NotionBlock, NotionBlockBuilder, NotionClient, type NotionClientOptions, type NotionColor, type NotionPageNode, type NotionRichText, type RichTextItem as NotionRichTextItem, type OperationType, type PageCover, type PageCreationPlan, type PageIcon, type PathFilterConfig, type PreserveMarker, PreserveMarkerCollector, PreserveMarkerInjector, type Processor, type ProcessorInput, type ProcessorMetadata, type ProcessorOutput, type ProgressCallback, type ProgressItem, PropertiesTableInjector, PropertiesTableRestorer, PropertyMapper, type PropertyOption, type PropertySchema, type PropertyValue, type PullOptions, type PullResult, type PushOptions, type PushResult, type RegisterFileInput, type RemoteChange, type ResolutionChoice, type ResolutionResult, type RichTextSegment, StateDB, type StatusResult, type SyncDirection, type SyncOptions, SyncOrchestrator, type SyncRecord, type SyncResult, type SyncStatus, TreeMapper, UnsupportedBlockStripper, type UpsertSyncRecord, type VaultFS, type ViewConfig, ViewDataProvider, type ViewPropertyConfig, type ViewRenderData, type ViewType, type WatchSyncOptions, WatchSyncService, type WikilinkEntry, WikilinkResolver, computeBufferHash, computeHash, createDefaultPipeline, extractCalendarEntries, filterByMonth, filterEntries, generateColorCSS, generateId, getLogger, getNotionBgColor, getNotionColor, getVisibleProperties, groupEntries, normalizeNotionId, notionIdsEqual, sanitizeFileName, setLogger, sortEntries, threeWayMerge };
+/**
+ * 내부 메타데이터 경로 단일 진실원(SSOT).
+ *
+ * `.im-nobsidian` 디렉터리·하위 파일명·ignore 파일·gitignore 항목을 한곳에서 정의한다.
+ * 디렉터리/파일명을 바꾸거나 리브랜딩할 때 이 파일만 수정하면 전 패키지에 반영된다.
+ */
+/** 내부 메타데이터 디렉터리명 (vault 루트 기준). */
+declare const INTERNAL_DIR = ".im-nobsidian";
+/** 동기화 설정 파일명. */
+declare const CONFIG_FILE = "config.json";
+/** SQLite 상태 DB 파일명. */
+declare const STATE_DB_FILE = "sync.db";
+/** DB 뷰 메타데이터 파일명. */
+declare const DB_VIEWS_FILE = "db-views.json";
+/** 동기화 제외 패턴 파일명 (디렉터리 외부, vault 루트 직속). */
+declare const IGNORE_FILE = ".im-nobsidian-ignore";
+/** `.gitignore`에 추가하는 항목. */
+declare const GITIGNORE_ENTRY = ".im-nobsidian/";
+/** vault 상대 POSIX 경로 — DB 뷰 메타데이터. */
+declare const DB_VIEWS_PATH = ".im-nobsidian/db-views.json";
+/** vault 상대 POSIX 경로 — 상태 DB. */
+declare const STATE_DB_PATH = ".im-nobsidian/sync.db";
+/** 파일 감시에서 제외할 내부 디렉터리 glob. */
+declare const INTERNAL_DIR_GLOB = "**/.im-nobsidian/**";
+/**
+ * 주어진 vault 상대 경로(POSIX)가 내부 메타데이터 디렉터리에 속하는지 판별한다.
+ */
+declare function isInternalPath(path: string): boolean;
+
+/**
+ * 보존 마커(preserve marker) 단일 진실원(SSOT).
+ *
+ * 변환 불가 요소를 라운드트립 보존하기 위해 본문에 삽입하는 마커가 공유하는
+ * 브랜드 토큰을 한곳에서 정의한다. 리브랜딩 시 {@link MARKER_BRAND}만 바꾸면
+ * 모든 빌더·정규식에 반영된다.
+ *
+ * 주의: 마커 포맷(공백 유무)은 기존 vault·Notion에 이미 기록된 데이터와의 호환을
+ * 위해 변경하지 않는다. 두 포맷이 공존한다 — 공백형(`%% brand:... %%`)과
+ * 압축형(`%%brand:...%%`).
+ */
+/** 모든 보존 마커가 공유하는 브랜드 토큰. */
+declare const MARKER_BRAND = "im-nobsidian";
+
+export { BaseFileGenerator, type BaseFileOptions, type BasePropertySchema, type BaseSyncOptions, type BasesViewType, BlockConverter, CONFIG_FILE, type CalendarEntry, CalloutRestorer, CalloutTransformer, ChangeDetector, ColorAnnotator, type Config, ConfigManager, ConfigSchema, type Conflict, ConflictResolver, type ConflictStrategy, type ConversionContext, type ConversionPath, ConversionPipeline, type ConversionResult, type CoverConfig, type DBEntry, DB_VIEWS_FILE, DB_VIEWS_PATH, DEFAULT_CONFIG, type DatabaseSyncConfig, type DatabaseSyncResult, DatabaseSyncer, type DatabaseViewsConfig, type DegradeNote, EmbedResolver, EntryEditor, type FailedOperation, type FidelityClassification, type FidelityContext, type FidelityDefect, type FidelityDefectForm, type FidelitySummary, type FileDownloadResult, FileHandler, type FileInfo, type FileRegistryEntry, type FileStatInfo, type FileSystemEntry, type FileType, type FileUploadResult, FileWatcher, type FilterCondition, FrontmatterExtractor, FrontmatterGenerator, GITIGNORE_ENTRY, type GroupByConfig, type GroupedEntries, IGNORE_FILE, INTERNAL_DIR, INTERNAL_DIR_GLOB, type IStateDB, type ImageDownloadResult, ImageHandler, type ImageReference, InlineAnnotationPreserver, InlineDBParser, type LocalChange, LocalImageRestorer, type Logger, MARKER_BRAND, type MappingResult, type MappingType, MathNormalizer, MentionToWikilink, type MergeConflictRegion, type MergeResult, NOTION_TO_BASES_VIEW, NodeVaultFS, type NonMdFileInfo, type NotionBlock, NotionBlockBuilder, NotionClient, type NotionClientOptions, type NotionColor, type NotionPageNode, type NotionRichText, type RichTextItem as NotionRichTextItem, type NotionSidecar, type OperationType, type PageCover, type PageCreationPlan, type PageIcon, type PathFilterConfig, type PendingOperation, type PreserveMarker, PreserveMarkerCollector, PreserveMarkerInjector, type Processor, type ProcessorInput, type ProcessorMetadata, type ProcessorOutput, type ProgressCallback, type ProgressItem, PropertiesTableInjector, PropertiesTableRestorer, PropertyMapper, type PropertyOption, type PropertySchema, type PropertyValue, type PullOptions, type PullResult, type PushOptions, type PushResult, type RecordPendingInput, type RegisterFileInput, type RemoteChange, type ResolutionChoice, type ResolutionResult, type RichTextSegment, STATE_DB_FILE, STATE_DB_PATH, SidecarGenerator, type SidecarProperty, type SidecarView, StateDB, type StatusResult, type SyncDirection, type SyncOptions, SyncOrchestrator, type SyncRecord, type SyncResult, type SyncStatus, TreeMapper, UnsupportedBlockStripper, type UpsertSyncRecord, type VaultFS, type ViewConfig, ViewDataProvider, type ViewPropertyConfig, type ViewRenderData, type ViewType, type WatchSyncOptions, WatchSyncService, type WikilinkEntry, WikilinkResolver, basesViewTypeOf, classifyBodyFidelity, compactNotionId, computeBufferHash, computeHash, createDefaultPipeline, extractCalendarEntries, filterByMonth, filterEntries, generateColorCSS, generateId, getLogger, getNotionBgColor, getNotionColor, getVisibleProperties, groupEntries, isInternalPath, normalizeNotionId, notionIdsEqual, sanitizeFileName, setLogger, sortEntries, summarizeFidelity, threeWayMerge };