@cyanheads/mcp-ts-core 0.8.8 → 0.8.10

package/dist/services/canvas/core/sqlGate.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview Read-only SQL gate for the DataCanvas primitive. Engine-agnostic
+ * pure validators that the provider invokes after pulling DuckDB-specific
+ * metadata (statement extraction, prepared-statement type, EXPLAIN plan JSON).
+ *
+ * Three layers of enforcement, each authoritative on its own:
+ *
+ * 1. **Single-statement check.** The provider parses the input via DuckDB's
+ *    `extractStatements` and passes the count here. Anything other than 1 is
+ *    rejected — comment-hidden second statements, multi-statement smuggling,
+ *    and Unicode tricks all collapse here because DuckDB's parser is the
+ *    arbiter, not a regex.
+ * 2. **Statement-type check.** The provider prepares the single statement and
+ *    passes the resulting `statementType`. We require `SELECT`. Any DDL, DML,
+ *    or utility (PRAGMA/ATTACH/COPY/INSTALL/LOAD/SET/EXECUTE) fails to type as
+ *    SELECT and is rejected here.
+ * 3. **Plan-walk allowlist.** The provider runs `EXPLAIN (FORMAT JSON)` and
+ *    passes the plan JSON. We walk every node and reject if any operator
+ *    name is outside the curated allowlist — defense-in-depth against future
+ *    DuckDB additions that might smuggle work into a SELECT envelope.
+ *
+ * Rejection paths throw `ValidationError` with a structured `data.reason`
+ * suitable for surfacing to the agent.
+ *
+ * @module src/services/canvas/core/sqlGate
+ */
+/**
+ * DuckDB statement-type strings emitted by the Neo client. Only `SELECT` is
+ * accepted by the canvas. Other values (`INSERT`, `UPDATE`, `DELETE`,
+ * `CREATE`, `DROP`, `ALTER`, `COPY`, `PRAGMA`, `ATTACH`, `DETACH`, `LOAD`,
+ * `INSTALL`, `SET`, `RESET`, `EXECUTE`, `EXPLAIN`, `TRANSACTION`, `VACUUM`,
+ * `CHECKPOINT`, `CALL`, …) are rejected outright. This is a surface — not
+ * an enum we own — so the gate matches on the literal string emitted.
+ */
+export type DuckdbStatementType = string;
+/** Subset of statement types the gate permits. */
+export declare const ALLOWED_STATEMENT_TYPES: ReadonlySet<DuckdbStatementType>;
+/**
+ * Curated allowlist of operator names that can appear in an EXPLAIN plan.
+ * Sourced from DuckDB's logical/physical-plan node families (1.5.x). Not
+ * every member is reachable from a SELECT — but every member is read-only.
+ *
+ * Pinned by `tests/canvas/sqlGate.fixtures.test.ts` against live DuckDB
+ * EXPLAIN output so version bumps that add operators are caught in CI rather
+ * than silently widening the gate.
+ *
+ * Operators **not** in this list cause rejection. Notable exclusions:
+ *
+ * - `READ_CSV`, `READ_PARQUET`, `READ_JSON` — bypass canvas, read external files.
+ * - `INSERT`, `UPDATE`, `DELETE`, `MERGE`, `CREATE_*`, `DROP_*`, `ALTER_*` — writes.
+ * - `COPY_TO_FILE`, `BATCH_COPY_TO_FILE` — exports a SELECT to a file.
+ * - `ATTACH`, `DETACH`, `LOAD`, `INSTALL`, `PRAGMA`, `SET`, `RESET` — utility.
+ */
+export declare const ALLOWED_PLAN_OPERATORS: ReadonlySet<string>;
+/**
+ * Public entry point — validates the trio of `(statementCount, statementType,
+ * planJson)`. Throws on the first violation, leaving the provider to pass
+ * results back to the caller untouched on success.
+ */
+export declare function assertReadOnlyQuery(input: {
+    /** Number of statements DuckDB extracted from the user-supplied SQL. */
+    statementCount: number;
+    /** DuckDB statement type for the (single) prepared statement. */
+    statementType: DuckdbStatementType;
+    /** Parsed `EXPLAIN (FORMAT JSON)` payload. */
+    planJson: unknown;
+}): void;
+/**
+ * Pre-EXPLAIN gate: validate statement count and type. Run before the EXPLAIN
+ * call so non-SELECT statements (which DuckDB's EXPLAIN can't always wrap —
+ * e.g. ATTACH/PRAGMA/COPY/INSTALL) fail with a structured ValidationError
+ * here rather than a confusing parser error from EXPLAIN itself.
+ */
+export declare function assertSelectOnly(input: {
+    statementCount: number;
+    statementType: DuckdbStatementType;
+}): void;
+/**
+ * Post-EXPLAIN gate: walk the plan tree and reject any operator outside the
+ * curated allowlist. Defense-in-depth against future DuckDB additions that
+ * smuggle work into a SELECT envelope.
+ */
+export declare function assertPlanReadOnly(planJson: unknown): void;
+/**
+ * Walks the EXPLAIN plan and returns the set of operator names not in
+ * `ALLOWED_PLAN_OPERATORS`. Exported for fixture-driven tests that want
+ * to inspect the gate's view of a plan without throwing.
+ *
+ * Tolerant of structural variation — DuckDB emits operator identity under
+ * either `name` (logical plan) or `operator_type` (physical/profile plan)
+ * depending on the EXPLAIN flavor. We honor both. Children traversal
+ * supports `children`, `child`, and `inputs` arrays.
+ */
+export declare function collectDisallowedOperators(planJson: unknown): Set<string>;
+/**
+ * Validate an identifier for use as a canvas-local table or column name.
+ * Throws `ValidationError` on rejection.
+ */
+export declare function assertValidIdentifier(value: string, kind: 'table' | 'column'): void;
+/**
+ * Wrap an identifier in double quotes for safe inclusion in SQL. Internal
+ * double quotes are doubled per the SQL standard. Callers should still
+ * validate via {@link assertValidIdentifier} before quoting — this helper
+ * only escapes; it does not validate shape.
+ */
+export declare function quoteIdentifier(value: string): string;
+//# sourceMappingURL=sqlGate.d.ts.map

