@cyanheads/mcp-ts-core 0.8.11 → 0.8.13

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

@@ -1,30 +1,23 @@
 /**
- * @fileoverview DuckDB-backed implementation of {@link IDataCanvasProvider}.
- * One DuckDB instance per canvasId for memory isolation; a shared connection
- * for control-plane work (DDL, describe, drop) and per-query connections for
- * data-plane work so that {@link DuckDBConnection.interrupt} cancels exactly
- * the in-flight query without disturbing concurrent ops on the same canvas.
- *
- * Lazy-loaded via {@link lazyImport} so `@duckdb/node-api` stays a true peer
- * dependency — servers that don't enable canvas pay no install cost.
- *
+ * @fileoverview DuckDB-backed {@link IDataCanvasProvider}. One in-memory
+ * DuckDB instance per canvasId; a long-lived control connection for DDL and
+ * describe operations, plus a per-query connection so cancellation interrupts
+ * exactly the in-flight query. `@duckdb/node-api` is lazy-loaded so it stays
+ * a true peer dependency.
  * @module src/services/canvas/providers/duckdb/DuckdbProvider
  */
-import { databaseError, notFound, validationError } from '../../../../types-global/errors.js';
+import { unlink } from 'node:fs/promises';
+import { databaseError, notFound, timeout, validationError } from '../../../../types-global/errors.js';
 import { lazyImport } from '../../../../utils/internal/lazyImport.js';
 import { logger } from '../../../../utils/internal/logger.js';
 import { requestContextService } from '../../../../utils/internal/requestContext.js';
-import { assertPlanReadOnly, assertSelectOnly, assertValidIdentifier, quoteIdentifier, } from '../../core/sqlGate.js';
+import { assertNoDeniedFunctions, assertPlanReadOnly, assertSelectOnly, assertValidIdentifier, quoteIdentifier, } from '../../core/sqlGate.js';
 import { copyFormatClause, isPathTarget, pipeFileToStream, resolveExportPath, safeSizeBytes, tempFilePathFor, } from './exportWriter.js';
 import { sniffSchema } from './schemaSniffer.js';
-/** Lazy import binding — preserves bundler-friendly module specifiers. */
 const importDuckDB = lazyImport(() => import('@duckdb/node-api'), 'Install "@duckdb/node-api" to use the DuckDB canvas provider: bun add @duckdb/node-api');
