ntion 0.3.0 → 0.4.0

package/README.md

@@ -148,9 +148,11 @@ ntion pages unrelate --from-id <page_id> --property Project --to-id <page_id>
 ```bash
 # Read as markdown (default)
 ntion blocks get --id <page_or_block_id> --depth 1
+ntion blocks get --id <page_or_block_id> --view full
+# blocks get uses --view (markdown|compact|full)
 
 # Append markdown content
-ntion blocks append --id <page_or_block_id> --markdown "# Title\n\nHello"
+ntion blocks append --id <page_or_block_id> --markdown $'# Title\n\nHello'
 ntion blocks append --id <page_or_block_id> --markdown-file ./notes.md
 
 # Surgical insertion
@@ -197,7 +199,7 @@ Compact, deterministic, easy to parse — by humans or machines.
 
 - **Generic** — works with any Notion workspace, no hardcoded schema assumptions
 - **Compact** — deterministic JSON envelopes, minimal bytes per response
-- **Safe** — automatic idempotency for all mutations, built-in conflict detection
+- **Safe** — automatic idempotency for all mutations, built-in conflict detection and verify-first recovery
 - **Fast** — zero native dependencies, internal schema caching, batch operations
 - **Agent-friendly** — designed for AI agents that pay per token
 

package/dist/audit/log.d.ts

@@ -6,5 +6,9 @@ export interface AuditEvent {
     target_ids?: string[];
     ok: boolean;
     timestamp: string;
+    recovery_attempted?: boolean;
+    recovery_succeeded?: boolean;
+    idempotency_persist_degraded?: boolean;
+    outcome_uncertain?: boolean;
 }
 export declare function appendAuditLog(event: AuditEvent): Promise<void>;

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { executeMutationWithIdempotency } from "./commands/mutation.js";
@@ -10,7 +10,7 @@ import { getConfigPath } from "./config/paths.js";
 import { buildInitialAuthConfig, loadConfigOrNull, saveConfig } from "./config/store.js";
 import { CliError } from "./errors/cli-error.js";
 import { markdownToBlocks } from "./notion/markdown.js";
-import { appendBlocks, archivePage, createPage, createPagesBulk, deleteBlocks, getBlocks, getDataSource, getDataSourceSchema, getPage, insertBlocks, listDataSources, queryDataSourcePages, replaceBlockRange, searchWorkspace, selectBlocks, setRelation, unarchivePage, updatePage, } from "./notion/repository.js";
+import { appendBlocks, archivePage, areBlocksDeleted, createPage, createPagesBulk, deleteBlocks, getBlocks, getDataSource, getDataSourceSchema, getPage, insertBlocks, listDataSources, queryDataSourcePages, replaceBlockRange, searchWorkspace, selectBlocks, setRelation, unarchivePage, updatePage, } from "./notion/repository.js";
 import { parseJsonOption } from "./utils/json.js";
 const ROOT_HELP_EPILOG = [
     "",
@@ -59,9 +59,15 @@ const BLOCKS_APPEND_HELP_EPILOG = [
     "  Provide exactly one of --blocks-json, --markdown, or --markdown-file.",
     "",
     "Examples:",
-    "  ntion blocks append --id <id> --markdown \"# Heading\\n\\nBody\"",
+    "  ntion blocks append --id <id> --markdown $'# Heading\\n\\nBody'",
     "  ntion blocks append --id <id> --markdown-file ./notes.md",
 ].join("\n");
+const BLOCKS_GET_HELP_EPILOG = [
+    "",
+    "View vs Return-View:",
+    "  blocks get uses --view <markdown|compact|full>.",
+    "  mutation commands use --return-view <compact|full> for page/data outputs.",
+].join("\n");
 const BLOCKS_INSERT_HELP_EPILOG = [
     "",
     "Positioning:",
@@ -104,7 +110,7 @@ function resolveBlockReadFormat(input, fallback) {
     if (value === "markdown" || value === "compact" || value === "full") {
         return value;
     }
-    throw new CliError("invalid_input", "Block format must be markdown, compact, or full.");
+    throw new CliError("invalid_input", "Block view must be markdown, compact, or full.");
 }
 function parseSearchObject(raw) {
     if (!raw) {
@@ -188,11 +194,26 @@ async function resolveBlocksInput(args) {
         return requireArrayJson(args.blocksJson, "blocks-json");
     }
     if (args.markdown) {
+        validateMarkdownInput(args.markdown);
         return markdownToBlocks(args.markdown);
     }
     const markdown = await readFile(String(args.markdownFile), "utf8");
     return markdownToBlocks(markdown);
 }
+function validateMarkdownInput(markdown) {
+    if (markdown.includes("\\n") && !markdown.includes("\n")) {
+        throw new CliError("invalid_input", "--markdown appears to contain literal \\n escapes. Use real newline characters or --markdown-file.");
+    }
+}
+function relationIncludesTarget(page, propertyName, targetId) {
+    const properties = page.properties;
+    if (!properties || typeof properties !== "object") {
+        return false;
+    }
+    const relationValue = properties[propertyName];
+    return (Array.isArray(relationValue) &&
+        relationValue.some((value) => typeof value === "string" && value === targetId));
+}
 function addCommonReadOptions(command) {
     return command
         .option("--view <compact|full>", "response view mode")
@@ -614,6 +635,16 @@ addCommonMutationOptions(pagesCommand.command("archive").description("Archive a
                 view,
                 fields,
             }),
+            recover: async () => {
+                const current = await getPage(notion, options.id, "full");
+                if (current.archived !== true) {
+                    return null;
+                }
+                if (view === "full") {
+                    return current;
+                }
+                return getPage(notion, options.id, view, fields);
+            },
         });
         return {
             data: {
@@ -647,6 +678,16 @@ addCommonMutationOptions(pagesCommand.command("unarchive").description("Unarchiv
                 view,
                 fields,
             }),
+            recover: async () => {
+                const current = await getPage(notion, options.id, "full");
+                if (current.archived !== false) {
+                    return null;
+                }
+                if (view === "full") {
+                    return current;
+                }
+                return getPage(notion, options.id, view, fields);
+            },
         });
         return {
             data: {
@@ -687,6 +728,16 @@ addCommonMutationOptions(pagesCommand.command("relate").description("Add a relat
                 view,
                 fields,
             }),
+            recover: async () => {
+                const current = await getPage(notion, options.fromId, "full");
+                if (!relationIncludesTarget(current, options.property, options.toId)) {
+                    return null;
+                }
+                if (view === "full") {
+                    return current;
+                }
+                return getPage(notion, options.fromId, view, fields);
+            },
         });
         return {
             data: {
@@ -727,6 +778,16 @@ addCommonMutationOptions(pagesCommand.command("unrelate").description("Remove a
                 view,
                 fields,
             }),
+            recover: async () => {
+                const current = await getPage(notion, options.fromId, "full");
+                if (relationIncludesTarget(current, options.property, options.toId)) {
+                    return null;
+                }
+                if (view === "full") {
+                    return current;
+                }
+                return getPage(notion, options.fromId, view, fields);
+            },
         });
         return {
             data: {
@@ -736,27 +797,32 @@ addCommonMutationOptions(pagesCommand.command("unrelate").description("Remove a
     });
 });
 const blocksCommand = program.command("blocks").description("Block operations");
-blocksCommand
+const blocksGetCommand = blocksCommand
     .command("get")
     .description("Get blocks from a page or block")
     .requiredOption("--id <page_or_block_id>", "Notion page or block ID")
     .option("--max-blocks <n>", "Maximum block count")
     .option("--depth <n>", "Recursion depth", "1")
-    .option("--format <markdown|compact|full>", "content format", "markdown")
+    .option("--view <markdown|compact|full>", "content view", "markdown")
+    .addOption(new Option("--format <markdown|compact|full>").hideHelp())
     .option("--pretty", "pretty-print JSON output")
     .option("--timeout-ms <n>", "request timeout in milliseconds")
     .action(async (options) => {
     await runAction(Boolean(options.pretty), async () => {
+        if (options.format) {
+            throw new CliError("invalid_input", "--format is no longer supported for blocks get. Use --view <markdown|compact|full>.");
+        }
         const { config, notion } = await loadRuntime({ timeoutMs: options.timeoutMs });
         const maxBlocks = parsePositiveInt(options.maxBlocks, "max-blocks", config.defaults.max_blocks);
         const depth = parsePositiveInt(options.depth, "depth", 1);
-        const format = resolveBlockReadFormat(options.format, "markdown");
-        const blocks = await getBlocks(notion, options.id, maxBlocks, depth, format);
+        const view = resolveBlockReadFormat(options.view, "markdown");
+        const blocks = await getBlocks(notion, options.id, maxBlocks, depth, view);
         return {
             data: blocks,
         };
     });
 });
+blocksGetCommand.addHelpText("after", BLOCKS_GET_HELP_EPILOG);
 const blocksAppendCommand = blocksCommand
     .command("append")
     .description("Append blocks to a page or block")
@@ -769,12 +835,12 @@ const blocksAppendCommand = blocksCommand
     .option("--timeout-ms <n>", "request timeout in milliseconds")
     .action(async (options) => {
     await runAction(Boolean(options.pretty), async (requestId) => {
-        const { notion } = await loadRuntime({ timeoutMs: options.timeoutMs });
         const blocks = await resolveBlocksInput({
             blocksJson: options.blocksJson,
             markdown: options.markdown,
             markdownFile: options.markdownFile,
         });
+        const { notion } = await loadRuntime({ timeoutMs: options.timeoutMs });
         const result = await executeMutationWithIdempotency({
             commandName: options.dryRun ? "blocks.append.dry_run" : "blocks.append",
             requestId,
@@ -810,13 +876,13 @@ const blocksInsertCommand = blocksCommand
     .option("--timeout-ms <n>", "request timeout in milliseconds")
     .action(async (options) => {
     await runAction(Boolean(options.pretty), async (requestId) => {
-        const { notion } = await loadRuntime({ timeoutMs: options.timeoutMs });
         const blocks = await resolveBlocksInput({
             blocksJson: options.blocksJson,
             markdown: options.markdown,
             markdownFile: options.markdownFile,
         });
         const position = resolveInsertPosition(options.position, options.afterId);
+        const { notion } = await loadRuntime({ timeoutMs: options.timeoutMs });
         const result = await executeMutationWithIdempotency({
             commandName: options.dryRun ? "blocks.insert.dry_run" : "blocks.insert",
             requestId,
@@ -881,7 +947,6 @@ const blocksReplaceRangeCommand = blocksCommand
     .option("--timeout-ms <n>", "request timeout in milliseconds")
     .action(async (options) => {
     await runAction(Boolean(options.pretty), async (requestId) => {
-        const { notion } = await loadRuntime({ timeoutMs: options.timeoutMs });
         const blocks = await resolveBlocksInput({
             blocksJson: options.blocksJson,
             markdown: options.markdown,
@@ -890,6 +955,7 @@ const blocksReplaceRangeCommand = blocksCommand
         const startSelector = requireSelectorJson(options.startSelectorJson, "start-selector-json");
         const endSelector = requireSelectorJson(options.endSelectorJson, "end-selector-json");
         const maxBlocks = parsePositiveInt(options.scanMaxBlocks, "scan-max-blocks", 5000);
+        const { notion } = await loadRuntime({ timeoutMs: options.timeoutMs });
         const result = await executeMutationWithIdempotency({
             commandName: options.dryRun ? "blocks.replace_range.dry_run" : "blocks.replace_range",
             requestId,
@@ -936,6 +1002,16 @@ blocksCommand
             requestShape: { block_ids: options.blockIds },
             targetIds: options.blockIds,
             run: () => deleteBlocks(notion, { blockIds: options.blockIds }),
+            recover: async () => {
+                const deleted = await areBlocksDeleted(notion, options.blockIds);
+                if (!deleted) {
+                    return null;
+                }
+                return {
+                    deleted_count: options.blockIds.length,
+                    deleted_ids: options.blockIds,
+                };
+            },
         });
         return {
             data: result,

package/dist/commands/mutation.d.ts

@@ -5,4 +5,6 @@ export declare function executeMutationWithIdempotency<T>(args: {
     entity?: string;
     targetIds?: string[];
     run: () => Promise<T>;
+    recover?: () => Promise<T | null>;
+    isAmbiguousError?: (error: unknown) => boolean;
 }): Promise<T>;

package/dist/commands/mutation.js

@@ -13,11 +13,42 @@ async function safeAppendAuditLog(event) {
         // Audit logging must not alter mutation outcomes.
     }
 }
+function getStatus(error) {
+    if (!error || typeof error !== "object") {
+        return undefined;
+    }
+    const status = error.status;
+    return typeof status === "number" ? status : undefined;
+}
+function getCode(error) {
+    if (!error || typeof error !== "object") {
+        return undefined;
+    }
+    const code = error.code;
+    return typeof code === "string" ? code : undefined;
+}
+function isAmbiguousMutationError(error, override) {
+    if (override) {
+        return override(error);
+    }
+    if (error instanceof CliError && error.code === "retryable_upstream") {
+        return true;
+    }
+    const status = getStatus(error);
+    if (status === 429 || (typeof status === "number" && status >= 500)) {
+        return true;
+    }
+    return getCode(error) === "internal_error";
+}
 export async function executeMutationWithIdempotency(args) {
     const store = new IdempotencyStore();
     const requestHash = hashObject(args.requestShape);
     const idempotencyKey = buildInternalIdempotencyKey(args.commandName, args.requestShape);
     let ownsReservation = false;
+    let recoveryAttempted = false;
+    let recoverySucceeded = false;
+    let idempotencyPersistDegraded = false;
+    let outcomeUncertain = false;
     try {
         let lookup = store.reserve(idempotencyKey, args.commandName, requestHash);
         while (lookup.kind === "pending") {
@@ -68,8 +99,45 @@ export async function executeMutationWithIdempotency(args) {
             return lookup.response;
         }
         ownsReservation = true;
-        const response = await args.run();
-        store.complete(idempotencyKey, args.commandName, requestHash, response);
+        let response;
+        try {
+            response = await args.run();
+        }
+        catch (error) {
+            if (!isAmbiguousMutationError(error, args.isAmbiguousError)) {
+                throw error;
+            }
+            recoveryAttempted = true;
+            if (args.recover) {
+                try {
+                    const recovered = await args.recover();
+                    if (recovered !== null) {
+                        response = recovered;
+                        recoverySucceeded = true;
+                    }
+                    else {
+                        outcomeUncertain = true;
+                        throw new CliError("retryable_upstream", "Mutation outcome could not be confirmed. Re-read before retrying.", { retryable: true });
+                    }
+                }
+                catch {
+                    outcomeUncertain = true;
+                    throw new CliError("retryable_upstream", "Mutation outcome could not be confirmed. Re-read before retrying.", { retryable: true });
+                }
+            }
+            else {
+                outcomeUncertain = true;
+                throw new CliError("retryable_upstream", "Mutation outcome could not be confirmed. Re-read before retrying.", { retryable: true });
+            }
+        }
+        try {
+            store.complete(idempotencyKey, args.commandName, requestHash, response);
+        }
+        catch {
+            // Avoid surfacing internal idempotency persistence failures to callers
+            // after the write has already succeeded or been verified.
+            idempotencyPersistDegraded = true;
+        }
         await safeAppendAuditLog({
             command: args.commandName,
             entity: args.entity,
@@ -77,6 +145,10 @@ export async function executeMutationWithIdempotency(args) {
             idempotency_key: idempotencyKey,
             target_ids: args.targetIds,
             ok: true,
+            recovery_attempted: recoveryAttempted,
+            recovery_succeeded: recoverySucceeded,
+            idempotency_persist_degraded: idempotencyPersistDegraded,
+            outcome_uncertain: false,
             timestamp: new Date().toISOString(),
         });
         return response;
@@ -92,6 +164,10 @@ export async function executeMutationWithIdempotency(args) {
             idempotency_key: idempotencyKey,
             target_ids: args.targetIds,
             ok: false,
+            recovery_attempted: recoveryAttempted,
+            recovery_succeeded: recoverySucceeded,
+            idempotency_persist_degraded: idempotencyPersistDegraded,
+            outcome_uncertain: outcomeUncertain,
             timestamp: new Date().toISOString(),
         });
         throw error;

package/dist/config/paths.d.ts

@@ -2,4 +2,5 @@ export declare function getConfigDir(): string;
 export declare function getConfigPath(): string;
 export declare function getAuditLogPath(): string;
 export declare function getIdempotencyStorePath(): string;
+export declare function getIdempotencyLockPath(): string;
 export declare function ensureConfigDir(): string;

package/dist/config/paths.js

@@ -17,6 +17,9 @@ export function getAuditLogPath() {
 export function getIdempotencyStorePath() {
     return join(getConfigDir(), "idempotency.json");
 }
+export function getIdempotencyLockPath() {
+    return join(getConfigDir(), "idempotency.lock");
+}
 export function ensureConfigDir() {
     const configDir = getConfigDir();
     if (!existsSync(configDir)) {

package/dist/idempotency/store.d.ts

@@ -22,13 +22,19 @@ export type IdempotencyReservation = {
 };
 export declare class IdempotencyStore {
     private readonly filePath;
+    private readonly lockPath;
     constructor(filePath?: string);
     close(): void;
     lookup(idempotencyKey: string, commandName: string, inputHash: string): IdempotencyLookup;
     reserve(idempotencyKey: string, commandName: string, inputHash: string): IdempotencyReservation;
     complete(idempotencyKey: string, commandName: string, inputHash: string, response: unknown): void;
     release(idempotencyKey: string, commandName: string, inputHash: string): void;
-    private loadData;
-    private saveData;
+    private withLock;
+    private acquireLock;
+    private releaseLock;
+    private tryClearStaleLock;
+    private sleepMs;
+    private loadDataUnlocked;
+    private saveDataUnlocked;
 }
 export declare function buildInternalIdempotencyKey(commandName: string, requestShape: unknown): string;

package/dist/idempotency/store.js

@@ -1,87 +1,172 @@
-import { readFileSync, writeFileSync } from "node:fs";
-import { ensureConfigDir, getIdempotencyStorePath } from "../config/paths.js";
+import { closeSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { ensureConfigDir, getIdempotencyLockPath, getIdempotencyStorePath } from "../config/paths.js";
 import { CliError } from "../errors/cli-error.js";
 import { hashObject } from "../utils/json.js";
 const PRUNE_TTL_MS = 180_000;
+const LOCK_STALE_MS = 30_000;
+const LOCK_WAIT_TIMEOUT_MS = 35_000;
+const LOCK_POLL_INTERVAL_MS = 30;
+const SLEEP_ARRAY = new Int32Array(new SharedArrayBuffer(4));
 const PENDING_RESPONSE_JSON = JSON.stringify({ __notion_lite_pending: true });
 function compositeKey(idempotencyKey, commandName) {
     return `${idempotencyKey}\0${commandName}`;
 }
 export class IdempotencyStore {
     filePath;
+    lockPath;
     constructor(filePath = getIdempotencyStorePath()) {
         ensureConfigDir();
         this.filePath = filePath;
+        this.lockPath =
+            filePath === getIdempotencyStorePath() ? getIdempotencyLockPath() : `${filePath}.lock`;
     }
     close() {
         // no-op — nothing to tear down for a JSON file store
     }
     lookup(idempotencyKey, commandName, inputHash) {
-        const data = this.loadData();
-        const entry = data[compositeKey(idempotencyKey, commandName)];
-        if (!entry) {
-            return { kind: "miss" };
-        }
-        if (entry.inputHash !== inputHash) {
-            return { kind: "conflict", storedHash: entry.inputHash };
-        }
-        if (entry.responseJson === PENDING_RESPONSE_JSON) {
-            return { kind: "pending" };
-        }
+        return this.withLock(() => {
+            const data = this.loadDataUnlocked();
+            const entry = data[compositeKey(idempotencyKey, commandName)];
+            if (!entry) {
+                return { kind: "miss" };
+            }
+            if (entry.inputHash !== inputHash) {
+                return { kind: "conflict", storedHash: entry.inputHash };
+            }
+            if (entry.responseJson === PENDING_RESPONSE_JSON) {
+                return { kind: "pending" };
+            }
+            try {
+                return { kind: "replay", response: JSON.parse(entry.responseJson) };
+            }
+            catch {
+                throw new CliError("internal_error", "Stored idempotency response is corrupt.");
+            }
+        });
+    }
+    reserve(idempotencyKey, commandName, inputHash) {
+        return this.withLock(() => {
+            const data = this.loadDataUnlocked();
+            const key = compositeKey(idempotencyKey, commandName);
+            if (!data[key]) {
+                data[key] = {
+                    inputHash,
+                    responseJson: PENDING_RESPONSE_JSON,
+                    createdAt: Date.now(),
+                };
+                this.saveDataUnlocked(data);
+                return { kind: "execute" };
+            }
+            const entry = data[key];
+            if (entry.inputHash !== inputHash) {
+                return { kind: "conflict", storedHash: entry.inputHash };
+            }
+            if (entry.responseJson === PENDING_RESPONSE_JSON) {
+                return { kind: "pending" };
+            }
+            try {
+                return { kind: "replay", response: JSON.parse(entry.responseJson) };
+            }
+            catch {
+                throw new CliError("internal_error", "Stored idempotency response is corrupt.");
+            }
+        });
+    }
+    complete(idempotencyKey, commandName, inputHash, response) {
+        this.withLock(() => {
+            const data = this.loadDataUnlocked();
+            const key = compositeKey(idempotencyKey, commandName);
+            const entry = data[key];
+            if (!entry) {
+                data[key] = {
+                    inputHash,
+                    responseJson: JSON.stringify(response),
+                    createdAt: Date.now(),
+                };
+                this.saveDataUnlocked(data);
+                return;
+            }
+            if (entry.inputHash !== inputHash) {
+                throw new CliError("internal_error", "Failed to finalize idempotency record for mutation replay.");
+            }
+            entry.responseJson = JSON.stringify(response);
+            entry.createdAt = Date.now();
+            this.saveDataUnlocked(data);
+        });
+    }
+    release(idempotencyKey, commandName, inputHash) {
+        this.withLock(() => {
+            const data = this.loadDataUnlocked();
+            const key = compositeKey(idempotencyKey, commandName);
+            const entry = data[key];
+            if (entry && entry.inputHash === inputHash && entry.responseJson === PENDING_RESPONSE_JSON) {
+                delete data[key];
+                this.saveDataUnlocked(data);
+            }
+        });
+    }
+    withLock(fn) {
+        const lockFd = this.acquireLock();
         try {
-            return { kind: "replay", response: JSON.parse(entry.responseJson) };
+            return fn();
         }
-        catch {
-            throw new CliError("internal_error", "Stored idempotency response is corrupt.");
+        finally {
+            this.releaseLock(lockFd);
         }
     }
-    reserve(idempotencyKey, commandName, inputHash) {
-        const data = this.loadData();
-        const key = compositeKey(idempotencyKey, commandName);
-        if (!data[key]) {
-            data[key] = {
-                inputHash,
-                responseJson: PENDING_RESPONSE_JSON,
-                createdAt: Date.now(),
-            };
-            this.saveData(data);
-            return { kind: "execute" };
+    acquireLock() {
+        const deadline = Date.now() + LOCK_WAIT_TIMEOUT_MS;
+        while (Date.now() < deadline) {
+            try {
+                const fd = openSync(this.lockPath, "wx");
+                writeFileSync(fd, `${JSON.stringify({ pid: process.pid, created_at: new Date().toISOString() })}\n`, "utf-8");
+                return fd;
+            }
+            catch (error) {
+                const code = error.code;
+                if (code !== "EEXIST") {
+                    throw new CliError("internal_error", "Failed to acquire idempotency store lock.", {
+                        details: error,
+                    });
+                }
+                this.tryClearStaleLock();
+                this.sleepMs(LOCK_POLL_INTERVAL_MS + Math.floor(Math.random() * 20));
+            }
         }
-        const entry = data[key];
-        if (entry.inputHash !== inputHash) {
-            return { kind: "conflict", storedHash: entry.inputHash };
+        throw new CliError("retryable_upstream", "Idempotency store is busy. Retry shortly.", {
+            retryable: true,
+        });
+    }
+    releaseLock(lockFd) {
+        try {
+            closeSync(lockFd);
         }
-        if (entry.responseJson === PENDING_RESPONSE_JSON) {
-            return { kind: "pending" };
+        catch {
+            // best effort
         }
         try {
-            return { kind: "replay", response: JSON.parse(entry.responseJson) };
+            unlinkSync(this.lockPath);
         }
         catch {
-            throw new CliError("internal_error", "Stored idempotency response is corrupt.");
+            // best effort
         }
     }
-    complete(idempotencyKey, commandName, inputHash, response) {
-        const data = this.loadData();
-        const key = compositeKey(idempotencyKey, commandName);
-        const entry = data[key];
-        if (!entry || entry.inputHash !== inputHash) {
-            throw new CliError("internal_error", "Failed to finalize idempotency record for mutation replay.");
+    tryClearStaleLock() {
+        try {
+            const lockStat = statSync(this.lockPath);
+            const ageMs = Date.now() - lockStat.mtimeMs;
+            if (ageMs > LOCK_STALE_MS) {
+                unlinkSync(this.lockPath);
+            }
         }
-        entry.responseJson = JSON.stringify(response);
-        entry.createdAt = Date.now();
-        this.saveData(data);
-    }
-    release(idempotencyKey, commandName, inputHash) {
-        const data = this.loadData();
-        const key = compositeKey(idempotencyKey, commandName);
-        const entry = data[key];
-        if (entry && entry.inputHash === inputHash && entry.responseJson === PENDING_RESPONSE_JSON) {
-            delete data[key];
-            this.saveData(data);
+        catch {
+            // best effort
         }
     }
-    loadData() {
+    sleepMs(ms) {
+        Atomics.wait(SLEEP_ARRAY, 0, 0, ms);
+    }
+    loadDataUnlocked() {
         let raw;
         try {
             raw = readFileSync(this.filePath, "utf-8");
@@ -94,6 +179,7 @@ export class IdempotencyStore {
             data = JSON.parse(raw);
         }
         catch {
+            this.saveDataUnlocked({});
             return {};
         }
         const now = Date.now();
@@ -105,12 +191,14 @@ export class IdempotencyStore {
             }
         }
         if (pruned) {
-            this.saveData(data);
+            this.saveDataUnlocked(data);
         }
         return data;
     }
-    saveData(data) {
-        writeFileSync(this.filePath, JSON.stringify(data), "utf-8");
+    saveDataUnlocked(data) {
+        const tempPath = `${this.filePath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+        writeFileSync(tempPath, JSON.stringify(data), "utf-8");
+        renameSync(tempPath, this.filePath);
     }
 }
 export function buildInternalIdempotencyKey(commandName, requestShape) {

package/dist/notion/repository.d.ts

@@ -143,3 +143,4 @@ export declare function replaceBlockRange(notion: NotionClientAdapter, args: {
 export declare function deleteBlocks(notion: NotionClientAdapter, args: {
     blockIds: string[];
 }): Promise<Record<string, unknown>>;
+export declare function areBlocksDeleted(notion: NotionClientAdapter, blockIds: string[]): Promise<boolean>;

package/dist/notion/repository.js

@@ -107,6 +107,94 @@ function readRelationProperty(page, propertyName) {
         .map((item) => item.id)
         .filter((value) => typeof value === "string" && value.length > 0);
 }
+function collectFilterPropertyRefs(value, refs) {
+    if (!value || typeof value !== "object") {
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            collectFilterPropertyRefs(item, refs);
+        }
+        return;
+    }
+    const record = value;
+    if (typeof record.property === "string" && record.property.length > 0) {
+        refs.add(record.property);
+    }
+    for (const child of Object.values(record)) {
+        collectFilterPropertyRefs(child, refs);
+    }
+}
+function levenshteinDistance(a, b) {
+    const left = a.toLowerCase();
+    const right = b.toLowerCase();
+    if (left === right) {
+        return 0;
+    }
+    const matrix = Array.from({ length: left.length + 1 }, () => new Array(right.length + 1).fill(0));
+    for (let i = 0; i <= left.length; i += 1) {
+        matrix[i][0] = i;
+    }
+    for (let j = 0; j <= right.length; j += 1) {
+        matrix[0][j] = j;
+    }
+    for (let i = 1; i <= left.length; i += 1) {
+        for (let j = 1; j <= right.length; j += 1) {
+            const cost = left[i - 1] === right[j - 1] ? 0 : 1;
+            matrix[i][j] = Math.min(matrix[i - 1][j] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j - 1] + cost);
+        }
+    }
+    return matrix[left.length][right.length];
+}
+function suggestPropertyNames(raw, candidates) {
+    const target = raw.toLowerCase();
+    return [...candidates]
+        .sort((a, b) => {
+        const aLower = a.toLowerCase();
+        const bLower = b.toLowerCase();
+        const aStarts = aLower.startsWith(target) ? 0 : 1;
+        const bStarts = bLower.startsWith(target) ? 0 : 1;
+        if (aStarts !== bStarts) {
+            return aStarts - bStarts;
+        }
+        const aContains = aLower.includes(target) ? 0 : 1;
+        const bContains = bLower.includes(target) ? 0 : 1;
+        if (aContains !== bContains) {
+            return aContains - bContains;
+        }
+        const distanceDiff = levenshteinDistance(raw, a) - levenshteinDistance(raw, b);
+        if (distanceDiff !== 0) {
+            return distanceDiff;
+        }
+        return a.localeCompare(b);
+    })
+        .slice(0, 3);
+}
+async function validateDataSourceFilterProperties(ctx, dataSourceId, filter) {
+    if (!filter) {
+        return;
+    }
+    const refs = new Set();
+    collectFilterPropertyRefs(filter, refs);
+    if (refs.size === 0) {
+        return;
+    }
+    const schema = await hydrateDataSourceSchema(ctx, dataSourceId);
+    const validNames = Object.keys(schema);
+    const validIds = new Set(Object.values(schema)
+        .map((entry) => entry.id)
+        .filter((value) => typeof value === "string" && value.length > 0));
+    for (const property of refs) {
+        if (schema[property] || validIds.has(property)) {
+            continue;
+        }
+        const suggestions = suggestPropertyNames(property, validNames);
+        const suggestionText = suggestions.length > 0
+            ? ` Did you mean ${suggestions.map((name) => `"${name}"`).join(", ")}?`
+            : "";
+        throw new CliError("invalid_input", `Unknown filter property "${property}" for this data source.${suggestionText}`);
+    }
+}
 async function withBestEffortPageMutation(ctx, pageId, apply) {
     const attempts = 2;
     for (let attempt = 1; attempt <= attempts; attempt += 1) {
@@ -288,6 +376,7 @@ export async function getDataSourceSchema(notion, dataSourceId) {
     };
 }
 export async function queryDataSourcePages(ctx, input) {
+    await validateDataSourceFilterProperties(ctx, input.dataSourceId, input.filter);
     const payload = {
         data_source_id: input.dataSourceId,
         page_size: Math.min(Math.max(1, input.limit), 100),
@@ -1090,3 +1179,21 @@ export async function deleteBlocks(notion, args) {
         deleted_ids: deletedIds,
     };
 }
+export async function areBlocksDeleted(notion, blockIds) {
+    for (const blockId of blockIds) {
+        try {
+            const block = asRecord(await notion.retrieveBlock(blockId));
+            if (block.archived !== true) {
+                return false;
+            }
+        }
+        catch (error) {
+            const status = getStatus(error);
+            if (status === 404) {
+                continue;
+            }
+            throw error;
+        }
+    }
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ntion",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Token-efficient CLI for personal Notion workspaces",
   "type": "module",
   "license": "MIT",