@cyanheads/mcp-ts-core 0.8.8 → 0.8.10

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

@@ -0,0 +1,250 @@
+/**
+ * @fileoverview Canvas lifecycle registry. Keys canvases by (tenantId, canvasId),
+ * generates crypto-secure 10-char URL-safe IDs, enforces a sliding 24h TTL with
+ * a 7-day absolute cap, and runs a periodic sweeper that destroys expired
+ * canvases via the underlying provider. Also enforces the per-tenant active
+ * canvas cap (default 100).
+ *
+ * Public access is gated by {@link DataCanvas} — callers never see this class
+ * directly. Tests construct it with a fake provider and a mock `Date.now` to
+ * exercise expiry/sweep logic.
+ * @module src/services/canvas/core/CanvasRegistry
+ */
+import { conflict, notFound, rateLimited } from '../../../types-global/errors.js';
+import { logger } from '../../../utils/internal/logger.js';
+import { requestContextService } from '../../../utils/internal/requestContext.js';
+import { IdGenerator } from '../../../utils/security/idGenerator.js';
+/**
+ * Canvas ID character set — URL-safe alphabet matching `nanoid`'s default
+ * (A-Z, a-z, 0-9, `-`, `_`). 10 chars × 64 alphabet ≈ 1.15 × 10^18 keyspace.
+ */
+const CANVAS_ID_CHARSET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+const CANVAS_ID_LENGTH = 10;
+const CANVAS_ID_REGEX = /^[A-Za-z0-9_-]{10}$/;
+/**
+ * Default lifecycle constants. Mirrored in the config schema; exported so
+ * tests and downstream tooling can reference the same numbers.
+ */
+export const DEFAULT_CANVAS_REGISTRY_OPTIONS = {
+    ttlMs: 24 * 60 * 60 * 1000,
+    absoluteCapMs: 7 * 24 * 60 * 60 * 1000,
+    maxCanvasesPerTenant: 100,
+    sweeperIntervalMs: 60 * 1000,
+};
+/**
+ * Tracks the active canvases for a single process. Not multi-process safe —
+ * tokens issued by one process are not portable to another (matches v1 scope
+ * in the issue).
+ */
+export class CanvasRegistry {
+    provider;
+    options;
+    clock;
+    idGenerator = new IdGenerator();
+    canvases = new Map();
+    /** Per-tenant index for cap enforcement and listing. */
+    byTenant = new Map();
+    sweeperTimer;
+    isShuttingDown = false;
+    constructor(provider, options = DEFAULT_CANVAS_REGISTRY_OPTIONS, 
+    /** Injected for tests. Defaults to `Date.now`. */
+    clock = Date.now) {
+        this.provider = provider;
+        this.options = options;
+        this.clock = clock;
+        if (options.sweeperIntervalMs > 0) {
+            this.sweeperTimer = setInterval(() => void this.sweep(), options.sweeperIntervalMs);
+            // Don't keep the event loop alive solely for the sweeper.
+            this.sweeperTimer.unref?.();
+        }
+    }
+    /**
+     * Resolve an existing canvas or create a new one when `maybeId` is omitted
+     * or the supplied id is unknown for the caller's tenant.
+     *
+     * - Omitted id → create fresh, return `isNew: true`.
+     * - Unknown id → throw `NotFound` (caller should retry without an id).
+     * - Known id under wrong tenant → throw `NotFound` (uniform with unknown
+     *   to avoid leaking existence across tenants).
+     * - Known + own tenant → touch (extend TTL), return `isNew: false`.
+     */
+    async acquire(maybeId, tenantId, context) {
+        if (this.isShuttingDown) {
+            throw notFound('Canvas registry is shutting down.', { tenantId });
+        }
+        if (maybeId !== undefined) {
+            const record = this.lookup(maybeId, tenantId);
+            if (!record) {
+                throw notFound('Canvas not found or expired. Omit canvas_id to start a new canvas.', {
+                    canvasId: maybeId,
+                });
+            }
+            this.touch(record);
+            return {
+                canvasId: record.canvasId,
+                tenantId: record.tenantId,
+                isNew: false,
+                expiresAt: new Date(record.expiresAt).toISOString(),
+            };
+        }
+        this.enforceTenantCap(tenantId);
+        const canvasId = this.mintId();
+        const now = this.clock();
+        const record = {
+            canvasId,
+            tenantId,
+            createdAt: now,
+            lastAccessedAt: now,
+            expiresAt: now + this.options.ttlMs,
+        };
+        this.canvases.set(canvasId, record);
+        this.indexByTenant(tenantId, canvasId);
+        await this.provider.initCanvas(canvasId, context);
+        logger.debug('Canvas created.', {
+            ...context,
+            canvasId,
+            tenantId,
+            provider: this.provider.name,
+        });
+        return {
+            canvasId,
+            tenantId,
+            isNew: true,
+            expiresAt: new Date(record.expiresAt).toISOString(),
+        };
+    }
+    /**
+     * Validate that `canvasId` belongs to `tenantId` and is not expired, then
+     * extend its TTL and return the resolved expiry. Used by {@link CanvasInstance}
+     * before every op so individual operations slide the window.
+     */
+    touchOrThrow(canvasId, tenantId) {
+        const record = this.lookup(canvasId, tenantId);
+        if (!record) {
+            throw notFound('Canvas not found or expired.', { canvasId });
+        }
+        this.touch(record);
+        return new Date(record.expiresAt).toISOString();
+    }
+    /**
+     * Drop a canvas explicitly (e.g. tenant-initiated cleanup). Returns true
+     * when the canvas existed and was destroyed.
+     */
+    async drop(canvasId, tenantId, context) {
+        const record = this.lookup(canvasId, tenantId);
+        if (!record)
+            return false;
+        await this.destroy(record, context);
+        return true;
+    }
+    /** Active canvas count for a tenant (used by tests and metrics surfaces). */
+    countForTenant(tenantId) {
+        return this.byTenant.get(tenantId)?.size ?? 0;
+    }
+    /** Total active canvases (used by tests and metrics surfaces). */
+    totalActive() {
+        return this.canvases.size;
+    }
+    /** Stop the sweeper and tear down every active canvas. Idempotent. */
+    async shutdown(context) {
+        if (this.isShuttingDown)
+            return;
+        this.isShuttingDown = true;
+        if (this.sweeperTimer) {
+            clearInterval(this.sweeperTimer);
+            this.sweeperTimer = undefined;
+        }
+        const records = Array.from(this.canvases.values());
+        await Promise.allSettled(records.map((r) => this.destroy(r, context)));
+        await this.provider.shutdown();
+    }
+    /** @internal Test/diagnostic hook — runs one sweep pass synchronously. */
+    async sweep() {
+        if (this.isShuttingDown)
+            return;
+        const now = this.clock();
+        const expired = [];
+        for (const record of this.canvases.values()) {
+            if (now >= record.expiresAt || now - record.createdAt >= this.options.absoluteCapMs) {
+                expired.push(record);
+            }
+        }
+        if (expired.length === 0)
+            return;
+        const sweepContext = requestContextService.createRequestContext({
+            operation: 'CanvasRegistry.sweep',
+        });
+        await Promise.allSettled(expired.map((r) => this.destroy(r, sweepContext)));
+        logger.debug('Canvas sweeper destroyed expired canvases.', {
+            ...sweepContext,
+            destroyedCount: expired.length,
+        });
+    }
+    // ---------------------------------------------------------------------
+    // Internals
+    // ---------------------------------------------------------------------
+    lookup(canvasId, tenantId) {
+        if (!CANVAS_ID_REGEX.test(canvasId))
+            return;
+        const record = this.canvases.get(canvasId);
+        if (!record)
+            return;
+        if (record.tenantId !== tenantId)
+            return;
+        const now = this.clock();
+        if (now >= record.expiresAt || now - record.createdAt >= this.options.absoluteCapMs) {
+            return;
+        }
+        return record;
+    }
+    touch(record) {
+        const now = this.clock();
+        record.lastAccessedAt = now;
+        const slidingExpiry = now + this.options.ttlMs;
+        const absoluteExpiry = record.createdAt + this.options.absoluteCapMs;
+        record.expiresAt = Math.min(slidingExpiry, absoluteExpiry);
+    }
+    enforceTenantCap(tenantId) {
+        const count = this.byTenant.get(tenantId)?.size ?? 0;
+        if (count >= this.options.maxCanvasesPerTenant) {
+            throw rateLimited(`Tenant has reached the active canvas cap (${this.options.maxCanvasesPerTenant}). Drop unused canvases or wait for the sliding TTL to expire them.`, { tenantId, activeCount: count, cap: this.options.maxCanvasesPerTenant });
+        }
+    }
+    mintId() {
+        // Loop-mint to avoid the (vanishingly rare) collision case.
+        for (let i = 0; i < 5; i += 1) {
+            const id = this.idGenerator.generateRandomString(CANVAS_ID_LENGTH, CANVAS_ID_CHARSET);
+            if (!this.canvases.has(id))
+                return id;
+        }
+        throw conflict('Failed to generate a unique canvas ID after 5 attempts.');
+    }
+    indexByTenant(tenantId, canvasId) {
+        let set = this.byTenant.get(tenantId);
+        if (!set) {
+            set = new Set();
+            this.byTenant.set(tenantId, set);
+        }
+        set.add(canvasId);
+    }
+    async destroy(record, context) {
+        this.canvases.delete(record.canvasId);
+        const set = this.byTenant.get(record.tenantId);
+        if (set) {
+            set.delete(record.canvasId);
+            if (set.size === 0)
+                this.byTenant.delete(record.tenantId);
+        }
+        try {
+            await this.provider.destroyCanvas(record.canvasId, context);
+        }
+        catch (err) {
+            logger.warning('Provider destroyCanvas failed during sweep.', {
+                ...context,
+                canvasId: record.canvasId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+}
+//# sourceMappingURL=CanvasRegistry.js.map

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

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

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

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview User-facing DataCanvas service. Wraps the provider and registry
+ * with debug logging and tenant-id resolution; the registry handles TTL,
+ * caps, and provider-keying. Mirrors the StorageService surface pattern but
+ * stays OTel-free in v1 (per issue #97 scope).
+ * @module src/services/canvas/core/DataCanvas
+ */
+import type { RequestContext } from '../../../utils/internal/requestContext.js';
+import type { AcquireOptions } from '../types.js';
+import { CanvasInstance } from './CanvasInstance.js';
+import type { CanvasRegistry } from './CanvasRegistry.js';
+import type { IDataCanvasProvider } from './IDataCanvasProvider.js';
+/**
+ * Service entry point for the DataCanvas primitive. Returned from
+ * `core.canvas` on `CoreServices` when a canvas provider is configured.
+ *
+ * @example
+ * ```ts
+ * const canvas = await core.canvas!.acquire(input.canvas_id, ctx);
+ * await canvas.registerTable('germplasm', rows);
+ * const result = await canvas.query('SELECT name FROM germplasm LIMIT 10');
+ * return { canvas_id: canvas.canvasId, expires_at: canvas.expiresAt, ... };
+ * ```
+ */
+export declare class DataCanvas {
+    private readonly provider;
+    private readonly registry;
+    constructor(provider: IDataCanvasProvider, registry: CanvasRegistry);
+    /**
+     * Resolve an existing canvas or create a new one. The returned
+     * {@link CanvasInstance} captures `(canvasId, tenantId)` so subsequent
+     * operations don't need to repeat them.
+     */
+    acquire(maybeId: string | undefined, context: RequestContext, _options?: AcquireOptions): Promise<CanvasInstance>;
+    /**
+     * Drop a canvas explicitly. Returns true when the canvas existed and was
+     * destroyed.
+     */
+    drop(canvasId: string, context: RequestContext): Promise<boolean>;
+    /** Active canvas count for the calling tenant. */
+    countForTenant(context: RequestContext): number;
+    /** Liveness check on the underlying provider. */
+    healthCheck(): Promise<boolean>;
+    /** Tear down the registry and provider. Called from `ServerHandle.shutdown()`. */
+    shutdown(context: RequestContext): Promise<void>;
+    /** @internal Surface the underlying provider for advanced use cases. */
+    getProvider(): IDataCanvasProvider;
+}
+//# sourceMappingURL=DataCanvas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DataCanvas.d.ts","sourceRoot":"","sources":["../../../../src/services/canvas/core/DataCanvas.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAmBpE;;;;;;;;;;;GAWG;AACH,qBAAa,UAAU;IAEnB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADR,QAAQ,EAAE,mBAAmB,EAC7B,QAAQ,EAAE,cAAc;IAK3C;;;;OAIG;IACG,OAAO,CACX,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,EAAE,cAAc,EACvB,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,cAAc,CAAC;IAoB1B;;;OAGG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAKvE,kDAAkD;IAClD,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM;IAK/C,iDAAiD;IACjD,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAI/B,kFAAkF;IAC5E,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAItD,wEAAwE;IACxE,WAAW,IAAI,mBAAmB;CAGnC"}

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

@@ -0,0 +1,85 @@
+/**
+ * @fileoverview User-facing DataCanvas service. Wraps the provider and registry
+ * with debug logging and tenant-id resolution; the registry handles TTL,
+ * caps, and provider-keying. Mirrors the StorageService surface pattern but
+ * stays OTel-free in v1 (per issue #97 scope).
+ * @module src/services/canvas/core/DataCanvas
+ */
+import { JsonRpcErrorCode, McpError } from '../../../types-global/errors.js';
+import { logger } from '../../../utils/internal/logger.js';
+import { CanvasInstance } from './CanvasInstance.js';
+/**
+ * Resolve the effective tenant ID from the context, throwing when absent.
+ * Mirrors `requireTenantId` in StorageService — canvas operations are
+ * tenant-scoped by construction.
+ */
+function requireTenantId(context) {
+    const tenantId = context.tenantId;
+    if (tenantId === undefined || tenantId === null || tenantId === '') {
+        throw new McpError(JsonRpcErrorCode.InternalError, 'Tenant ID is required for canvas operations but was not found in the request context.', { operation: context.operation || 'DataCanvas.acquire', requestId: context.requestId });
+    }
+    return tenantId;
+}
+/**
+ * Service entry point for the DataCanvas primitive. Returned from
+ * `core.canvas` on `CoreServices` when a canvas provider is configured.
+ *
+ * @example
+ * ```ts
+ * const canvas = await core.canvas!.acquire(input.canvas_id, ctx);
+ * await canvas.registerTable('germplasm', rows);
+ * const result = await canvas.query('SELECT name FROM germplasm LIMIT 10');
+ * return { canvas_id: canvas.canvasId, expires_at: canvas.expiresAt, ... };
+ * ```
+ */
+export class DataCanvas {
+    provider;
+    registry;
+    constructor(provider, registry) {
+        this.provider = provider;
+        this.registry = registry;
+        logger.info(`DataCanvas initialized with provider: ${provider.name}`);
+    }
+    /**
+     * Resolve an existing canvas or create a new one. The returned
+     * {@link CanvasInstance} captures `(canvasId, tenantId)` so subsequent
+     * operations don't need to repeat them.
+     */
+    async acquire(maybeId, context, _options) {
+        const tenantId = requireTenantId(context);
+        const result = await this.registry.acquire(maybeId, tenantId, context);
+        logger.debug('Canvas acquired.', {
+            ...context,
+            canvasId: result.canvasId,
+            tenantId,
+            isNew: result.isNew,
+        });
+        return new CanvasInstance(result.canvasId, result.tenantId, result.isNew, result.expiresAt, this.registry, this.provider, context);
+    }
+    /**
+     * Drop a canvas explicitly. Returns true when the canvas existed and was
+     * destroyed.
+     */
+    async drop(canvasId, context) {
+        const tenantId = requireTenantId(context);
+        return await this.registry.drop(canvasId, tenantId, context);
+    }
+    /** Active canvas count for the calling tenant. */
+    countForTenant(context) {
+        const tenantId = requireTenantId(context);
+        return this.registry.countForTenant(tenantId);
+    }
+    /** Liveness check on the underlying provider. */
+    healthCheck() {
+        return this.provider.healthCheck();
+    }
+    /** Tear down the registry and provider. Called from `ServerHandle.shutdown()`. */
+    async shutdown(context) {
+        await this.registry.shutdown(context);
+    }
+    /** @internal Surface the underlying provider for advanced use cases. */
+    getProvider() {
+        return this.provider;
+    }
+}
+//# sourceMappingURL=DataCanvas.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DataCanvas.js","sourceRoot":"","sources":["../../../../src/services/canvas/core/DataCanvas.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAGpD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAIrD;;;;GAIG;AACH,SAAS,eAAe,CAAC,OAAuB;IAC9C,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAClC,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,EAAE,EAAE,CAAC;QACnE,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,aAAa,EAC9B,uFAAuF,EACvF,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,oBAAoB,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CACvF,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,UAAU;IAEF;IACA;IAFnB,YACmB,QAA6B,EAC7B,QAAwB;QADxB,aAAQ,GAAR,QAAQ,CAAqB;QAC7B,aAAQ,GAAR,QAAQ,CAAgB;QAEzC,MAAM,CAAC,IAAI,CAAC,yCAAyC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACxE,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO,CACX,OAA2B,EAC3B,OAAuB,EACvB,QAAyB;QAEzB,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;QAC1C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QACvE,MAAM,CAAC,KAAK,CAAC,kBAAkB,EAAE;YAC/B,GAAG,OAAO;YACV,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,QAAQ;YACR,KAAK,EAAE,MAAM,CAAC,KAAK;SACpB,CAAC,CAAC;QACH,OAAO,IAAI,cAAc,CACvB,MAAM,CAAC,QAAQ,EACf,MAAM,CAAC,QAAQ,EACf,MAAM,CAAC,KAAK,EACZ,MAAM,CAAC,SAAS,EAChB,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,QAAQ,EACb,OAAO,CACR,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI,CAAC,QAAgB,EAAE,OAAuB;QAClD,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;QAC1C,OAAO,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC/D,CAAC;IAED,kDAAkD;IAClD,cAAc,CAAC,OAAuB;QACpC,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;QAC1C,OAAO,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;IAChD,CAAC;IAED,iDAAiD;IACjD,WAAW;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;IACrC,CAAC;IAED,kFAAkF;IAClF,KAAK,CAAC,QAAQ,CAAC,OAAuB;QACpC,MAAM,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACxC,CAAC;IAED,wEAAwE;IACxE,WAAW;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;CACF"}

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

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview Engine-level provider interface for the DataCanvas primitive.
+ * Implementations own the physical resources backing each canvas (e.g. one
+ * DuckDB instance per canvasId) and expose register/query/export/describe
+ * operations keyed by canvasId. The lifecycle wrapper ({@link CanvasRegistry})
+ * keys these calls by `(tenantId, canvasId)` and enforces TTL/caps.
+ * @module src/services/canvas/core/IDataCanvasProvider
+ */
+import type { RequestContext } from '../../../utils/internal/requestContext.js';
+import type { DescribeOptions, ExportOptions, ExportResult, ExportTarget, QueryOptions, QueryResult, RegisterRows, RegisterTableOptions, RegisterTableResult, TableInfo } from '../types.js';
+/**
+ * Engine-level contract. The lifecycle wrapper guarantees `canvasId` is
+ * already validated and authorized for the caller's tenant before any of
+ * these methods are invoked, so providers may treat `canvasId` as opaque
+ * and trusted.
+ */
+export interface IDataCanvasProvider {
+    /** Drop every table on the canvas. Returns the number dropped. */
+    clear(canvasId: string, context: RequestContext): Promise<number>;
+    /** Describe one or all tables on the canvas. */
+    describe(canvasId: string, context: RequestContext, options?: DescribeOptions): Promise<TableInfo[]>;
+    /**
+     * Release engine resources for a canvas. After this call, further ops on
+     * the canvas throw `NotFound`.
+     */
+    destroyCanvas(canvasId: string, context: RequestContext): Promise<void>;
+    /** Drop a single canvas table. Returns `true` when found and removed. */
+    drop(canvasId: string, name: string, context: RequestContext): Promise<boolean>;
+    /** Export a canvas table to a file or stream target. */
+    export(canvasId: string, tableName: string, target: ExportTarget, context: RequestContext, options?: ExportOptions): Promise<ExportResult>;
+    /** Liveness check on the underlying engine. */
+    healthCheck(): Promise<boolean>;
+    /**
+     * Allocate engine resources for a new canvas. Idempotent — calling twice
+     * with the same id is a no-op.
+     */
+    initCanvas(canvasId: string, context: RequestContext): Promise<void>;
+    /** Provider name (e.g. `'duckdb'`). Used in logs and health output. */
+    readonly name: string;
+    /** Run a SQL query against the canvas. Read-only enforcement is the gate's job. */
+    query(canvasId: string, sql: string, context: RequestContext, options?: QueryOptions): Promise<QueryResult>;
+    /** Register a table on the canvas from in-memory or async iterator rows. */
+    registerTable(canvasId: string, name: string, rows: RegisterRows, context: RequestContext, options?: RegisterTableOptions): Promise<RegisterTableResult>;
+    /** Tear down all engine resources. Called from `ServerHandle.shutdown()`. */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=IDataCanvasProvider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IDataCanvasProvider.d.ts","sourceRoot":"","sources":["../../../../src/services/canvas/core/IDataCanvasProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,oBAAoB,EACpB,mBAAmB,EACnB,SAAS,EACV,MAAM,aAAa,CAAC;AAErB;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAElE,gDAAgD;IAChD,QAAQ,CACN,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAExB;;;OAGG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExE,yEAAyE;IACzE,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEhF,wDAAwD;IACxD,MAAM,CACJ,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzB,+CAA+C;IAC/C,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEhC;;;OAGG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,mFAAmF;IACnF,KAAK,CACH,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,WAAW,CAAC,CAAC;IAExB,4EAA4E;IAC5E,aAAa,CACX,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAEhC,6EAA6E;IAC7E,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B"}

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

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview Engine-level provider interface for the DataCanvas primitive.
+ * Implementations own the physical resources backing each canvas (e.g. one
+ * DuckDB instance per canvasId) and expose register/query/export/describe
+ * operations keyed by canvasId. The lifecycle wrapper ({@link CanvasRegistry})
+ * keys these calls by `(tenantId, canvasId)` and enforces TTL/caps.
+ * @module src/services/canvas/core/IDataCanvasProvider
+ */
+export {};
+//# sourceMappingURL=IDataCanvasProvider.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IDataCanvasProvider.js","sourceRoot":"","sources":["../../../../src/services/canvas/core/IDataCanvasProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

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

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Factory for the optional DataCanvas service. Mirrors the
+ * pattern in `createStorageProvider` — switches on `config.canvas.providerType`,
+ * fails closed in serverless environments for `duckdb`, and returns
+ * `undefined` when canvas is disabled (`'none'`).
+ *
+ * The factory does NOT eager-load `@duckdb/node-api`; the provider lazy-loads
+ * on first use via `lazyImport`. Servers that set `CANVAS_PROVIDER_TYPE=none`
+ * (the default) pay zero install cost.
+ *
+ * @module src/services/canvas/core/canvasFactory
+ */
+import type { AppConfig } from '../../../config/index.js';
+import { DataCanvas } from './DataCanvas.js';
+/**
+ * Construct the canvas service from configuration. Returns `undefined` when
+ * canvas is disabled (`CANVAS_PROVIDER_TYPE=none`), keeping `core.canvas`
+ * `undefined` on `CoreServices` for that case.
+ *
+ * In serverless environments, an explicit `CANVAS_PROVIDER_TYPE=duckdb`
+ * fails closed with a clear ConfigurationError — DuckDB has no V8-isolate
+ * build, so canvas is unavailable on Workers. (Refinement #1 in issue #97 is
+ * about export-path sandboxing, separate from this Worker fail-closed.)
+ */
+export declare function createCanvasService(config: AppConfig): DataCanvas | undefined;
+//# sourceMappingURL=canvasFactory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"canvasFactory.d.ts","sourceRoot":"","sources":["../../../../src/services/canvas/core/canvasFactory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAOnD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAO7C;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,CAkC7E"}

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

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview Factory for the optional DataCanvas service. Mirrors the
+ * pattern in `createStorageProvider` — switches on `config.canvas.providerType`,
+ * fails closed in serverless environments for `duckdb`, and returns
+ * `undefined` when canvas is disabled (`'none'`).
+ *
+ * The factory does NOT eager-load `@duckdb/node-api`; the provider lazy-loads
+ * on first use via `lazyImport`. Servers that set `CANVAS_PROVIDER_TYPE=none`
+ * (the default) pay zero install cost.
+ *
+ * @module src/services/canvas/core/canvasFactory
+ */
+import { configurationError } from '../../../types-global/errors.js';
+import { logger } from '../../../utils/internal/logger.js';
+import { requestContextService } from '../../../utils/internal/requestContext.js';
+import { DuckdbProvider } from '../providers/duckdb/DuckdbProvider.js';
+import { CanvasRegistry } from './CanvasRegistry.js';
+import { DataCanvas } from './DataCanvas.js';
+/** Evaluated at call time so worker.ts can set IS_SERVERLESS before first use. */
+function isServerless() {
+    return typeof process === 'undefined' || process.env.IS_SERVERLESS === 'true';
+}
+/**
+ * Construct the canvas service from configuration. Returns `undefined` when
+ * canvas is disabled (`CANVAS_PROVIDER_TYPE=none`), keeping `core.canvas`
+ * `undefined` on `CoreServices` for that case.
+ *
+ * In serverless environments, an explicit `CANVAS_PROVIDER_TYPE=duckdb`
+ * fails closed with a clear ConfigurationError — DuckDB has no V8-isolate
+ * build, so canvas is unavailable on Workers. (Refinement #1 in issue #97 is
+ * about export-path sandboxing, separate from this Worker fail-closed.)
+ */
+export function createCanvasService(config) {
+    const providerType = config.canvas.providerType;
+    if (providerType === 'none')
+        return;
+    const context = requestContextService.createRequestContext({
+        operation: 'createCanvasService',
+    });
+    if (providerType === 'duckdb') {
+        if (isServerless()) {
+            throw configurationError('DuckDB canvas requires Node.js or Bun. Set CANVAS_PROVIDER_TYPE=none or omit it for Cloudflare Workers deployment.', context);
+        }
+        logger.info('Creating DuckDB canvas provider', context);
+        const provider = new DuckdbProvider({
+            memoryLimitMb: config.canvas.defaultMemoryLimitMb,
+            exportRootPath: config.canvas.exportRootPath,
+            defaultRowLimit: config.canvas.defaultRowLimit,
+            schemaSniffRows: config.canvas.schemaSniffRows,
+        });
+        const registry = new CanvasRegistry(provider, {
+            ttlMs: config.canvas.ttlMs,
+            absoluteCapMs: config.canvas.absoluteCapMs,
+            maxCanvasesPerTenant: config.canvas.maxCanvasesPerTenant,
+            sweeperIntervalMs: config.canvas.sweeperIntervalMs,
+        });
+        return new DataCanvas(provider, registry);
+    }
+    // Exhaustive check for the providerType union.
+    const exhaustive = providerType;
+    throw configurationError(`Unhandled canvas provider type: ${String(exhaustive)}`, context);
+}
+//# sourceMappingURL=canvasFactory.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"canvasFactory.js","sourceRoot":"","sources":["../../../../src/services/canvas/core/canvasFactory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAE3E,OAAO,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,kFAAkF;AAClF,SAAS,YAAY;IACnB,OAAO,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,KAAK,MAAM,CAAC;AAChF,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAiB;IACnD,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC;IAChD,IAAI,YAAY,KAAK,MAAM;QAAE,OAAO;IAEpC,MAAM,OAAO,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;QACzD,SAAS,EAAE,qBAAqB;KACjC,CAAC,CAAC;IAEH,IAAI,YAAY,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,YAAY,EAAE,EAAE,CAAC;YACnB,MAAM,kBAAkB,CACtB,oHAAoH,EACpH,OAAO,CACR,CAAC;QACJ,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,iCAAiC,EAAE,OAAO,CAAC,CAAC;QACxD,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAC;YAClC,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,oBAAoB;YACjD,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC,cAAc;YAC5C,eAAe,EAAE,MAAM,CAAC,MAAM,CAAC,eAAe;YAC9C,eAAe,EAAE,MAAM,CAAC,MAAM,CAAC,eAAe;SAC/C,CAAC,CAAC;QACH,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAC,QAAQ,EAAE;YAC5C,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK;YAC1B,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,aAAa;YAC1C,oBAAoB,EAAE,MAAM,CAAC,MAAM,CAAC,oBAAoB;YACxD,iBAAiB,EAAE,MAAM,CAAC,MAAM,CAAC,iBAAiB;SACnD,CAAC,CAAC;QACH,OAAO,IAAI,UAAU,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC5C,CAAC;IAED,+CAA+C;IAC/C,MAAM,UAAU,GAAU,YAAY,CAAC;IACvC,MAAM,kBAAkB,CAAC,mCAAmC,MAAM,CAAC,UAAU,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;AAC7F,CAAC"}