-/** DuckDB SELECT statement-type id (matches `StatementType.SELECT === 1`). */
-const STATEMENT_TYPE_SELECT_ID = 1;
 export class DuckdbProvider {
     options;
     name = 'duckdb';
-    duck;
     canvases = new Map();
     constructor(options) {
         this.options = options;
@@ -35,15 +28,14 @@ export class DuckdbProvider {
     async initCanvas(canvasId, _context) {
         if (this.canvases.has(canvasId))
             return;
-        const duck = await this.getModule();
+        const duck = await importDuckDB();
         const instance = await duck.DuckDBInstance.create(':memory:', {
             memory_limit: `${this.options.memoryLimitMb}MB`,
-            // Disable secrets/extensions install paths for safety in canvas mode.
+            // Disable extension install/load paths in canvas mode.
             autoinstall_known_extensions: 'false',
             autoload_known_extensions: 'false',
         });
         const controlConnection = await instance.connect();
-        // Belt-and-suspenders — also set the limit on the connection.
         await controlConnection.run(`SET memory_limit = '${this.options.memoryLimitMb}MB'`);
         this.canvases.set(canvasId, { instance, controlConnection });
     }
@@ -78,7 +70,7 @@ export class DuckdbProvider {
     }
     async healthCheck() {
         try {
-            const duck = await this.getModule();
+            const duck = await importDuckDB();
             const instance = await duck.DuckDBInstance.create(':memory:');
             const conn = await instance.connect();
             await conn.run('SELECT 1');
@@ -95,20 +87,20 @@ export class DuckdbProvider {
             operation: 'DuckdbProvider.shutdown',
         });
         const ids = [...this.canvases.keys()];
-        for (const id of ids) {
-            await this.destroyCanvas(id, context);
-        }
+        await Promise.allSettled(ids.map((id) => this.destroyCanvas(id, context)));
     }
     // ---------------------------------------------------------------------
     // 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;
         }
@@ -119,12 +111,11 @@ export class DuckdbProvider {
             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');
-        // Re-create the table — the issue's lifecycle guarantees a fresh canvasId
-        // per acquire, but explicit drop+create makes register idempotent under
-        // re-registration of the same name.
+        // 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);
@@ -134,7 +125,7 @@ export class DuckdbProvider {
         try {
             const appendOne = (row) => {
                 for (const col of schema) {
-                    appendValue(appender, col, row[col.name]);
+                    appendValue(appender, col, row[col.name], duck);
                 }
                 appender.endRow();
                 count += 1;
@@ -145,22 +136,25 @@ export class DuckdbProvider {
                     appendOne(row);
                 }
             }
-            // Drain whatever's left of the iterable.
             if (isAsyncIterable) {
                 for await (const row of rows) {
                     options?.signal?.throwIfAborted();
                     appendOne(row);
                 }
             }
-            else if (!bufferedRows) {
-                for (const row of rows) {
+            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(row);
+                    appendOne(next.value);
+                    next = remainingSync.next();
                 }
             }
             else {
-                // Sniffer consumed bufferedRows but the iterable may have more.
-                for (const row of skipFirst(rows, bufferedRows.length)) {
+                for (const row of rows) {
                     options?.signal?.throwIfAborted();
                     appendOne(row);
                 }
@@ -177,28 +171,10 @@ export class DuckdbProvider {
     }
     async query(canvasId, sql, _context, options) {
         const record = this.requireCanvas(canvasId);
+        const duck = await importDuckDB();
         options?.signal?.throwIfAborted();
-        // Step 1: parse and type-check before invoking EXPLAIN.
-        const extracted = await record.controlConnection.extractStatements(sql);
-        const statementCount = extracted.count;
-        let statementType;
-        if (statementCount === 1) {
-            const prepared = await extracted.prepare(0);
-            try {
-                statementType = prepared.statementType;
-            }
-            finally {
-                prepared.destroySync();
-            }
-        }
-        assertSelectOnly({
-            statementCount,
-            statementType: statementTypeIdToString(statementType),
-        });
-        // Step 2: walk the plan with the allowlist (defense in depth).
-        const planJson = await this.runExplain(record.controlConnection, `EXPLAIN (FORMAT JSON) ${sql}`);
-        assertPlanReadOnly(planJson);
-        // Step 3: per-query connection so cancellation is scoped to this call.
+        await this.assertReadOnlySql(record, sql, duck);
+        // Per-query connection so cancellation interrupts only this call.
         const conn = await record.instance.connect();
         let cancelled = false;
         const onAbort = () => {
@@ -207,7 +183,7 @@ export class DuckdbProvider {
                 conn.interrupt();
             }
             catch {
-                // interrupt is best-effort; closeSync still cleans up.
+                /* interrupt is best-effort; closeSync still cleans up. */
             }
         };
         options?.signal?.addEventListener('abort', onAbort, { once: true });
@@ -220,18 +196,14 @@ export class DuckdbProvider {
             let totalRowCount = 0;
             if (options?.registerAs) {
                 assertValidIdentifier(options.registerAs, 'table');
-                // Reject clash with existing canvas table.
                 await ensureTableMissing(record.controlConnection, options.registerAs);
                 const ctas = `CREATE TABLE ${quoteIdentifier(options.registerAs)} AS ${sql}`;
                 await conn.run(ctas);
                 registeredAs = options.registerAs;
-                // Read a preview off the new table (cheap because rows are local).
                 const reader = await conn.runAndReadUntil(`SELECT * FROM ${quoteIdentifier(options.registerAs)} LIMIT ${preview}`, preview);
                 rowsToReturn = reader.getRowObjectsJson();
                 columns = reader.columnNames();
-                const countReader = await conn.runAndReadAll(`SELECT COUNT(*) AS n FROM ${quoteIdentifier(options.registerAs)}`);
-                const countRow = countReader.getRowObjectsJson()[0];
-                totalRowCount = Number(countRow?.n ?? 0);
+                totalRowCount = await this.countRows(conn, options.registerAs);
             }
             else {
                 const reader = await conn.runAndReadAll(sql);
@@ -249,7 +221,7 @@ export class DuckdbProvider {
         }
         catch (err) {
             if (cancelled) {
-                throw validationError('Canvas query was cancelled.', { reason: 'cancelled' }, { cause: err });
+                throw timeout('Canvas query was cancelled.', { reason: 'cancelled' }, { cause: err });
             }
             throw classifyDuckdbError(err);
         }
@@ -259,7 +231,7 @@ export class DuckdbProvider {
                 conn.closeSync();
             }
             catch {
-                // Connection may already be torn down by interrupt — ignore.
+                /* Connection may already be torn down by interrupt. */
             }
         }
     }
@@ -269,20 +241,19 @@ export class DuckdbProvider {
         options?.signal?.throwIfAborted();
         const formatClause = copyFormatClause(target.format);
         const conn = await record.instance.connect();
+        let cancelled = false;
         const onAbort = () => {
+            cancelled = true;
             try {
                 conn.interrupt();
             }
             catch {
-                /* noop */
+                /* interrupt is best-effort. */
             }
         };
         options?.signal?.addEventListener('abort', onAbort, { once: true });
         try {
-            // Row count from the table — cheap, used for the result payload.
-            const countReader = await conn.runAndReadAll(`SELECT COUNT(*) AS n FROM ${quoteIdentifier(tableName)}`);
-            const countRow = countReader.getRowObjectsJson()[0];
-            const rowCount = Number(countRow?.n ?? 0);
+            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}`);
@@ -294,10 +265,17 @@ export class DuckdbProvider {
                     rowCount,
                 };
             }
-            // Stream branch: copy to temp file in sandbox, pipe to caller's stream,
-            // then unlink. tempFilePathFor() creates the sandbox root if missing.
+            // Stream branch: COPY to a sandbox temp 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(this.options.exportRootPath, target.format);
-            await conn.run(`COPY ${quoteIdentifier(tableName)} TO '${escapeSqlString(tempPath)}' ${formatClause}`);
+            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,
@@ -306,6 +284,9 @@ export class DuckdbProvider {
             };
         }
         catch (err) {
+            if (cancelled) {
+                throw timeout('Canvas export was cancelled.', { reason: 'cancelled' }, { cause: err });
+            }
             throw classifyDuckdbError(err);
         }
         finally {
@@ -314,57 +295,156 @@ export class DuckdbProvider {
                 conn.closeSync();
             }
             catch {
-                /* noop */
+                /* Already torn down by interrupt. */
             }
         }
     }
+    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?.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 });
+        }
+        try {
+            await record.controlConnection.run(`CREATE OR REPLACE VIEW ${quoteIdentifier(name)} AS ${selectSql}`);
+        }
+        catch (err) {
+            throw classifyDuckdbError(err);
+        }
+        const colReader = await record.controlConnection.runAndReadAll(`SELECT column_name FROM information_schema.columns ` +
+            `WHERE table_schema = 'main' AND table_name = '${escapeSqlString(name)}' ` +
+            `ORDER BY ordinal_position`);
+        const columns = colReader.getRowObjectsJson().map((r) => r.column_name);
+        return { viewName: name, columns };
+    }
+    async importFrom(targetCanvasId, sourceCanvasId, sourceTableName, asName, _context, options) {
+        if (sourceCanvasId === targetCanvasId) {
+            throw validationError('Source and target canvases must differ. Use registerAs in query() to materialize within a single canvas.', { reason: 'import_same_canvas' });
+        }
+        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}".`, {
+                sourceCanvasId,
+                sourceTableName,
+            });
+        }
+        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 });
+        }
+        // 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 sandbox-rooted temp 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(this.options.exportRootPath, '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 classifyDuckdbError(err);
+        }
+        finally {
+            await unlink(tempPath).catch(() => { });
+        }
+        const [colReader, rowCount] = await Promise.all([
+            target.controlConnection.runAndReadAll(`SELECT column_name FROM information_schema.columns ` +
+                `WHERE table_schema = 'main' AND table_name = '${escapeSqlString(asName)}' ` +
+                `ORDER BY ordinal_position`),
+            this.countRows(target.controlConnection, asName),
+        ]);
+        const columns = colReader.getRowObjectsJson().map((r) => r.column_name);
+        return { tableName: asName, rowCount, columns };
+    }
     async describe(canvasId, _context, options) {
         const record = this.requireCanvas(canvasId);
         if (options?.tableName !== undefined) {
             assertValidIdentifier(options.tableName, 'table');
         }
-        const filter = options?.tableName
-            ? ` AND table_name = '${escapeSqlString(options.tableName)}'`
-            : '';
-        const reader = await record.controlConnection.runAndReadAll(`SELECT table_name FROM information_schema.tables WHERE table_schema = 'main'${filter} ORDER BY table_name`);
+        const filters = [`table_schema = 'main'`];
+        if (options?.tableName) {
+            filters.push(`table_name = '${escapeSqlString(options.tableName)}'`);
+        }
+        if (options?.kind === 'view') {
+            filters.push(`table_type = 'VIEW'`);
+        }
+        else if (options?.kind === 'table') {
+            filters.push(`table_type <> 'VIEW'`);
+        }
+        const reader = await record.controlConnection.runAndReadAll(`SELECT table_name, table_type FROM information_schema.tables WHERE ${filters.join(' AND ')} ORDER BY table_name`);
         const tableRows = reader.getRowObjectsJson();
-        const result = [];
-        for (const row of tableRows) {
-            const tableName = row.table_name;
-            const colReader = await record.controlConnection.runAndReadAll(`SELECT column_name, data_type, is_nullable FROM information_schema.columns ` +
+        return await Promise.all(tableRows.map((row) => this.describeOne(record.controlConnection, row.table_name, row.table_type === 'VIEW' ? 'view' : 'table')));
+    }
+    async describeOne(connection, tableName, kind) {
+        const [colReader, rowCount] = await Promise.all([
+            connection.runAndReadAll(`SELECT column_name, data_type, is_nullable FROM information_schema.columns ` +
                 `WHERE table_schema = 'main' AND table_name = '${escapeSqlString(tableName)}' ` +
-                `ORDER BY ordinal_position`);
-            const colRows = colReader.getRowObjectsJson();
-            const columns = colRows.map((c) => ({
-                name: c.column_name,
-                type: dataTypeToColumnType(c.data_type),
-                nullable: c.is_nullable === 'YES',
-            }));
-            const countReader = await record.controlConnection.runAndReadAll(`SELECT COUNT(*) AS n FROM ${quoteIdentifier(tableName)}`);
-            const countRow = countReader.getRowObjectsJson()[0];
-            result.push({
-                name: tableName,
-                rowCount: Number(countRow?.n ?? 0),
-                columns,
-            });
-        }
-        return result;
+                `ORDER BY ordinal_position`),
+            this.countRows(connection, tableName),
+        ]);
+        const colRows = colReader.getRowObjectsJson();
+        const columns = colRows.map((c) => ({
+            name: c.column_name,
+            type: dataTypeToColumnType(c.data_type),
+            nullable: c.is_nullable === 'YES',
+        }));
+        return {
+            name: tableName,
+            kind,
+            rowCount,
+            columns,
+        };
     }
     async drop(canvasId, name, _context) {
         const record = this.requireCanvas(canvasId);
         assertValidIdentifier(name, 'table');
-        const checkReader = await record.controlConnection.runAndReadAll(`SELECT 1 FROM information_schema.tables WHERE table_schema = 'main' AND table_name = '${escapeSqlString(name)}' LIMIT 1`);
-        if (checkReader.getRowsJson().length === 0)
+        const kind = await this.lookupKind(record.controlConnection, name);
+        if (kind === undefined)
             return false;
-        await record.controlConnection.run(`DROP TABLE ${quoteIdentifier(name)}`);
+        const dropKeyword = kind === 'view' ? 'VIEW' : 'TABLE';
+        await record.controlConnection.run(`DROP ${dropKeyword} ${quoteIdentifier(name)}`);
         return true;
     }
     async clear(canvasId, _context) {
         const record = this.requireCanvas(canvasId);
-        const reader = await record.controlConnection.runAndReadAll(`SELECT table_name FROM information_schema.tables WHERE table_schema = 'main'`);
+        const reader = await record.controlConnection.runAndReadAll(`SELECT table_name, table_type FROM information_schema.tables WHERE table_schema = 'main'`);
         const rows = reader.getRowObjectsJson();
-        for (const row of rows) {
-            await record.controlConnection.run(`DROP TABLE ${quoteIdentifier(row.table_name)}`);
+        // 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;
     }
@@ -378,26 +458,75 @@ export class DuckdbProvider {
         }
         return record;
     }
-    async getModule() {
-        if (!this.duck)
-            this.duck = await importDuckDB();
-        return this.duck;
+    /**
+     * Run the same four-layer read-only gate `query()` enforces, against an
+     * arbitrary SELECT string. Used by `query()` and `registerView()` so view
+     * definitions inherit query-level safety.
+     */
+    async assertReadOnlySql(record, sql, duck) {
+        // 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.
+        const extracted = await record.controlConnection.extractStatements(sql);
+        const statementCount = extracted.count;
+        let statementType;
+        if (statementCount === 1) {
+            const prepared = await extracted.prepare(0);
+            try {
+                statementType = prepared.statementType;
+            }
+            finally {
+                prepared.destroySync();
+            }
+        }
+        assertSelectOnly({
+            statementCount,
+            statementType: statementType !== undefined ? (duck.StatementType[statementType] ?? 'UNKNOWN') : 'UNKNOWN',
+        });
+        // Layer 4: walk the plan with the allowlist + denied-function rescan.
+        const planJson = await this.runExplain(record.controlConnection, `EXPLAIN (FORMAT JSON) ${sql}`);
+        assertPlanReadOnly(planJson);
+    }
+    /**
+     * Resolve whether a name on the canvas refers to a base table, a view, or
+     * nothing. Returns `undefined` when absent; used by drop/registerView/
+     * importFrom to dispatch the right DDL.
+     */
+    async lookupKind(connection, name) {
+        const reader = await connection.runAndReadAll(`SELECT table_type FROM information_schema.tables ` +
+            `WHERE table_schema = 'main' AND table_name = '${escapeSqlString(name)}' LIMIT 1`);
+        const rows = reader.getRowObjectsJson();
+        if (rows.length === 0)
+            return;
+        return rows[0]?.table_type === 'VIEW' ? 'view' : 'table';
+    }
+    /**
+     * Materialize `COUNT(*)` against a (validated) table or view name. DuckDB
+     * returns BIGINT as a JSON string; this helper centralizes the `Number(...)`
+     * coercion so callers see a plain `number`.
+     */
+    async countRows(connection, name) {
+        const reader = await connection.runAndReadAll(`SELECT COUNT(*) AS n FROM ${quoteIdentifier(name)}`);
+        const row = reader.getRowObjectsJson()[0];
+        return Number(row?.n ?? 0);
     }
     async runExplain(connection, explainSql) {
         const reader = await connection.runAndReadAll(explainSql);
         const rows = reader.getRowObjectsJson();
-        // EXPLAIN returns a single row with an `explain_value` column containing
-        // the JSON tree as a string.
+        // EXPLAIN returns one row with `explain_value` as the JSON tree string.
+        // Fail loud if the shape changes — a silent fallback would let queries
+        // bypass the plan-walk gate.
         const value = rows[0]?.explain_value;
-        if (typeof value === 'string') {
-            try {
-                return JSON.parse(value);
-            }
-            catch (err) {
-                throw databaseError('Failed to parse EXPLAIN plan JSON.', undefined, { cause: err });
-            }
+        if (typeof value !== 'string') {
+            throw databaseError('EXPLAIN returned an unexpected shape; canvas plan-walk cannot run safely.', { rowCount: rows.length, hasExplainValue: rows[0]?.explain_value !== undefined });
+        }
+        try {
+            return JSON.parse(value);
+        }
+        catch (err) {
+            throw databaseError('Failed to parse EXPLAIN plan JSON.', undefined, { cause: err });
         }
-        return rows;
     }
 }
 // ---------------------------------------------------------------------------
@@ -409,32 +538,10 @@ function buildCreateTableSql(tableName, schema) {
     }
     const cols = schema.map((c) => {
         const nullable = c.nullable === false ? ' NOT NULL' : '';
-        return `${quoteIdentifier(c.name)} ${columnTypeToSql(c.type)}${nullable}`;
+        return `${quoteIdentifier(c.name)} ${c.type}${nullable}`;
     });
     return `CREATE TABLE ${quoteIdentifier(tableName)} (${cols.join(', ')})`;
 }
-function columnTypeToSql(type) {
-    switch (type) {
-        case 'VARCHAR':
-            return 'VARCHAR';
-        case 'INTEGER':
-            return 'INTEGER';
-        case 'BIGINT':
-            return 'BIGINT';
-        case 'DOUBLE':
-            return 'DOUBLE';
-        case 'BOOLEAN':
-            return 'BOOLEAN';
-        case 'TIMESTAMP':
-            return 'TIMESTAMP';
-        case 'DATE':
-            return 'DATE';
-        case 'JSON':
-            return 'JSON';
-        case 'BLOB':
-            return 'BLOB';
-    }
-}
 /** Map DuckDB `information_schema.columns.data_type` strings back to {@link ColumnType}. */
 function dataTypeToColumnType(dataType) {
     const upper = dataType.toUpperCase();
@@ -458,71 +565,13 @@ function dataTypeToColumnType(dataType) {
         return 'BLOB';
     return 'VARCHAR';
 }
-/** Convert a DuckDB `StatementType` numeric id to a string the gate can match. */
-function statementTypeIdToString(id) {
-    switch (id) {
-        case 1:
-            return 'SELECT';
-        case 2:
-            return 'INSERT';
-        case 3:
-            return 'UPDATE';
-        case 4:
-            return 'EXPLAIN';
-        case 5:
-            return 'DELETE';
-        case 6:
-            return 'PREPARE';
-        case 7:
-            return 'CREATE';
-        case 8:
-            return 'EXECUTE';
-        case 9:
-            return 'ALTER';
-        case 10:
-            return 'TRANSACTION';
-        case 11:
-            return 'COPY';
-        case 12:
-            return 'ANALYZE';
-        case 13:
-            return 'VARIABLE_SET';
-        case 14:
-            return 'CREATE_FUNC';
-        case 15:
-            return 'DROP';
-        case 16:
-            return 'EXPORT';
-        case 17:
-            return 'PRAGMA';
-        case 18:
-            return 'VACUUM';
-        case 19:
-            return 'CALL';
-        case 20:
-            return 'SET';
-        case 21:
-            return 'LOAD';
-        case 22:
-            return 'RELATION';
-        case 23:
-            return 'EXTENSION';
-        case 24:
-            return 'LOGICAL_PLAN';
-        case 25:
-            return 'ATTACH';
-        case 26:
-            return 'DETACH';
-        case 27:
-            return 'MULTI';
-        default:
-            return 'UNKNOWN';
-    }
-}
-/** Re-export for tests and consumer-side parsing. */
-export { STATEMENT_TYPE_SELECT_ID };
-/** Append a single value via the DuckDB appender, dispatched on column type. */
-function appendValue(appender, col, value) {
+/**
+ * Append a value through the DuckDB appender, dispatched by column type.
+ * `duck` carries the typed value constructors needed for TIMESTAMP/DATE.
+ * Incompatible values fail fast with a structured `validationError` rather
+ * than coercing through `String(value)` (which corrupts Dates and binary).
+ */
+function appendValue(appender, col, value, duck) {
     if (value === null || value === undefined) {
         appender.appendNull();
         return;
@@ -535,7 +584,7 @@ function appendValue(appender, col, value) {
             appender.appendInteger(Number(value));
             return;
         case 'BIGINT':
-            appender.appendBigInt(typeof value === 'bigint' ? value : BigInt(Math.trunc(Number(value))));
+            appender.appendBigInt(toBigInt(value));
             return;
         case 'DOUBLE':
             appender.appendDouble(Number(value));
@@ -547,22 +596,121 @@ function appendValue(appender, col, value) {
             appender.appendVarchar(typeof value === 'string' ? value : JSON.stringify(value));
             return;
         case 'TIMESTAMP':
+            appender.appendTimestamp(new duck.DuckDBTimestampValue(toTimestampMicros(value, col.name)));
+            return;
         case 'DATE':
+            appender.appendDate(new duck.DuckDBDateValue(toDateDays(value, col.name)));
+            return;
         case 'BLOB':
-            // Use varchar fallback; DuckDB casts on insert when the schema allows.
-            appender.appendVarchar(String(value));
+            appender.appendBlob(toUint8Array(value, col.name));
             return;
     }
 }
-function* skipFirst(iter, n) {
-    let skipped = 0;
-    for (const item of iter) {
-        if (skipped < n) {
-            skipped += 1;
-            continue;
-        }
-        yield item;
+/**
+ * Coerce a value to BigInt without precision loss. `BigInt(Number(value))`
+ * round-trips through JS Number and truncates outside the 53-bit safe range,
+ * silently corrupting BIGINT IDs returned as numeric strings.
+ *
+ * @internal Exported for unit testing.
+ */
+export function toBigInt(value) {
+    if (typeof value === 'bigint')
+        return value;
+    if (typeof value === 'string' && /^-?\d+$/.test(value))
+        return BigInt(value);
+    return BigInt(Math.trunc(Number(value)));
+}
+const MS_PER_DAY = 86_400_000;
+/**
+ * Coerce to DuckDB's TIMESTAMP unit (micros since 1970-01-01 UTC, as `bigint`).
+ * Accepts `Date`, `bigint` (already-micros), `number` (ms-since-epoch matching
+ * `Date.getTime()`), and ISO 8601 strings. Throws `validationError` otherwise.
+ *
+ * @internal Exported for unit testing.
+ */
+export function toTimestampMicros(value, columnName) {
+    if (value instanceof Date) {
+        const ms = value.getTime();
+        if (!Number.isFinite(ms)) {
+            throw validationError(`Invalid Date for TIMESTAMP column "${columnName}".`, {
+                reason: 'invalid_value_for_type',
+                column: columnName,
+                type: 'TIMESTAMP',
+            });
+        }
+        return BigInt(ms) * 1000n;
+    }
+    if (typeof value === 'bigint')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return BigInt(Math.trunc(value)) * 1000n;
+    }
+    if (typeof value === 'string') {
+        const ms = Date.parse(value);
+        if (Number.isFinite(ms))
+            return BigInt(ms) * 1000n;
+    }
+    throw validationError(`Cannot append ${describeValueType(value)} to TIMESTAMP column "${columnName}". Expected Date, ISO 8601 string, number (ms epoch), or bigint (micros epoch).`, { reason: 'invalid_value_for_type', column: columnName, type: 'TIMESTAMP' });
+}
+/**
+ * Coerce to DuckDB's DATE unit (days since 1970-01-01 UTC, as `number`).
+ * Accepts the same shapes as {@link toTimestampMicros}; throws otherwise.
+ *
+ * @internal Exported for unit testing.
+ */
+export function toDateDays(value, columnName) {
+    if (value instanceof Date) {
+        const ms = value.getTime();
+        if (!Number.isFinite(ms)) {
+            throw validationError(`Invalid Date for DATE column "${columnName}".`, {
+                reason: 'invalid_value_for_type',
+                column: columnName,
+                type: 'DATE',
+            });
+        }
+        return Math.floor(ms / MS_PER_DAY);
+    }
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return Math.floor(value / MS_PER_DAY);
+    }
+    if (typeof value === 'string') {
+        const ms = Date.parse(value);
+        if (Number.isFinite(ms))
+            return Math.floor(ms / MS_PER_DAY);
     }
+    throw validationError(`Cannot append ${describeValueType(value)} to DATE column "${columnName}". Expected Date, ISO 8601 date string, or number (ms epoch).`, { reason: 'invalid_value_for_type', column: columnName, type: 'DATE' });
+}
+/**
+ * Coerce to `Uint8Array` for BLOB appends. Accepts `Uint8Array` (Node's
+ * `Buffer` passes through as a subclass), `ArrayBuffer`, and any other
+ * `ArrayBufferView`. Throws `validationError` for non-binary inputs.
+ *
+ * @internal Exported for unit testing.
+ */
+export function toUint8Array(value, columnName) {
+    if (value instanceof Uint8Array)
+        return value;
+    if (value instanceof ArrayBuffer)
+        return new Uint8Array(value);
+    if (ArrayBuffer.isView(value)) {
+        const view = value;
+        return new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+    }
+    throw validationError(`Cannot append ${describeValueType(value)} to BLOB column "${columnName}". Expected Uint8Array, Buffer, or ArrayBuffer.`, { reason: 'invalid_value_for_type', column: columnName, type: 'BLOB' });
+}
+/** Tag describing a runtime value's type, for error messages. */
+function describeValueType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    if (value instanceof Date)
+        return 'Date';
+    if (value instanceof Uint8Array)
+        return 'Uint8Array';
+    if (value instanceof ArrayBuffer)
+        return 'ArrayBuffer';
+    return typeof value;
 }
 /** Escape a string literal for safe inclusion in `'...'` SQL contexts. */
 function escapeSqlString(value) {
@@ -576,22 +724,16 @@ async function ensureTableMissing(connection, tableName) {
 }
 /**
  * Map a DuckDB-thrown error to a framework error class.
- * @internal Exported for unit testing — not re-exported from the canvas barrel.
+ * @internal Exported for unit testing.
  */
 export function classifyDuckdbError(err) {
     if (err instanceof Error) {
         const msg = err.message;
-        // DuckDB tends to throw `Error` with a descriptive message; keep its
-        // identity as the cause and attach a structured message.
         if (/parser error|syntax/i.test(msg)) {
-            return validationError(`Canvas SQL rejected: ${msg}`, { reason: 'sql_parse_error' }, {
-                cause: err,
-            });
+            return validationError(`Canvas SQL rejected: ${msg}`, { reason: 'sql_parse_error' }, { cause: err });
         }
         if (/permission|read.?only/i.test(msg)) {
-            return validationError(`Canvas SQL rejected: ${msg}`, { reason: 'sql_read_only' }, {
-                cause: err,
-            });
+            return validationError(`Canvas SQL rejected: ${msg}`, { reason: 'sql_read_only' }, { cause: err });
         }
         return databaseError(msg, undefined, { cause: err });
     }