@cyanheads/mcp-ts-core 0.13.7 → 0.13.9

package/dist/services/canvas/providers/duckdb/DuckdbProvider.js

@@ -6,10 +6,63 @@
  * a true peer dependency.
  * @module src/services/canvas/providers/duckdb/DuckdbProvider
  */
-import { mkdir, unlink } from 'node:fs/promises';
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { randomUUID } from 'node:crypto';
+import { mkdir, mkdtemp, rm, unlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
-import { databaseError, McpError, notFound, timeout, validationError, } from '../../../../types-global/errors.js';
+import { configurationError, databaseError, McpError, notFound, serviceUnavailable, timeout, validationError, } from '../../../../types-global/errors.js';
 import { lazyImport } from '../../../../utils/internal/lazyImport.js';
 import { logger } from '../../../../utils/internal/logger.js';
 import { requestContextService, withExtra, } from '../../../../utils/internal/requestContext.js';
@@ -22,6 +75,10 @@ export class DuckdbProvider {
     options;
     name = 'duckdb';
     canvases = new Map();
+    /** One pending promise per held canvas record, resolved on release — see {@link holdCanvas}. */
+    holds = new Set();
+    /** The private scratch directory once first requested — see {@link ensureTempRoot}. */
+    tempRoot;
     constructor(options) {
         this.options = options;
     }
@@ -29,36 +86,83 @@ export class DuckdbProvider {
     // Lifecycle
     // ---------------------------------------------------------------------
     /**
-     * Absolute scratch root, created on first use.
+     * The provider's private scratch directory, created once on first use.
      *
-     * DuckDB defaults an in-memory database's `temp_directory` to a
-     * cwd-relative `.tmp`, so the first query that spills `mkdir`s under the
-     * process working directory — which fails with `EACCES` whenever the
-     * container runs non-root or on a read-only rootfs. Resolving scratch to an
-     * explicitly writable directory keeps spills working regardless of cwd.
+     * `mkdtemp` makes a directory no other local user can have pre-created,
+     * planted links in, or read (`0700` on POSIX; on Windows it inherits the
+     * parent's ACL, so there the parent must not grant other users access), so
+     * no scratch path resolves through a fixed shared name (#554). It also
+     * keeps scratch off the process cwd: DuckDB defaults an in-memory
+     * database's `temp_directory` to a cwd-relative `.tmp`, which fails on a
+     * non-root or read-only rootfs. Concurrent first calls share one directory;
+     * a failed attempt is dropped so the next call retries.
      */
-    async ensureTempRoot() {
-        const root = resolve(this.options.tempRootPath ?? join(tmpdir(), 'mcp-canvas'));
-        await mkdir(root, { recursive: true });
-        return root;
+    ensureTempRoot() {
+        if (!this.tempRoot) {
+            const pending = this.createTempRoot();
+            this.tempRoot = pending;
+            pending.catch(() => {
+                if (this.tempRoot === pending)
+                    this.tempRoot = undefined;
+            });
+        }
+        return this.tempRoot;
+    }
+    async createTempRoot() {
+        const parent = resolve(this.options.tempRootPath ?? tmpdir());
+        try {
+            await mkdir(parent, { recursive: true });
+            return await mkdtemp(join(parent, 'mcp-canvas-'));
+        }
+        catch (err) {
+            throw configurationError('Canvas scratch directory could not be created: CANVAS_TEMP_PATH (the OS temp directory when unset) must be writable by the server process.', undefined, { cause: err });
+        }
     }
     async initCanvas(canvasId, _context) {
         if (this.canvases.has(canvasId))
             return;
         const duck = await importDuckDB();
-        const tempDirectory = await this.ensureTempRoot();
+        const root = this.ensureTempRoot();
+        const scratchDir = await root;
+        // DuckDB names spill files by block size alone, so instances sharing a
+        // temp_directory overwrite each other's evicted blocks (#561).
+        const spillDir = join(scratchDir, randomUUID());
         const instance = await duck.DuckDBInstance.create(':memory:', {
             memory_limit: `${this.options.memoryLimitMb}MB`,
-            temp_directory: tempDirectory,
+            temp_directory: spillDir,
             // Disable extension install/load paths in canvas mode.
             autoinstall_known_extensions: 'false',
             autoload_known_extensions: 'false',
         });
         const controlConnection = await instance.connect();
         await controlConnection.run(`SET memory_limit = '${this.options.memoryLimitMb}MB'`);
-        this.canvases.set(canvasId, { instance, controlConnection });
+        // A shutdown that began meanwhile retired `scratchDir` and may already
+        // have removed it, freeing the name for another local user to re-create;
+        // DuckDB creates only the leaf of its temp_directory and would spill into
+        // whatever sits there. The check and the insert share one synchronous run,
+        // so no shutdown can begin between them.
+        if (this.tempRoot !== root) {
+            controlConnection.closeSync();
+            instance.closeSync();
+            throw serviceUnavailable('Canvas provider shut down while the canvas was being created.');
+        }
+        this.canvases.set(canvasId, {
+            instance,
+            controlConnection,
+            holds: new Set(),
+            scratchDir,
+            spillDir,
+        });
     }
-    // biome-ignore lint/suspicious/useAwait: async is required by IDataCanvasProvider; close is sync for DuckDB.
+    /**
+     * Close the canvas's instance and remove its spill directory. A call still
+     * running on the canvas keeps the database open on its own connection and
+     * can still read spilled blocks back from that directory, so the directory
+     * goes once the last such call settles, and this does not wait for it.
+     * DuckDB removes a `temp_directory` it created when the database finally
+     * closes; the removal here covers every other case, so nothing of the
+     * canvas outlives it.
+     */
     async destroyCanvas(canvasId, _context) {
         const record = this.canvases.get(canvasId);
         if (!record)
@@ -80,6 +184,14 @@ export class DuckdbProvider {
         catch (err) {
             logger.warning('DuckDB instance close failed.', withExtra(closeContext, { error: err instanceof Error ? err.message : String(err) }));
         }
+        const remove = () => rm(record.spillDir, { recursive: true, force: true }).catch((err) => {
+            logger.warning('Canvas spill directory removal failed.', withExtra(closeContext, { error: err instanceof Error ? err.message : String(err) }));
+        });
+        if (record.holds.size > 0) {
+            void Promise.all(record.holds).then(remove);
+            return;
+        }
+        await remove();
     }
     async healthCheck() {
         try {
@@ -95,312 +207,413 @@ export class DuckdbProvider {
             return false;
         }
     }
+    /**
+     * Destroy every canvas, then remove the private scratch directory. A call
+     * that reached a canvas before shutdown began can still be writing there —
+     * an open per-query connection outlives its closed instance — so the
+     * directory goes once the last such call settles, and shutdown does not
+     * wait for it. Until then the directory stays in place and private, which
+     * keeps another local user from re-creating its name while that call still
+     * writes inside it. A canvas whose creation straddles the shutdown is
+     * refused rather than bound to the retired directory. A provider used
+     * again afterwards creates a fresh one. After an abnormal exit the
+     * directory stays behind, still private; nothing sweeps it on the next
+     * start.
+     */
     async shutdown() {
         const context = requestContextService.createRequestContext({
             operation: 'DuckdbProvider.shutdown',
         });
         const ids = [...this.canvases.keys()];
+        const held = [...this.holds];
+        const tempRoot = this.tempRoot;
+        this.tempRoot = undefined;
         await Promise.allSettled(ids.map((id) => this.destroyCanvas(id, context)));
+        const dir = await tempRoot?.catch(() => undefined);
+        if (!dir)
+            return;
+        const remove = () => rm(dir, { recursive: true, force: true }).catch((err) => {
+            logger.warning('Canvas scratch directory removal failed; it stays in place, still private.', withExtra(context, { error: err instanceof Error ? err.message : String(err) }));
+        });
+        const pending = held.filter((hold) => this.holds.has(hold));
+        if (pending.length > 0) {
+            void Promise.all(pending).then(remove);
+            return;
+        }
+        await remove();
     }
     // ---------------------------------------------------------------------
     // Data plane
     // ---------------------------------------------------------------------
     async registerTable(canvasId, name, rows, _context, options) {
-        const record = this.requireCanvas(canvasId);
-        const duck = await importDuckDB();
-        assertValidIdentifier(name, 'table');
-        options?.signal?.throwIfAborted();
-        const isAsyncIterable = typeof rows[Symbol.asyncIterator] === 'function';
-        let schema;
-        let bufferedRows;
-        let remainingSync;
-        if (options?.schema) {
-            schema = options.schema;
-        }
-        else if (isAsyncIterable) {
-            throw validationError('Schema must be provided explicitly when registering rows from an AsyncIterable.', { reason: 'async_iterable_requires_schema', tableName: name });
-        }
-        else {
-            const sniffed = sniffSchema(rows, this.options.schemaSniffRows);
-            schema = sniffed.schema;
-            bufferedRows = sniffed.sniffedRows;
-            remainingSync = sniffed.remaining;
-        }
-        for (const col of schema)
-            assertValidIdentifier(col.name, 'column');
-        // Drop+create makes register idempotent under re-registration of a name.
-        const ddl = buildCreateTableSql(name, schema);
-        await record.controlConnection.run(`DROP TABLE IF EXISTS ${quoteIdentifier(name)}`);
-        await record.controlConnection.run(ddl);
-        options?.signal?.throwIfAborted();
-        const appender = await record.controlConnection.createAppender(name);
-        let count = 0;
+        const env_1 = { stack: [], error: void 0, hasError: false };
         try {
-            const appendOne = (row) => {
-                for (const col of schema) {
-                    appendValue(appender, col, row[col.name], duck);
-                }
-                appender.endRow();
-                count += 1;
-            };
-            if (bufferedRows) {
-                for (const row of bufferedRows) {
-                    options?.signal?.throwIfAborted();
-                    appendOne(row);
-                }
-            }
-            if (isAsyncIterable) {
-                for await (const row of rows) {
-                    options?.signal?.throwIfAborted();
-                    appendOne(row);
-                }
+            const record = __addDisposableResource(env_1, this.holdCanvas(canvasId), false);
+            const duck = await importDuckDB();
+            assertValidIdentifier(name, 'table');
+            options?.signal?.throwIfAborted();
+            const isAsyncIterable = typeof rows[Symbol.asyncIterator] === 'function';
+            let schema;
+            let bufferedRows;
+            let remainingSync;
+            if (options?.schema) {
+                schema = options.schema;
             }
-            else if (remainingSync) {
-                // Continuation iterator from the sniffer — picks up just past
-                // bufferedRows so we don't re-iterate (which would drop data on
-                // generators or duplicate rows from fresh-iterator iterables).
-                let next = remainingSync.next();
-                while (!next.done) {
-                    options?.signal?.throwIfAborted();
-                    appendOne(next.value);
-                    next = remainingSync.next();
-                }
+            else if (isAsyncIterable) {
+                throw validationError('Schema must be provided explicitly when registering rows from an AsyncIterable.', { reason: 'async_iterable_requires_schema', tableName: name });
             }
             else {
-                for (const row of rows) {
-                    options?.signal?.throwIfAborted();
-                    appendOne(row);
+                const sniffed = sniffSchema(rows, this.options.schemaSniffRows);
+                schema = sniffed.schema;
+                bufferedRows = sniffed.sniffedRows;
+                remainingSync = sniffed.remaining;
+            }
+            for (const col of schema)
+                assertValidIdentifier(col.name, 'column');
+            // Drop+create makes register idempotent under re-registration of a name.
+            const ddl = buildCreateTableSql(name, schema);
+            await record.controlConnection.run(`DROP TABLE IF EXISTS ${quoteIdentifier(name)}`);
+            await record.controlConnection.run(ddl);
+            options?.signal?.throwIfAborted();
+            let count = 0;
+            try {
+                const appender = await record.controlConnection.createAppender(name);
+                try {
+                    const appendOne = (row) => {
+                        for (const col of schema) {
+                            appendValue(appender, col, row[col.name], duck);
+                        }
+                        appender.endRow();
+                        count += 1;
+                    };
+                    if (bufferedRows) {
+                        for (const row of bufferedRows) {
+                            options?.signal?.throwIfAborted();
+                            appendOne(row);
+                        }
+                    }
+                    if (isAsyncIterable) {
+                        for await (const row of rows) {
+                            options?.signal?.throwIfAborted();
+                            appendOne(row);
+                        }
+                    }
+                    else if (remainingSync) {
+                        // Continuation iterator from the sniffer — picks up just past
+                        // bufferedRows so we don't re-iterate (which would drop data on
+                        // generators or duplicate rows from fresh-iterator iterables).
+                        let next = remainingSync.next();
+                        while (!next.done) {
+                            options?.signal?.throwIfAborted();
+                            appendOne(next.value);
+                            next = remainingSync.next();
+                        }
+                    }
+                    else {
+                        for (const row of rows) {
+                            options?.signal?.throwIfAborted();
+                            appendOne(row);
+                        }
+                    }
                 }
+                finally {
+                    appender.closeSync();
+                }
+            }
+            catch (err) {
+                // A spill that cannot start fails here; the caller's own row source
+                // runs in the same block, so only errors naming a host path change.
+                throw this.redactHostPaths(err, record);
             }
+            return {
+                tableName: name,
+                rowCount: count,
+                columns: schema.map((c) => c.name),
+            };
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
         }
         finally {
-            appender.closeSync();
+            __disposeResources(env_1);
         }
-        return {
-            tableName: name,
-            rowCount: count,
-            columns: schema.map((c) => c.name),
-        };
     }
     async query(canvasId, sql, _context, options) {
-        const record = this.requireCanvas(canvasId);
-        options?.signal?.throwIfAborted();
-        const rowLimit = options?.rowLimit ?? this.options.defaultRowLimit;
-        if (!Number.isSafeInteger(rowLimit) ||
-            rowLimit < 1 ||
-            rowLimit > this.options.defaultRowLimit) {
-            throw validationError(`rowLimit must be a positive safe integer no greater than ${this.options.defaultRowLimit}.`, { reason: 'invalid_query_bounds', field: 'rowLimit' });
-        }
-        const preview = options?.preview ?? rowLimit;
-        if (!Number.isSafeInteger(preview) || preview < 0 || preview > rowLimit) {
-            throw validationError('preview must be a non-negative safe integer no greater than rowLimit.', { reason: 'invalid_query_bounds', field: 'preview' });
-        }
-        const duck = await importDuckDB();
-        await this.assertReadOnlySql(record, sql, duck, options);
-        return await this.withConnection(record, options?.signal, 'Canvas query was cancelled.', async (conn) => {
-            let registeredAs;
-            let rowsToReturn = [];
-            let columns = [];
-            let totalRowCount = 0;
-            let truncated;
-            if (options?.registerAs) {
-                assertValidIdentifier(options.registerAs, 'table');
-                await ensureTableMissing(record.controlConnection, options.registerAs);
-                const ctas = `CREATE TABLE ${quoteIdentifier(options.registerAs)} AS ${sql}`;
-                await conn.run(ctas);
-                registeredAs = options.registerAs;
-                const reader = await conn.runAndReadUntil(`SELECT * FROM ${quoteIdentifier(options.registerAs)} LIMIT ${preview}`, preview);
-                rowsToReturn = reader.getRowObjectsJson();
-                columns = reader.columnNames();
-                totalRowCount = await this.countRows(conn, options.registerAs);
-                // truncated is false on the registerAs path — rowCount is exact.
+        const env_2 = { stack: [], error: void 0, hasError: false };
+        try {
+            const record = __addDisposableResource(env_2, this.holdCanvas(canvasId), false);
+            options?.signal?.throwIfAborted();
+            const rowLimit = options?.rowLimit ?? this.options.defaultRowLimit;
+            if (!Number.isSafeInteger(rowLimit) ||
+                rowLimit < 1 ||
+                rowLimit > this.options.defaultRowLimit) {
+                throw validationError(`rowLimit must be a positive safe integer no greater than ${this.options.defaultRowLimit}.`, { reason: 'invalid_query_bounds', field: 'rowLimit' });
             }
-            else {
-                // Use streamAndReadUntil to keep the engine pipeline lazy: reads at
-                // most rowLimit+1 rows without materializing the full result in JS.
-                const reader = await conn.streamAndReadUntil(sql, rowLimit + 1);
-                const fetched = reader.getRowObjectsJson();
-                columns = reader.columnNames();
-                if (fetched.length > rowLimit) {
-                    // More rows exist beyond the cap.
-                    rowsToReturn = fetched.slice(0, rowLimit);
-                    totalRowCount = rowLimit;
-                    truncated = true;
+            const preview = options?.preview ?? rowLimit;
+            if (!Number.isSafeInteger(preview) || preview < 0 || preview > rowLimit) {
+                throw validationError('preview must be a non-negative safe integer no greater than rowLimit.', { reason: 'invalid_query_bounds', field: 'preview' });
+            }
+            const duck = await importDuckDB();
+            await this.assertReadOnlySql(record, sql, duck, options);
+            return await this.withConnection(record, options?.signal, 'Canvas query was cancelled.', async (conn) => {
+                let registeredAs;
+                let rowsToReturn = [];
+                let columns = [];
+                let totalRowCount = 0;
+                let truncated;
+                if (options?.registerAs) {
+                    assertValidIdentifier(options.registerAs, 'table');
+                    await ensureTableMissing(record.controlConnection, options.registerAs);
+                    const ctas = `CREATE TABLE ${quoteIdentifier(options.registerAs)} AS ${sql}`;
+                    await conn.run(ctas);
+                    registeredAs = options.registerAs;
+                    const reader = await conn.runAndReadUntil(`SELECT * FROM ${quoteIdentifier(options.registerAs)} LIMIT ${preview}`, preview);
+                    rowsToReturn = reader.getRowObjectsJson();
+                    columns = reader.columnNames();
+                    totalRowCount = await this.countRows(conn, options.registerAs);
+                    // truncated is false on the registerAs path — rowCount is exact.
                 }
                 else {
-                    rowsToReturn = fetched;
-                    totalRowCount = fetched.length;
-                }
-                // Apply preview cap (may be smaller than rowLimit when caller requests a smaller slice).
-                if (rowsToReturn.length > preview) {
-                    rowsToReturn = rowsToReturn.slice(0, preview);
+                    // Use streamAndReadUntil to keep the engine pipeline lazy: reads at
+                    // most rowLimit+1 rows without materializing the full result in JS.
+                    const reader = await conn.streamAndReadUntil(sql, rowLimit + 1);
+                    const fetched = reader.getRowObjectsJson();
+                    columns = reader.columnNames();
+                    if (fetched.length > rowLimit) {
+                        // More rows exist beyond the cap.
+                        rowsToReturn = fetched.slice(0, rowLimit);
+                        totalRowCount = rowLimit;
+                        truncated = true;
+                    }
+                    else {
+                        rowsToReturn = fetched;
+                        totalRowCount = fetched.length;
+                    }
+                    // Apply preview cap (may be smaller than rowLimit when caller requests a smaller slice).
+                    if (rowsToReturn.length > preview) {
+                        rowsToReturn = rowsToReturn.slice(0, preview);
+                    }
                 }
-            }
-            return {
-                rows: rowsToReturn,
-                columns,
-                rowCount: totalRowCount,
-                ...(truncated && { truncated }),
-                ...(registeredAs && { tableName: registeredAs }),
-            };
-        });
+                return {
+                    rows: rowsToReturn,
+                    columns,
+                    rowCount: totalRowCount,
+                    ...(truncated && { truncated }),
+                    ...(registeredAs && { tableName: registeredAs }),
+                };
+            });
+        }
+        catch (e_2) {
+            env_2.error = e_2;
+            env_2.hasError = true;
+        }
+        finally {
+            __disposeResources(env_2);
+        }
     }
     async export(canvasId, tableName, target, _context, options) {
-        const record = this.requireCanvas(canvasId);
-        assertValidIdentifier(tableName, 'table');
-        options?.signal?.throwIfAborted();
-        const formatClause = copyFormatClause(target.format);
-        return await this.withConnection(record, options?.signal, 'Canvas export was cancelled.', async (conn) => {
-            const rowCount = await this.countRows(conn, tableName);
-            if (isPathTarget(target)) {
-                const absolutePath = await resolveExportPath(this.options.exportRootPath, target.path);
-                await conn.run(`COPY ${quoteIdentifier(tableName)} TO '${escapeSqlString(absolutePath)}' ${formatClause}`);
-                const sizeBytes = await safeSizeBytes(absolutePath);
+        const env_3 = { stack: [], error: void 0, hasError: false };
+        try {
+            const record = __addDisposableResource(env_3, this.holdCanvas(canvasId), false);
+            assertValidIdentifier(tableName, 'table');
+            options?.signal?.throwIfAborted();
+            const formatClause = copyFormatClause(target.format);
+            return await this.withConnection(record, options?.signal, 'Canvas export was cancelled.', async (conn) => {
+                const rowCount = await this.countRows(conn, tableName);
+                if (isPathTarget(target)) {
+                    const absolutePath = await resolveExportPath(this.options.exportRootPath, target.path);
+                    await conn.run(`COPY ${quoteIdentifier(tableName)} TO '${escapeSqlString(absolutePath)}' ${formatClause}`);
+                    const sizeBytes = await safeSizeBytes(absolutePath);
+                    return {
+                        format: target.format,
+                        path: absolutePath,
+                        sizeBytes,
+                        rowCount,
+                    };
+                }
+                // Stream branch: COPY to a scratch file, pipe to the caller's stream,
+                // then unlink. pipeFileToStream owns cleanup once invoked; if the COPY
+                // itself fails we must unlink here before re-throwing.
+                const tempPath = tempFilePathFor(record.scratchDir, target.format);
+                try {
+                    await conn.run(`COPY ${quoteIdentifier(tableName)} TO '${escapeSqlString(tempPath)}' ${formatClause}`);
+                }
+                catch (copyErr) {
+                    await unlink(tempPath).catch(() => { });
+                    throw copyErr;
+                }
+                const { sizeBytes } = await pipeFileToStream(tempPath, target.stream);
                 return {
                     format: target.format,
-                    path: absolutePath,
                     sizeBytes,
                     rowCount,
                 };
+            });
+        }
+        catch (e_3) {
+            env_3.error = e_3;
+            env_3.hasError = true;
+        }
+        finally {
+            __disposeResources(env_3);
+        }
+    }
+    async registerView(canvasId, name, selectSql, _context, options) {
+        const env_4 = { stack: [], error: void 0, hasError: false };
+        try {
+            const record = __addDisposableResource(env_4, this.holdCanvas(canvasId), false);
+            const duck = await importDuckDB();
+            assertValidIdentifier(name, 'table');
+            options?.signal?.throwIfAborted();
+            // Same four-layer gate `query()` enforces. View definitions inherit the
+            // operator allowlist transitively at query time, but we also gate the
+            // SELECT at registration so a malicious definition fails loud here, not
+            // later when the view is referenced.
+            await this.assertReadOnlySql(record, selectSql, duck, options);
+            options?.signal?.throwIfAborted();
+            // Block view-on-table-name collisions explicitly so the failure carries a
+            // structured `reason` rather than a raw DuckDB catalog message.
+            const existing = await this.lookupKind(record.controlConnection, name);
+            if (existing === 'table') {
+                throw validationError(`Canvas already contains a base table named "${name}". Drop the table or choose a different name.`, { reason: 'view_table_clash', name });
             }
-            // Stream branch: COPY to a scratch file, pipe to the caller's stream,
-            // then unlink. pipeFileToStream owns cleanup once invoked; if the COPY
-            // itself fails we must unlink here before re-throwing.
-            const tempPath = await tempFilePathFor(await this.ensureTempRoot(), target.format);
             try {
-                await conn.run(`COPY ${quoteIdentifier(tableName)} TO '${escapeSqlString(tempPath)}' ${formatClause}`);
+                await record.controlConnection.run(`CREATE OR REPLACE VIEW ${quoteIdentifier(name)} AS ${selectSql}`);
             }
-            catch (copyErr) {
-                await unlink(tempPath).catch(() => { });
-                throw copyErr;
+            catch (err) {
+                throw this.classify(err, record);
             }
-            const { sizeBytes } = await pipeFileToStream(tempPath, target.stream);
-            return {
-                format: target.format,
-                sizeBytes,
-                rowCount,
-            };
-        });
-    }
-    async registerView(canvasId, name, selectSql, _context, options) {
-        const record = this.requireCanvas(canvasId);
-        const duck = await importDuckDB();
-        assertValidIdentifier(name, 'table');
-        options?.signal?.throwIfAborted();
-        // Same four-layer gate `query()` enforces. View definitions inherit the
-        // operator allowlist transitively at query time, but we also gate the
-        // SELECT at registration so a malicious definition fails loud here, not
-        // later when the view is referenced.
-        await this.assertReadOnlySql(record, selectSql, duck, options);
-        options?.signal?.throwIfAborted();
-        // Block view-on-table-name collisions explicitly so the failure carries a
-        // structured `reason` rather than a raw DuckDB catalog message.
-        const existing = await this.lookupKind(record.controlConnection, name);
-        if (existing === 'table') {
-            throw validationError(`Canvas already contains a base table named "${name}". Drop the table or choose a different name.`, { reason: 'view_table_clash', name });
+            return { viewName: name, columns: await this.columnNames(record.controlConnection, name) };
         }
-        try {
-            await record.controlConnection.run(`CREATE OR REPLACE VIEW ${quoteIdentifier(name)} AS ${selectSql}`);
+        catch (e_4) {
+            env_4.error = e_4;
+            env_4.hasError = true;
         }
-        catch (err) {
-            throw classifyDuckdbError(err);
+        finally {
+            __disposeResources(env_4);
         }
-        return { viewName: name, columns: await this.columnNames(record.controlConnection, name) };
     }
     async importFrom(targetCanvasId, sourceCanvasId, sourceTableName, asName, _context, options) {
-        if (sourceCanvasId === targetCanvasId) {
-            throw validationError('Source and target canvases must differ. Importing copies a table between two canvases.', {
-                reason: 'import_same_canvas',
-                recovery: {
-                    hint: 'Pass the canvas id of a different canvas as the source — the table is already on this one.',
-                },
-            });
-        }
-        const target = this.requireCanvas(targetCanvasId);
-        const source = this.requireCanvas(sourceCanvasId);
-        assertValidIdentifier(sourceTableName, 'table');
-        assertValidIdentifier(asName, 'table');
-        options?.signal?.throwIfAborted();
-        const sourceKind = await this.lookupKind(source.controlConnection, sourceTableName);
-        if (sourceKind === undefined) {
-            throw notFound(`Source canvas does not contain a table or view named "${sourceTableName}".`, {
-                reason: 'missing_table',
-                sourceCanvasId,
-                sourceTableName,
-                recovery: {
-                    hint: "Re-check the source table name, or list the tables staged on the source canvas with this server's dataframe-describe tool.",
-                },
-            });
-        }
-        const targetExisting = await this.lookupKind(target.controlConnection, asName);
-        if (targetExisting === 'view') {
-            throw validationError(`Target canvas already contains a view named "${asName}". Drop the view or choose a different name.`, {
-                reason: 'import_view_clash',
-                asName,
-                recovery: {
-                    hint: 'Drop the existing view first, or choose a different destination name for the imported table.',
-                },
-            });
-        }
-        // Drop+create makes import idempotent under re-imports of the same name,
-        // matching registerTable's behavior.
-        await target.controlConnection.run(`DROP TABLE IF EXISTS ${quoteIdentifier(asName)}`);
-        // Round-trip through a scratch Parquet file. Parquet is
-        // built into DuckDB's core (no extension load needed even with
-        // autoload disabled). All column types — including TIMESTAMP/DATE/BLOB
-        // — round-trip losslessly, which an in-memory appender path can't
-        // guarantee for native engine value types.
-        const tempPath = await tempFilePathFor(await this.ensureTempRoot(), 'parquet');
+        const env_5 = { stack: [], error: void 0, hasError: false };
         try {
-            await source.controlConnection.run(`COPY ${quoteIdentifier(sourceTableName)} TO '${escapeSqlString(tempPath)}' (FORMAT 'parquet')`);
+            if (sourceCanvasId === targetCanvasId) {
+                throw validationError('Source and target canvases must differ. Importing copies a table between two canvases.', {
+                    reason: 'import_same_canvas',
+                    recovery: {
+                        hint: 'Pass the canvas id of a different canvas as the source — the table is already on this one.',
+                    },
+                });
+            }
+            const target = __addDisposableResource(env_5, this.holdCanvas(targetCanvasId), false);
+            const source = __addDisposableResource(env_5, this.holdCanvas(sourceCanvasId), false);
+            assertValidIdentifier(sourceTableName, 'table');
+            assertValidIdentifier(asName, 'table');
             options?.signal?.throwIfAborted();
-            await target.controlConnection.run(`CREATE TABLE ${quoteIdentifier(asName)} AS SELECT * FROM read_parquet('${escapeSqlString(tempPath)}')`);
+            const sourceKind = await this.lookupKind(source.controlConnection, sourceTableName);
+            if (sourceKind === undefined) {
+                throw notFound(`Source canvas does not contain a table or view named "${sourceTableName}".`, {
+                    reason: 'missing_table',
+                    sourceCanvasId,
+                    sourceTableName,
+                    recovery: {
+                        hint: "Re-check the source table name, or list the tables staged on the source canvas with this server's dataframe-describe tool.",
+                    },
+                });
+            }
+            const targetExisting = await this.lookupKind(target.controlConnection, asName);
+            if (targetExisting === 'view') {
+                throw validationError(`Target canvas already contains a view named "${asName}". Drop the view or choose a different name.`, {
+                    reason: 'import_view_clash',
+                    asName,
+                    recovery: {
+                        hint: 'Drop the existing view first, or choose a different destination name for the imported table.',
+                    },
+                });
+            }
+            // Drop+create makes import idempotent under re-imports of the same name,
+            // matching registerTable's behavior.
+            await target.controlConnection.run(`DROP TABLE IF EXISTS ${quoteIdentifier(asName)}`);
+            // Round-trip through a scratch Parquet file. Parquet is
+            // built into DuckDB's core (no extension load needed even with
+            // autoload disabled). All column types — including TIMESTAMP/DATE/BLOB
+            // — round-trip losslessly, which an in-memory appender path can't
+            // guarantee for native engine value types.
+            const tempPath = tempFilePathFor(target.scratchDir, 'parquet');
+            try {
+                await source.controlConnection.run(`COPY ${quoteIdentifier(sourceTableName)} TO '${escapeSqlString(tempPath)}' (FORMAT 'parquet')`);
+                options?.signal?.throwIfAborted();
+                await target.controlConnection.run(`CREATE TABLE ${quoteIdentifier(asName)} AS SELECT * FROM read_parquet('${escapeSqlString(tempPath)}')`);
+            }
+            catch (err) {
+                // Best-effort cleanup of a half-written target before surfacing.
+                await target.controlConnection
+                    .run(`DROP TABLE IF EXISTS ${quoteIdentifier(asName)}`)
+                    .catch(() => { });
+                throw this.classify(err, target);
+            }
+            finally {
+                await unlink(tempPath).catch(() => { });
+            }
+            const [columns, rowCount] = await Promise.all([
+                this.columnNames(target.controlConnection, asName),
+                this.countRows(target.controlConnection, asName),
+            ]);
+            return { tableName: asName, rowCount, columns };
         }
-        catch (err) {
-            // Best-effort cleanup of a half-written target before surfacing.
-            await target.controlConnection
-                .run(`DROP TABLE IF EXISTS ${quoteIdentifier(asName)}`)
-                .catch(() => { });
-            throw classifyDuckdbError(err);
+        catch (e_5) {
+            env_5.error = e_5;
+            env_5.hasError = true;
         }
         finally {
-            await unlink(tempPath).catch(() => { });
+            __disposeResources(env_5);
         }
-        const [columns, rowCount] = await Promise.all([
-            this.columnNames(target.controlConnection, asName),
-            this.countRows(target.controlConnection, asName),
-        ]);
-        return { tableName: asName, rowCount, columns };
     }
     async describe(canvasId, _context, options) {
-        const record = this.requireCanvas(canvasId);
-        if (options?.tableName !== undefined) {
-            assertValidIdentifier(options.tableName, 'table');
-        }
-        // Every pushed filter stays qualified with the `t` alias. The join that
-        // made an unqualified `table_name` ambiguous is gone (#324), but keeping
-        // the qualification means re-introducing a second source here cannot
-        // silently resurrect the Binder Error of #235.
-        const filters = [`t.table_schema = 'main'`];
-        if (options?.tableName) {
-            filters.push(`t.table_name = '${escapeSqlString(options.tableName)}'`);
-        }
-        if (options?.kind === 'view') {
-            filters.push(`t.table_type = 'VIEW'`);
-        }
-        else if (options?.kind === 'table') {
-            filters.push(`t.table_type <> 'VIEW'`);
-        }
-        // No join against duckdb_tables(): its `estimated_size` is an estimated row
-        // count, not a byte footprint, so reporting it as `approxSizeBytes` sent a
-        // caller choosing an eviction victim after the wrong table. DuckDB exposes
-        // no per-table byte column at all (#324), so describe() reports none.
-        const reader = await record.controlConnection.runAndReadAll(`SELECT t.table_name, t.table_type
+        const env_6 = { stack: [], error: void 0, hasError: false };
+        try {
+            const record = __addDisposableResource(env_6, this.holdCanvas(canvasId), false);
+            if (options?.tableName !== undefined) {
+                assertValidIdentifier(options.tableName, 'table');
+            }
+            // Every pushed filter stays qualified with the `t` alias. The join that
+            // made an unqualified `table_name` ambiguous is gone (#324), but keeping
+            // the qualification means re-introducing a second source here cannot
+            // silently resurrect the Binder Error of #235.
+            const filters = [`t.table_schema = 'main'`];
+            if (options?.tableName) {
+                filters.push(`t.table_name = '${escapeSqlString(options.tableName)}'`);
+            }
+            if (options?.kind === 'view') {
+                filters.push(`t.table_type = 'VIEW'`);
+            }
+            else if (options?.kind === 'table') {
+                filters.push(`t.table_type <> 'VIEW'`);
+            }
+            // No join against duckdb_tables(): its `estimated_size` is an estimated row
+            // count, not a byte footprint, so reporting it as `approxSizeBytes` sent a
+            // caller choosing an eviction victim after the wrong table. DuckDB exposes
+            // no per-table byte column at all (#324), so describe() reports none.
+            const reader = await record.controlConnection.runAndReadAll(`SELECT t.table_name, t.table_type
        FROM information_schema.tables t
        WHERE ${filters.join(' AND ')}
        ORDER BY t.table_name`);
-        const tableRows = reader.getRowObjectsJson();
-        return await Promise.all(tableRows.map((row) => this.describeOne(record.controlConnection, row.table_name, row.table_type === 'VIEW' ? 'view' : 'table')));
+            const tableRows = reader.getRowObjectsJson();
+            try {
+                return await Promise.all(tableRows.map((row) => this.describeOne(record.controlConnection, row.table_name, row.table_type === 'VIEW' ? 'view' : 'table')));
+            }
+            catch (err) {
+                // Counting a view runs it, and a view past the memory limit spills.
+                throw this.redactHostPaths(err, record);
+            }
+        }
+        catch (e_6) {
+            env_6.error = e_6;
+            env_6.hasError = true;
+        }
+        finally {
+            __disposeResources(env_6);
+        }
     }
     async describeOne(connection, tableName, kind) {
         const [colRows, rowCount] = await Promise.all([
@@ -420,43 +633,103 @@ export class DuckdbProvider {
         };
     }
     async drop(canvasId, name, _context) {
-        const record = this.requireCanvas(canvasId);
-        assertValidIdentifier(name, 'table');
-        const kind = await this.lookupKind(record.controlConnection, name);
-        if (kind === undefined)
-            return false;
-        const dropKeyword = kind === 'view' ? 'VIEW' : 'TABLE';
-        await record.controlConnection.run(`DROP ${dropKeyword} ${quoteIdentifier(name)}`);
-        return true;
+        const env_7 = { stack: [], error: void 0, hasError: false };
+        try {
+            const record = __addDisposableResource(env_7, this.holdCanvas(canvasId), false);
+            assertValidIdentifier(name, 'table');
+            const kind = await this.lookupKind(record.controlConnection, name);
+            if (kind === undefined)
+                return false;
+            const dropKeyword = kind === 'view' ? 'VIEW' : 'TABLE';
+            await record.controlConnection.run(`DROP ${dropKeyword} ${quoteIdentifier(name)}`);
+            return true;
+        }
+        catch (e_7) {
+            env_7.error = e_7;
+            env_7.hasError = true;
+        }
+        finally {
+            __disposeResources(env_7);
+        }
     }
     async clear(canvasId, _context) {
-        const record = this.requireCanvas(canvasId);
-        const reader = await record.controlConnection.runAndReadAll(`SELECT table_name, table_type FROM information_schema.tables WHERE table_schema = 'main'`);
-        const rows = reader.getRowObjectsJson();
-        // Drop views before tables so a dependent view doesn't block its base table.
-        const ordered = [...rows].sort((a, b) => {
-            const aView = a.table_type === 'VIEW';
-            const bView = b.table_type === 'VIEW';
-            if (aView !== bView)
-                return aView ? -1 : 1;
-            return a.table_name.localeCompare(b.table_name);
-        });
-        for (const row of ordered) {
-            const dropKeyword = row.table_type === 'VIEW' ? 'VIEW' : 'TABLE';
-            await record.controlConnection.run(`DROP ${dropKeyword} ${quoteIdentifier(row.table_name)}`);
+        const env_8 = { stack: [], error: void 0, hasError: false };
+        try {
+            const record = __addDisposableResource(env_8, this.holdCanvas(canvasId), false);
+            const reader = await record.controlConnection.runAndReadAll(`SELECT table_name, table_type FROM information_schema.tables WHERE table_schema = 'main'`);
+            const rows = reader.getRowObjectsJson();
+            // Drop views before tables so a dependent view doesn't block its base table.
+            const ordered = [...rows].sort((a, b) => {
+                const aView = a.table_type === 'VIEW';
+                const bView = b.table_type === 'VIEW';
+                if (aView !== bView)
+                    return aView ? -1 : 1;
+                return a.table_name.localeCompare(b.table_name);
+            });
+            for (const row of ordered) {
+                const dropKeyword = row.table_type === 'VIEW' ? 'VIEW' : 'TABLE';
+                await record.controlConnection.run(`DROP ${dropKeyword} ${quoteIdentifier(row.table_name)}`);
+            }
+            return rows.length;
+        }
+        catch (e_8) {
+            env_8.error = e_8;
+            env_8.hasError = true;
+        }
+        finally {
+            __disposeResources(env_8);
         }
-        return rows.length;
     }
     // ---------------------------------------------------------------------
     // Internals
     // ---------------------------------------------------------------------
-    requireCanvas(canvasId) {
+    /**
+     * `canvasId`'s record, held until the caller's `using` scope exits, on
+     * return or throw. {@link destroyCanvas} removes the canvas's spill
+     * directory only once every hold on that canvas is released, so a call
+     * already running can still read back the blocks it spilled. {@link shutdown}
+     * removes the scratch directory only once every hold taken before it began
+     * is released, so a call already running finishes inside the private
+     * directory, never in one another local user re-created under its name.
+     * Every data-plane call reaches its record through a hold.
+     */
+    holdCanvas(canvasId) {
         const record = this.canvases.get(canvasId);
         // Defensive — CanvasInstance touches the registry first, which throws the
         // same structured canvas_not_found before the provider is reached (#261).
         if (!record)
             throw canvasNotFound(canvasId);
-        return record;
+        const { promise, resolve } = Promise.withResolvers();
+        this.holds.add(promise);
+        record.holds.add(promise);
+        return {
+            ...record,
+            [Symbol.dispose]: () => {
+                this.holds.delete(promise);
+                record.holds.delete(promise);
+                resolve();
+            },
+        };
+    }
+    /** Host directories an engine message can quote and a caller must not see. */
+    hostPaths(record) {
+        return [resolve(this.options.exportRootPath), record.scratchDir];
+    }
+    /** {@link classifyDuckdbError} with this canvas's host directories redacted. */
+    classify(err, record) {
+        return classifyDuckdbError(err, this.hostPaths(record));
+    }
+    /**
+     * `err` classified and redacted when it is an engine error naming a host
+     * directory; anything else as it came. For blocks that also run code other
+     * than the engine's — a caller's row source, a cancellation check — whose
+     * failures must reach the caller as thrown.
+     */
+    redactHostPaths(err, record) {
+        if (!(err instanceof Error) || err instanceof McpError)
+            return err;
+        const paths = this.hostPaths(record);
+        return redactPaths(err.message, paths) === err.message ? err : classifyDuckdbError(err, paths);
     }
     /**
      * Runs `fn` on a connection of its own, so an abort interrupts only this
@@ -483,7 +756,7 @@ export class DuckdbProvider {
         catch (err) {
             if (cancelled)
                 throw timeout(cancelledMessage, { reason: 'cancelled' }, { cause: err });
-            throw classifyDuckdbError(err);
+            throw this.classify(err, record);
         }
         finally {
             signal?.removeEventListener('abort', onAbort);
@@ -507,18 +780,19 @@ export class DuckdbProvider {
     }
     /**
      * The rejection for a statement that failed to parse or prepare: a
-     * SELECT-shaped statement surfaces the sanitized binder message (the SQL
-     * itself is probably wrong), anything else is rejected as non-SELECT.
+     * SELECT-shaped statement surfaces the binder message, host directories
+     * redacted (the SQL itself is probably wrong), anything else is rejected as
+     * non-SELECT.
      */
-    prepareFailure(sql, err) {
+    prepareFailure(sql, err, record) {
         if (isSelectShaped(sql) && err instanceof Error) {
-            const binderMessage = sanitizeBinderMessage(err.message, this.options.exportRootPath);
+            const binderMessage = redactPaths(err.message.trim(), this.hostPaths(record));
             return validationError(`Canvas query failed to prepare: ${binderMessage}`, {
                 reason: SQL_GATE_REASONS.invalidSql,
                 statementType: 'UNKNOWN',
                 binderMessage,
                 ...gateRecovery(SQL_GATE_REASONS.invalidSql),
-            });
+            }, { cause: err });
         }
         return validationError('Canvas query must be SELECT; the statement could not be parsed or prepared.', {
             reason: SQL_GATE_REASONS.nonSelectStatement,
@@ -540,10 +814,9 @@ export class DuckdbProvider {
         // Layer 1: text-level deny-list. read_json/read_parquet/... lower into
         // generic scans that pass the operator allowlist, so reject by name first.
         assertNoDeniedFunctions(sql);
-        // Layers 2-3: parse and type-check before EXPLAIN.
-        // Fail closed: if extractStatements or prepare(0) throws for a missing-
-        // table binder error, surface NotFound so the agent knows to re-stage.
-        // Any other error is treated as non-SELECT (the existing fail-closed path).
+        // Layers 2-3: parse and type-check before EXPLAIN. Fail closed: a statement
+        // that cannot be parsed or prepared is rejected — as a missing table, an
+        // invalid SELECT, or a non-SELECT (see `prepareFailure`).
         let statementCount;
         let statementType;
         try {
@@ -557,23 +830,31 @@ export class DuckdbProvider {
                     statementType = duck.StatementType[typeInt] ?? 'UNKNOWN';
                 }
                 catch (prepErr) {
-                    // DuckDB raises a Catalog/Binder error at prepare time when the
-                    // referenced table doesn't exist. Surface a structured NotFound so
-                    // the agent knows to re-stage rather than blaming the SQL shape.
-                    if (prepErr instanceof Error) {
-                        const tableNameMatch = prepErr.message.match(/Table with name (\S+) does not exist|Catalog Error:.*?(\S+) does not exist/i);
-                        if (tableNameMatch) {
-                            const tableName = tableNameMatch[1] ?? tableNameMatch[2];
-                            throw notFound(`Canvas table ${tableName ? `"${tableName}"` : '(unknown)'} does not exist. The table may have expired, been dropped, or the name may be mistyped.`, {
+                    // DuckDB raises a Catalog error at prepare time when the referenced
+                    // table doesn't exist. Surface a structured NotFound so the agent
+                    // knows to re-stage rather than blaming the SQL shape. Only the
+                    // table form qualifies: a missing function, table function, type,
+                    // collation, or schema is a Catalog error too, but the SQL is what
+                    // is wrong, so it falls through to invalid_sql with the binder
+                    // detail (#484). A schema miss is phrased "Table with name "s.t"
+                    // does not exist because schema …", without the closing `!`. The
+                    // name is captured whole, since a quoted one can contain spaces.
+                    // A DROP/DELETE/INSERT/UPDATE/ALTER naming a missing table fails
+                    // with the same text, but re-staging would not make it pass, so only
+                    // a read-shaped statement qualifies; the rest fall to non-SELECT.
+                    if (prepErr instanceof Error && isSelectShaped(sql)) {
+                        const tableName = prepErr.message.match(/Catalog Error: Table with name (.+?) does not exist!/)?.[1];
+                        if (tableName) {
+                            throw notFound(`Canvas table "${tableName}" does not exist. The table may have expired, been dropped, or the name may be mistyped.`, {
                                 reason: 'missing_table',
-                                ...(tableName && { tableName }),
+                                tableName,
                                 recovery: {
                                     hint: "Re-run the tool that produced this table to stage it again, or list the currently staged tables with this server's dataframe-describe tool.",
                                 },
                             });
                         }
                     }
-                    throw this.prepareFailure(sql, prepErr);
+                    throw this.prepareFailure(sql, prepErr, record);
                 }
                 finally {
                     prepared?.destroySync();
@@ -590,7 +871,7 @@ export class DuckdbProvider {
             // can carry errno-style `code` props and must not escape the gate raw.
             if (err instanceof McpError)
                 throw err;
-            throw this.prepareFailure(sql, err);
+            throw this.prepareFailure(sql, err, record);
         }
         assertSelectOnly({ statementCount, statementType });
         // Layer 4: walk the plan with the allowlist + denied-function rescan.
@@ -841,26 +1122,27 @@ function escapeSqlString(value) {
 }
 /**
  * SELECT-shape probe for prepare-failure classification. A statement that
- * starts with `SELECT` or `WITH` (CTE) but throws at prepare time is an invalid
- * SELECT (unknown column/function/expression), not a non-SELECT statement.
+ * starts with `SELECT`, `WITH` (CTE), or `FROM` (DuckDB's FROM-first form) but
+ * throws at prepare time is an invalid SELECT (missing table, unknown
+ * column/function/expression), not a non-SELECT statement. Only classifies a
+ * failure: a statement that prepares is judged by its statement type.
  */
 function isSelectShaped(sql) {
-    return /^\s*(?:select|with)\b/i.test(sql);
+    return /^\s*(?:select|with|from)\b/i.test(sql);
 }
 /**
- * Strip any occurrence of the configured export root path from a DuckDB binder
- * message before it leaves the gate. Column/function/expression binder errors
- * carry no host or path material, but the export root is the one local path
- * that could in principle appear — redact it defensively so the detail surfaced
- * to callers stays free of filesystem hints.
+ * Replace every occurrence of each host directory in an engine message with
+ * `[path]`, longest first so a directory nested inside another is redacted
+ * whole. DuckDB quotes the absolute export and scratch paths it failed on;
+ * the part below the directory — the caller's own export name — stays. A
+ * one-character path (the filesystem root) is skipped, since replacing it
+ * would mangle every path in the message.
  */
-function sanitizeBinderMessage(raw, exportRootPath) {
-    const trimmed = raw.trim();
-    if (exportRootPath.length > 1) {
-        const escaped = exportRootPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-        return trimmed.replace(new RegExp(escaped, 'g'), '[path]');
-    }
-    return trimmed;
+function redactPaths(message, paths) {
+    return paths
+        .filter((path) => path.length > 1)
+        .sort((a, b) => b.length - a.length)
+        .reduce((text, path) => text.replaceAll(path, '[path]'), message);
 }
 async function ensureTableMissing(connection, tableName) {
     const reader = await connection.runAndReadAll(`SELECT 1 FROM information_schema.tables WHERE table_schema = 'main' AND table_name = '${escapeSqlString(tableName)}' LIMIT 1`);
@@ -876,7 +1158,10 @@ async function ensureTableMissing(connection, tableName) {
 export const DUCKDB_ERROR_REASONS = {
     /** SQL the engine could not parse. */
     sqlParseError: 'sql_parse_error',
-    /** A write the engine refused, or a permission it denied. */
+    /**
+     * A write the engine refused, or file access its configuration denies —
+     * never the operating system refusing a file, which is an I/O fault.
+     */
     sqlReadOnly: 'sql_read_only',
     /** A gated SELECT that prepared cleanly and then failed on the staged data. */
     sqlExecutionError: 'sql_execution_error',
@@ -902,6 +1187,18 @@ const DUCKDB_ERROR_RECOVERY = {
  * merely quotes a data-error class mid-sentence is still an engine fault.
  */
 const DUCKDB_EXECUTION_ERROR_PREFIX = /^(?:Conversion|Invalid Input|Out of Range) Error\b/;
+/**
+ * DuckDB's refusals, anchored on the class prefix the engine gives them:
+ * `Permission Error` (file access with `enable_external_access` off), and a
+ * write attempted in a read-only transaction (`TransactionContext Error: …
+ * read-only mode`) or against a read-only database (`Invalid Input Error: …
+ * attached in read-only mode!`). An `IO Error` never matches, whatever its
+ * text: `Permission denied` and `Read-only file system` there are the
+ * operating system refusing a file, an engine fault the caller cannot act on.
+ */
+const DUCKDB_REFUSAL = /^(?:Permission Error\b|(?:TransactionContext|Invalid Input) Error: .*\bread-only mode\b)/;
+/** DuckDB's parser class; a quoted file name mentioning "syntax" is not one. */
+const DUCKDB_PARSER_ERROR_PREFIX = /^Parser Error\b/;
 /**
  * Map a DuckDB-thrown error to a framework error class. Classification is for
  * raw engine errors only — an already-structured `McpError` passes through
@@ -910,31 +1207,35 @@ const DUCKDB_EXECUTION_ERROR_PREFIX = /^(?:Conversion|Invalid Input|Out of Range
  * validations) must keep their code and `data.reason` instead of being
  * reclassified as `DatabaseError`.
  *
- * The three caller-side classes are `ValidationError`; everything else — I/O,
- * internal, out-of-memory, transaction, interrupt — stays `DatabaseError`,
- * which is what an export or Parquet round-trip failing on the filesystem
- * must remain.
+ * The three caller-side classes are `ValidationError`, each matched on the
+ * engine's own class prefix; everything else — I/O, internal, out-of-memory,
+ * transaction conflict, interrupt — stays `DatabaseError`, which is what an
+ * export or Parquet round-trip failing on the filesystem must remain (#565).
+ * Every `redact` path in the message becomes `[path]`; the raw engine error,
+ * paths included, stays on `cause`.
  * @internal Exported for unit testing.
  */
-export function classifyDuckdbError(err) {
+export function classifyDuckdbError(err, redact = []) {
     if (err instanceof McpError)
         return err;
     if (err instanceof Error) {
-        const msg = err.message;
-        // Checked first: the anchored class prefix is a stronger signal than the
-        // loose word matches below, which a data-error message can also satisfy.
+        const msg = redactPaths(err.message, redact);
+        // Checked before the execution prefix: a write refused by a read-only
+        // database is phrased as an `Invalid Input Error`.
+        if (DUCKDB_REFUSAL.test(msg)) {
+            return engineFailure(DUCKDB_ERROR_REASONS.sqlReadOnly, `Canvas SQL rejected: ${msg}`, err);
+        }
         if (DUCKDB_EXECUTION_ERROR_PREFIX.test(msg)) {
             return engineFailure(DUCKDB_ERROR_REASONS.sqlExecutionError, `Canvas query failed: ${msg}`, err);
         }
-        if (/parser error|syntax/i.test(msg)) {
+        if (DUCKDB_PARSER_ERROR_PREFIX.test(msg)) {
             return engineFailure(DUCKDB_ERROR_REASONS.sqlParseError, `Canvas SQL rejected: ${msg}`, err);
         }
-        if (/permission|read.?only/i.test(msg)) {
-            return engineFailure(DUCKDB_ERROR_REASONS.sqlReadOnly, `Canvas SQL rejected: ${msg}`, err);
-        }
         return databaseError(msg, undefined, { cause: err });
     }
-    return databaseError('DuckDB threw a non-Error value.', { value: String(err) });
+    return databaseError('DuckDB threw a non-Error value.', {
+        value: redactPaths(String(err), redact),
+    });
 }
 /** A caller-side engine failure: reason, contract recovery, and the engine error chained. */
 function engineFailure(reason, message, cause) {