package/dist/services/canvas/core/sqlGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlGate.d.ts","sourceRoot":"","sources":["../../../../src/services/canvas/core/sqlGate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEzC,kDAAkD;AAClD,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,mBAAmB,CAAuB,CAAC;AAE7F;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAwDrD,CAAC;AAEH;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IACzC,wEAAwE;IACxE,cAAc,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,aAAa,EAAE,mBAAmB,CAAC;IACnC,8CAA8C;IAC9C,QAAQ,EAAE,OAAO,CAAC;CACnB,GAAG,IAAI,CAGP;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IACtC,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,mBAAmB,CAAC;CACpC,GAAG,IAAI,CAaP;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAW1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAIzE;AAsFD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAmBnF;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/dist/services/canvas/core/sqlGate.js

@@ -0,0 +1,267 @@
+/**
+ * @fileoverview Read-only SQL gate for the DataCanvas primitive. Engine-agnostic
+ * pure validators that the provider invokes after pulling DuckDB-specific
+ * metadata (statement extraction, prepared-statement type, EXPLAIN plan JSON).
+ *
+ * Three layers of enforcement, each authoritative on its own:
+ *
+ * 1. **Single-statement check.** The provider parses the input via DuckDB's
+ *    `extractStatements` and passes the count here. Anything other than 1 is
+ *    rejected — comment-hidden second statements, multi-statement smuggling,
+ *    and Unicode tricks all collapse here because DuckDB's parser is the
+ *    arbiter, not a regex.
+ * 2. **Statement-type check.** The provider prepares the single statement and
+ *    passes the resulting `statementType`. We require `SELECT`. Any DDL, DML,
+ *    or utility (PRAGMA/ATTACH/COPY/INSTALL/LOAD/SET/EXECUTE) fails to type as
+ *    SELECT and is rejected here.
+ * 3. **Plan-walk allowlist.** The provider runs `EXPLAIN (FORMAT JSON)` and
+ *    passes the plan JSON. We walk every node and reject if any operator
+ *    name is outside the curated allowlist — defense-in-depth against future
+ *    DuckDB additions that might smuggle work into a SELECT envelope.
+ *
+ * Rejection paths throw `ValidationError` with a structured `data.reason`
+ * suitable for surfacing to the agent.
+ *
+ * @module src/services/canvas/core/sqlGate
+ */
+import { validationError } from '../../../types-global/errors.js';
+/** Subset of statement types the gate permits. */
+export const ALLOWED_STATEMENT_TYPES = new Set(['SELECT']);
+/**
+ * Curated allowlist of operator names that can appear in an EXPLAIN plan.
+ * Sourced from DuckDB's logical/physical-plan node families (1.5.x). Not
+ * every member is reachable from a SELECT — but every member is read-only.
+ *
+ * Pinned by `tests/canvas/sqlGate.fixtures.test.ts` against live DuckDB
+ * EXPLAIN output so version bumps that add operators are caught in CI rather
+ * than silently widening the gate.
+ *
+ * Operators **not** in this list cause rejection. Notable exclusions:
+ *
+ * - `READ_CSV`, `READ_PARQUET`, `READ_JSON` — bypass canvas, read external files.
+ * - `INSERT`, `UPDATE`, `DELETE`, `MERGE`, `CREATE_*`, `DROP_*`, `ALTER_*` — writes.
+ * - `COPY_TO_FILE`, `BATCH_COPY_TO_FILE` — exports a SELECT to a file.
+ * - `ATTACH`, `DETACH`, `LOAD`, `INSTALL`, `PRAGMA`, `SET`, `RESET` — utility.
+ */
+export const ALLOWED_PLAN_OPERATORS = new Set([
+    // Scans (registered tables only — file scans like READ_CSV are excluded)
+    'SEQ_SCAN',
+    'COLUMN_DATA_SCAN',
+    'CHUNK_SCAN',
+    'EXPRESSION_SCAN',
+    'DUMMY_SCAN',
+    'EMPTY_RESULT',
+    'IN_MEMORY_TABLE_SCAN',
+    // Projection / filter
+    'PROJECTION',
+    'FILTER',
+    // Joins
+    'HASH_JOIN',
+    'NESTED_LOOP_JOIN',
+    'BLOCKWISE_NL_JOIN',
+    'IE_JOIN',
+    'PIECEWISE_MERGE_JOIN',
+    'CROSS_PRODUCT',
+    'POSITIONAL_JOIN',
+    'ASOF_JOIN',
+    'DELIM_JOIN',
+    // Aggregates
+    'HASH_GROUP_BY',
+    'PERFECT_HASH_GROUP_BY',
+    'UNGROUPED_AGGREGATE',
+    'SIMPLE_AGGREGATE',
+    'PARTITIONED_AGGREGATE',
+    // Distinct / set ops
+    'HASH_DISTINCT',
+    'DISTINCT',
+    'UNION',
+    // Sorting / limits
+    'ORDER_BY',
+    'TOP_N',
+    'LIMIT',
+    'LIMIT_PERCENT',
+    'STREAMING_LIMIT',
+    // Window
+    'WINDOW',
+    // Nested
+    'UNNEST',
+    // CTEs
+    'CTE',
+    'CTE_REF',
+    'RECURSIVE_CTE',
+    'MATERIALIZED_CTE',
+    // Sampling
+    'RESERVOIR_SAMPLE',
+    'SAMPLE',
+    'STREAMING_SAMPLE',
+    // Result framing
+    'RESULT_COLLECTOR',
+    'EXPLAIN',
+    // Pivot/unpivot collapsed planner forms
+    'PIVOT',
+]);
+/**
+ * Public entry point — validates the trio of `(statementCount, statementType,
+ * planJson)`. Throws on the first violation, leaving the provider to pass
+ * results back to the caller untouched on success.
+ */
+export function assertReadOnlyQuery(input) {
+    assertSelectOnly(input);
+    assertPlanReadOnly(input.planJson);
+}
+/**
+ * Pre-EXPLAIN gate: validate statement count and type. Run before the EXPLAIN
+ * call so non-SELECT statements (which DuckDB's EXPLAIN can't always wrap —
+ * e.g. ATTACH/PRAGMA/COPY/INSTALL) fail with a structured ValidationError
+ * here rather than a confusing parser error from EXPLAIN itself.
+ */
+export function assertSelectOnly(input) {
+    if (input.statementCount !== 1) {
+        throw validationError('Canvas query must contain exactly one SQL statement.', {
+            reason: 'multi_statement',
+            statementCount: input.statementCount,
+        });
+    }
+    if (!ALLOWED_STATEMENT_TYPES.has(input.statementType)) {
+        throw validationError(`Canvas query must be SELECT; got ${input.statementType}. Mutations must use registerTable, drop, or clear.`, { reason: 'non_select_statement', statementType: input.statementType });
+    }
+}
+/**
+ * Post-EXPLAIN gate: walk the plan tree and reject any operator outside the
+ * curated allowlist. Defense-in-depth against future DuckDB additions that
+ * smuggle work into a SELECT envelope.
+ */
+export function assertPlanReadOnly(planJson) {
+    const offending = collectDisallowedOperators(planJson);
+    if (offending.size > 0) {
+        throw validationError(`Canvas query contains disallowed operators: ${[...offending].sort().join(', ')}.`, {
+            reason: 'plan_operator_not_allowed',
+            operators: [...offending].sort(),
+        });
+    }
+}
+/**
+ * Walks the EXPLAIN plan and returns the set of operator names not in
+ * `ALLOWED_PLAN_OPERATORS`. Exported for fixture-driven tests that want
+ * to inspect the gate's view of a plan without throwing.
+ *
+ * Tolerant of structural variation — DuckDB emits operator identity under
+ * either `name` (logical plan) or `operator_type` (physical/profile plan)
+ * depending on the EXPLAIN flavor. We honor both. Children traversal
+ * supports `children`, `child`, and `inputs` arrays.
+ */
+export function collectDisallowedOperators(planJson) {
+    const offending = new Set();
+    walk(planJson, offending);
+    return offending;
+}
+function walk(node, offending) {
+    if (node === null || typeof node !== 'object')
+        return;
+    if (Array.isArray(node)) {
+        for (const child of node)
+            walk(child, offending);
+        return;
+    }
+    const obj = node;
+    const operator = readOperatorName(obj);
+    if (operator !== undefined && !ALLOWED_PLAN_OPERATORS.has(operator)) {
+        offending.add(operator);
+    }
+    // Traverse known child slots; ignore string/number leaves.
+    for (const key of ['children', 'child', 'inputs', 'plan', 'root']) {
+        if (key in obj)
+            walk(obj[key], offending);
+    }
+}
+function readOperatorName(obj) {
+    const candidates = ['name', 'operator_type', 'operator', 'type'];
+    for (const key of candidates) {
+        const value = obj[key];
+        if (typeof value === 'string' && value !== '') {
+            return value.toUpperCase();
+        }
+    }
+    return;
+}
+// ---------------------------------------------------------------------------
+// Identifier validation and quoting
+// ---------------------------------------------------------------------------
+/**
+ * Allowed shape for canvas-local table and column names. Matches the
+ * conservative SQL identifier convention: starts with letter/underscore,
+ * followed by letters/digits/underscores, max 63 chars (PostgreSQL/DuckDB cap).
+ */
+const IDENTIFIER_REGEX = /^[A-Za-z_][A-Za-z0-9_]{0,62}$/;
+/**
+ * DuckDB reserved words that must not be used as bare identifiers. Not
+ * exhaustive — this is a courtesy guard so misnamed tables fail at register
+ * time rather than confusing-error time. The `IDENTIFIER_REGEX` is the
+ * authoritative shape gate.
+ */
+const RESERVED_IDENTIFIERS = new Set([
+    'select',
+    'from',
+    'where',
+    'order',
+    'group',
+    'having',
+    'limit',
+    'offset',
+    'union',
+    'intersect',
+    'except',
+    'all',
+    'distinct',
+    'as',
+    'and',
+    'or',
+    'not',
+    'null',
+    'true',
+    'false',
+    'case',
+    'when',
+    'then',
+    'else',
+    'end',
+    'join',
+    'inner',
+    'outer',
+    'left',
+    'right',
+    'full',
+    'cross',
+    'on',
+    'using',
+    'with',
+    'recursive',
+]);
+/**
+ * Validate an identifier for use as a canvas-local table or column name.
+ * Throws `ValidationError` on rejection.
+ */
+export function assertValidIdentifier(value, kind) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw validationError(`Canvas ${kind} name must be a non-empty string.`, {
+            reason: 'identifier_empty',
+            kind,
+        });
+    }
+    if (!IDENTIFIER_REGEX.test(value)) {
+        throw validationError(`Canvas ${kind} name "${value}" is invalid. Use letters, digits, and underscores; must start with a letter or underscore; max 63 chars.`, { reason: 'identifier_shape', kind, value });
+    }
+    if (RESERVED_IDENTIFIERS.has(value.toLowerCase())) {
+        throw validationError(`Canvas ${kind} name "${value}" is a reserved SQL keyword. Choose another name.`, { reason: 'identifier_reserved', kind, value });
+    }
+}
+/**
+ * Wrap an identifier in double quotes for safe inclusion in SQL. Internal
+ * double quotes are doubled per the SQL standard. Callers should still
+ * validate via {@link assertValidIdentifier} before quoting — this helper
+ * only escapes; it does not validate shape.
+ */
+export function quoteIdentifier(value) {
+    return `"${value.replace(/"/g, '""')}"`;
+}
+//# sourceMappingURL=sqlGate.js.map

package/dist/services/canvas/core/sqlGate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlGate.js","sourceRoot":"","sources":["../../../../src/services/canvas/core/sqlGate.ts"],"names":[],"mappings":"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"}

package/dist/services/canvas/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Public barrel for the DataCanvas primitive. Servers import
+ * from `@cyanheads/mcp-ts-core/canvas` to interact with `core.canvas` —
+ * either via tool handlers (acquire → register → query → export) or directly
+ * for advanced lifecycle work.
+ *
+ * The DuckDB provider is lazy-loaded; pulling this barrel does not pull in
+ * `@duckdb/node-api` until {@link DataCanvas.acquire} runs against an active
+ * canvas configuration.
+ *
+ * @module src/services/canvas/index
+ */
+export { CanvasInstance } from './core/CanvasInstance.js';
+export { type AcquireResult, CanvasRegistry, type CanvasRegistryOptions, DEFAULT_CANVAS_REGISTRY_OPTIONS, } from './core/CanvasRegistry.js';
+export { createCanvasService } from './core/canvasFactory.js';
+export { DataCanvas } from './core/DataCanvas.js';
+export type { IDataCanvasProvider } from './core/IDataCanvasProvider.js';
+export { ALLOWED_PLAN_OPERATORS, ALLOWED_STATEMENT_TYPES, assertReadOnlyQuery, assertValidIdentifier, collectDisallowedOperators, type DuckdbStatementType, quoteIdentifier, } from './core/sqlGate.js';
+export { DuckdbProvider, type DuckdbProviderOptions, } from './providers/duckdb/DuckdbProvider.js';
+export type { AcquireOptions, ColumnSchema, ColumnType, DescribeOptions, ExportFormat, ExportOptions, ExportResult, ExportTarget, QueryOptions, QueryResult, RegisterRows, RegisterTableOptions, RegisterTableResult, TableInfo, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/services/canvas/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/canvas/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EACL,KAAK,aAAa,EAClB,cAAc,EACd,KAAK,qBAAqB,EAC1B,+BAA+B,GAChC,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,YAAY,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,mBAAmB,EACnB,qBAAqB,EACrB,0BAA0B,EAC1B,KAAK,mBAAmB,EACxB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,GAC3B,MAAM,sCAAsC,CAAC;AAC9C,YAAY,EACV,cAAc,EACd,YAAY,EACZ,UAAU,EACV,eAAe,EACf,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,oBAAoB,EACpB,mBAAmB,EACnB,SAAS,GACV,MAAM,YAAY,CAAC"}

package/dist/services/canvas/index.js

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Public barrel for the DataCanvas primitive. Servers import
+ * from `@cyanheads/mcp-ts-core/canvas` to interact with `core.canvas` —
+ * either via tool handlers (acquire → register → query → export) or directly
+ * for advanced lifecycle work.
+ *
+ * The DuckDB provider is lazy-loaded; pulling this barrel does not pull in
+ * `@duckdb/node-api` until {@link DataCanvas.acquire} runs against an active
+ * canvas configuration.
+ *
+ * @module src/services/canvas/index
+ */
+export { CanvasInstance } from './core/CanvasInstance.js';
+export { CanvasRegistry, DEFAULT_CANVAS_REGISTRY_OPTIONS, } from './core/CanvasRegistry.js';
+export { createCanvasService } from './core/canvasFactory.js';
+export { DataCanvas } from './core/DataCanvas.js';
+export { ALLOWED_PLAN_OPERATORS, ALLOWED_STATEMENT_TYPES, assertReadOnlyQuery, assertValidIdentifier, collectDisallowedOperators, quoteIdentifier, } from './core/sqlGate.js';
+export { DuckdbProvider, } from './providers/duckdb/DuckdbProvider.js';
+//# sourceMappingURL=index.js.map

package/dist/services/canvas/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/services/canvas/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAEL,cAAc,EAEd,+BAA+B,GAChC,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAElD,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,mBAAmB,EACnB,qBAAqB,EACrB,0BAA0B,EAE1B,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,cAAc,GAEf,MAAM,sCAAsC,CAAC"}

package/dist/services/canvas/providers/duckdb/DuckdbProvider.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @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.
+ *
+ * @module src/services/canvas/providers/duckdb/DuckdbProvider
+ */
+import { type RequestContext } from '../../../../utils/internal/requestContext.js';
+import type { IDataCanvasProvider } from '../../core/IDataCanvasProvider.js';
+import type { DescribeOptions, ExportOptions, ExportResult, ExportTarget, QueryOptions, QueryResult, RegisterRows, RegisterTableOptions, RegisterTableResult, TableInfo } from '../../types.js';
+/** Configuration for {@link DuckdbProvider}. Mirrors the AppConfig.canvas block. */
+export interface DuckdbProviderOptions {
+    /** Default row cap for `query()` results. */
+    defaultRowLimit: number;
+    /** Sandbox root for path-targeted exports. */
+    exportRootPath: string;
+    /** Per-canvas `memory_limit` PRAGMA value, in MB. */
+    memoryLimitMb: number;
+    /** Number of rows to sniff for schema inference. */
+    schemaSniffRows: number;
+}
+/** DuckDB SELECT statement-type id (matches `StatementType.SELECT === 1`). */
+declare const STATEMENT_TYPE_SELECT_ID = 1;
+export declare class DuckdbProvider implements IDataCanvasProvider {
+    private readonly options;
+    readonly name = "duckdb";
+    private duck;
+    private readonly canvases;
+    constructor(options: DuckdbProviderOptions);
+    initCanvas(canvasId: string, _context: RequestContext): Promise<void>;
+    destroyCanvas(canvasId: string, _context: RequestContext): Promise<void>;
+    healthCheck(): Promise<boolean>;
+    shutdown(): Promise<void>;
+    registerTable(canvasId: string, name: string, rows: RegisterRows, _context: RequestContext, options?: RegisterTableOptions): Promise<RegisterTableResult>;
+    query(canvasId: string, sql: string, _context: RequestContext, options?: QueryOptions): Promise<QueryResult>;
+    export(canvasId: string, tableName: string, target: ExportTarget, _context: RequestContext, options?: ExportOptions): Promise<ExportResult>;
+    describe(canvasId: string, _context: RequestContext, options?: DescribeOptions): Promise<TableInfo[]>;
+    drop(canvasId: string, name: string, _context: RequestContext): Promise<boolean>;
+    clear(canvasId: string, _context: RequestContext): Promise<number>;
+    private requireCanvas;
+    private getModule;
+    private runExplain;
+}
+/** Re-export for tests and consumer-side parsing. */
+export { STATEMENT_TYPE_SELECT_ID };
+/**
+ * Map a DuckDB-thrown error to a framework error class.
+ * @internal Exported for unit testing — not re-exported from the canvas barrel.
+ */
+export declare function classifyDuckdbError(err: unknown): Error;
+//# sourceMappingURL=DuckdbProvider.d.ts.map

package/dist/services/canvas/providers/duckdb/DuckdbProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DuckdbProvider.d.ts","sourceRoot":"","sources":["../../../../../src/services/canvas/providers/duckdb/DuckdbProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAAE,KAAK,cAAc,EAAyB,MAAM,oCAAoC,CAAC;AAEhG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAO7E,OAAO,KAAK,EAGV,eAAe,EACf,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,oBAAoB,EACpB,mBAAmB,EACnB,SAAS,EACV,MAAM,gBAAgB,CAAC;AAqBxB,oFAAoF;AACpF,MAAM,WAAW,qBAAqB;IACpC,6CAA6C;IAC7C,eAAe,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,cAAc,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,aAAa,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,8EAA8E;AAC9E,QAAA,MAAM,wBAAwB,IAAI,CAAC;AAQnC,qBAAa,cAAe,YAAW,mBAAmB;IAM5C,OAAO,CAAC,QAAQ,CAAC,OAAO;IALpC,QAAQ,CAAC,IAAI,YAAY;IAEzB,OAAO,CAAC,IAAI,CAA2B;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;gBAE/B,OAAO,EAAE,qBAAqB;IAMrD,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBrE,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BxE,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAc/B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAczB,aAAa,CACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,YAAY,EAClB,QAAQ,EAAE,cAAc,EACxB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC;IAoFzB,KAAK,CACT,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,cAAc,EACxB,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,WAAW,CAAC;IAsGjB,MAAM,CACV,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,cAAc,EACxB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,CAAC;IA8DlB,QAAQ,CACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,cAAc,EACxB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,SAAS,EAAE,CAAC;IA2CjB,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAWhF,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAgBxE,OAAO,CAAC,aAAa;YAQP,SAAS;YAKT,UAAU;CAezB;AAsHD,qDAAqD;AACrD,OAAO,EAAE,wBAAwB,EAAE,CAAC;AA4EpC;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,KAAK,CA0BvD"}