@cyanheads/mcp-ts-core 0.8.7 → 0.8.9

package/CLAUDE.md

@@ -34,6 +34,7 @@
 | `/auth` | `checkScopes` | Dynamic scope checking |
 | `/storage` | `StorageService` | Storage abstraction |
 | `/storage/types` | `IStorageProvider` | Provider interface |
+| `/canvas` | `DataCanvas`, `CanvasInstance`, `CanvasRegistry`, `IDataCanvasProvider`, `DuckdbProvider`, `assertReadOnlyQuery`, `quoteIdentifier`, ... | DataCanvas primitive (Tier 3, optional peer dep `@duckdb/node-api`); SQL/analytical workspace |
 | `/utils` | formatting, encoding, network, pagination, logging, runtime, telemetry, token counting, parsers†, sanitization†, scheduling† | All utilities (†optional peer deps) |
 | `/services` | `OpenRouterProvider`, `SpeechService`, `createSpeechProvider`, `ElevenLabsProvider`, `WhisperProvider`, `GraphService`, provider interfaces and types | LLM, Speech (TTS/STT), Graph services |
 | `/linter` | `validateDefinitions`, `LintReport`, `LintDiagnostic`, `LintInput`, `LintSeverity` | Definition validation |
@@ -492,6 +493,7 @@ Detailed method signatures, options, and examples live in skill files. Read the
 | `api-config` | `skills/api-config/SKILL.md` | AppConfig, parseConfig, env vars |
 | `api-testing` | `skills/api-testing/SKILL.md` | createMockContext, test patterns, MockContextOptions |
 | `api-workers` | `skills/api-workers/SKILL.md` | createWorkerHandler, CloudflareBindings, Worker runtime |
+| `api-canvas` | `skills/api-canvas/SKILL.md` | DataCanvas primitive: acquire/register/query/export, token-sharing model, SQL gate, lifecycle |
 | `api-linter` | `skills/api-linter/SKILL.md` | Definition lint rules (`format-parity`, `schema-*`, `name-*`, `server-json-*`, …) — look here when devcheck reports a lint diagnostic |
 | `add-tool` | `skills/add-tool/SKILL.md` | Scaffold a new MCP tool definition |
 | `add-app-tool` | `skills/add-app-tool/SKILL.md` | Scaffold an MCP App tool + UI resource pair |

package/README.md

@@ -5,7 +5,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.8.7-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE)
+[![Version](https://img.shields.io/badge/Version-0.8.9-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE)
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
 

package/biome.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.4.13/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.4.14/schema.json",
   "vcs": {
     "enabled": true,
     "clientKind": "git",

package/changelog/0.8.x/0.8.8.md

@@ -0,0 +1,11 @@
+---
+summary: "ErrorHandler stops double-writing ended OTel spans (recordException/setStatus); storage decodeCursor no longer leaks server stack traces through McpError.data on malformed cursors."
+breaking: false
+---
+
+# 0.8.8 — 2026-05-01
+
+## Fixed
+
+- **`src/utils/internal/error-handler/errorHandler.ts`** ([#93](https://github.com/cyanheads/mcp-ts-core/issues/93)) — `handleError` now guards its OTel block with `activeSpan.isRecording()`, eliminating two `Cannot execute the operation on ended Span` warnings per tool failure under HTTP+OTel (`measureToolExecution` already records and ends the span before re-throwing). Same fix covers the prompt path; resource path was already clean (uses `classifyOnly`).
+- **`src/storage/core/storageValidation.ts`** ([#71](https://github.com/cyanheads/mcp-ts-core/issues/71)) — `decodeCursor` no longer attaches `error.stack` to `McpError.data.rawError` — the stack goes to `logger.warning`, the thrown error carries only `operation` + request context. `McpError.data` is wire-visible (`structuredContent.error.data`/JSON-RPC `error.data`), so a forged cursor against `ctx.state.list(...)` previously leaked framework paths and version markers. Mirrors the pattern in `src/utils/pagination/pagination.ts`.

package/changelog/0.8.x/0.8.9.md

@@ -0,0 +1,34 @@
+---
+summary: "DataCanvas primitive lands as a Tier 3 SQL/analytical workspace backed by DuckDB ([#97](https://github.com/cyanheads/mcp-ts-core/issues/97)) — opt-in via CANVAS_PROVIDER_TYPE, fails closed on Cloudflare Workers."
+breaking: false
+---
+
+# 0.8.9 — 2026-05-02
+
+First landing of the DataCanvas primitive ([#97](https://github.com/cyanheads/mcp-ts-core/issues/97)) — register tabular data from upstream APIs, run SQL across multiple registered tables, export results. Tier 3, optional peer dep `@duckdb/node-api`, disabled by default.
+
+## Added
+
+- **`@cyanheads/mcp-ts-core/canvas` subpath** (`src/canvas/`) — new public export. Surfaces `DataCanvas`, `CanvasInstance`, `CanvasRegistry`, `IDataCanvasProvider`, `DuckdbProvider`, `assertReadOnlyQuery`, `quoteIdentifier`, plus types (`ColumnSchema`, `RegisterTableOptions`, `QueryOptions`, `ExportOptions`, etc.).
+- **`CoreServices.canvas?: DataCanvas`** (`src/core/app.ts`) — wired in `composeServices()` when `CANVAS_PROVIDER_TYPE !== 'none'`. `undefined` when disabled or running on Workers. `ServerHandle.shutdown()` automatically tears down active DuckDB instances and stops the sweeper.
+- **Token-sharing model** — opaque 10-char URL-safe `canvasId` (~10¹⁸ keyspace). Tools accept an optional `canvas_id` input; framework mints on omit, resolves on match, throws `NotFound` on cross-tenant or unknown id (uniform to avoid existence leaks). Composite scope is `(tenantId, canvasId)`.
+- **Lifecycle controls** — sliding TTL (default 24 h, extended on every op), absolute cap from creation (default 7 d), per-tenant active cap (default 100), background `unref`'d sweeper (default 60 s, set 0 to disable). In-memory only in v1; restart drops all canvases.
+- **DuckDB provider** (`src/canvas/providers/duckdb/`) — one DuckDB instance per canvasId with `memory_limit` PRAGMA. SQL gate (`assertReadOnlyQuery`) blocks writes via AST inspection, not regex. Path-sandbox for file exports (CSV/Parquet/JSON) rejects absolute paths and `..` traversal; stream-based exports bypass. Schema sniffer materializes a sample (default 100 rows) when `schema` is omitted on `registerTable`.
+- **Canvas env vars** (`src/config/index.ts`) — `CANVAS_PROVIDER_TYPE` (`none` | `duckdb`), `CANVAS_DEFAULT_MEMORY_LIMIT_MB` (1024), `CANVAS_EXPORT_PATH` (`./.canvas-exports`), `CANVAS_MAX_CANVASES_PER_TENANT` (100), `CANVAS_TTL_MS` (86400000), `CANVAS_ABSOLUTE_CAP_MS` (604800000), `CANVAS_SWEEPER_INTERVAL_MS` (60000), `CANVAS_DEFAULT_ROW_LIMIT` (10000), `CANVAS_SCHEMA_SNIFF_ROWS` (100). Worker bindings include `CANVAS_PROVIDER_TYPE` so explicit `duckdb` triggers the fail-closed factory path instead of silently no-opping.
+- **Cloudflare Workers fail-closed** — `createCanvasService(config)` throws `ConfigurationError` when `CANVAS_PROVIDER_TYPE=duckdb` is set on a Worker (DuckDB has no V8-isolate build). Leave unset or `none` for Worker deployments.
+- **Test coverage** — 7 unit suites (`tests/unit/canvas/`: `canvasFactory`, `CanvasRegistry`, `classifyDuckdbError`, `DataCanvas`, `exportWriter`, `schemaSniffer`, `sqlGate`) and a real-DuckDB smoke test (`tests/smoke/canvas-duckdb.test.ts`).
+- **`surplus-token-idea` issue label** — new option in `.github/ISSUE_TEMPLATE/{bug_report,feature_request}.yml`, mirrored to `templates/.github/ISSUE_TEMPLATE/`. Added to the label tables in `skills/report-issue-framework/SKILL.md` and `skills/report-issue-local/SKILL.md`, plus a `gh label create` line in the latter (color `FF10F0`).
+
+## Docs
+
+- **`skills/api-canvas/SKILL.md` v1.0** — new skill. Covers acquire → register → query → export flow, the token-sharing pattern for multi-agent collaboration, env config, lifecycle, SQL gate, and Cloudflare Workers fail-closed behavior.
+- **`skills/api-config/SKILL.md`** — new Canvas env var table; platform support note (Linux/macOS/Windows × x64; Linux/macOS arm64; Windows arm64 unsupported per DuckDB upstream).
+- **`skills/api-workers/SKILL.md`** — DataCanvas-unavailable callout with the exact `ConfigurationError` message and a `if (!ctx.core.canvas) { ... }` guard pattern.
+- **`AGENTS.md` / `CLAUDE.md`** — `/canvas` row added to the exports table; `api-canvas` row added to the skills table.
+
+## Deps
+
+- `@biomejs/biome` 2.4.13 → 2.4.14 (schema URL bumped in `biome.json`).
+- `@cloudflare/workers-types` 4.20260501.1 → 4.20260502.1 (daily roll).
+- `zod` 4.4.1 → 4.4.2 (resolutions + runtime dep + peer range).
+- **Added** `@duckdb/node-api` ^1.5.2-r.1 as devDependency and optional peerDependency (Tier 3 — only installed when canvas is enabled).

package/dist/canvas/core/CanvasInstance.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Per-canvas handle returned by {@link DataCanvas.acquire}. Captures
+ * `(canvasId, tenantId)` once so callers don't repeat them on every op, and
+ * routes each call through the registry's TTL-touch + tenant validation gate
+ * before delegating to the provider.
+ * @module src/canvas/core/CanvasInstance
+ */
+import type { RequestContext } from '../../utils/internal/requestContext.js';
+import type { DescribeOptions, ExportOptions, ExportResult, ExportTarget, QueryOptions, QueryResult, RegisterRows, RegisterTableOptions, RegisterTableResult, TableInfo } from '../types.js';
+import type { CanvasRegistry } from './CanvasRegistry.js';
+import type { IDataCanvasProvider } from './IDataCanvasProvider.js';
+/** Handle bound to a single canvas. Returned from {@link DataCanvas.acquire}. */
+export declare class CanvasInstance {
+    /** Opaque canvas token. Surface this to callers; share it across agents. */
+    readonly canvasId: string;
+    /** Tenant the canvas is bound to. Resolved by the registry from `RequestContext`. */
+    readonly tenantId: string;
+    private readonly registry;
+    private readonly provider;
+    private readonly context;
+    /** True when {@link DataCanvas.acquire} created this canvas during the current call. */
+    readonly isNew: boolean;
+    /** ISO 8601 expiry after the most recent operation extended the sliding TTL. */
+    expiresAt: string;
+    constructor(
+    /** Opaque canvas token. Surface this to callers; share it across agents. */
+    canvasId: string, 
+    /** Tenant the canvas is bound to. Resolved by the registry from `RequestContext`. */
+    tenantId: string, isNew: boolean, expiresAt: string, registry: CanvasRegistry, provider: IDataCanvasProvider, context: RequestContext);
+    /** Register a table on the canvas. */
+    registerTable(name: string, rows: RegisterRows, options?: RegisterTableOptions): Promise<RegisterTableResult>;
+    /** Run a SQL query against the canvas. */
+    query(sql: string, options?: QueryOptions): Promise<QueryResult>;
+    /** Export a canvas table to a path or stream target. */
+    export(tableName: string, target: ExportTarget, options?: ExportOptions): Promise<ExportResult>;
+    /** Describe one or all canvas tables. */
+    describe(options?: DescribeOptions): Promise<TableInfo[]>;
+    /** Drop a single canvas table. Returns `true` when found and removed. */
+    drop(name: string): Promise<boolean>;
+    /** Drop every table on the canvas. Returns the number dropped. */
+    clear(): Promise<number>;
+}
+//# sourceMappingURL=CanvasInstance.d.ts.map

package/dist/canvas/core/CanvasInstance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CanvasInstance.d.ts","sourceRoot":"","sources":["../../../src/canvas/core/CanvasInstance.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;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;AACrB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,iFAAiF;AACjF,qBAAa,cAAc;IAOvB,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,EAAE,MAAM;IAGzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAd1B,wFAAwF;IACxF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAC;;IAGhB,4EAA4E;IACnE,QAAQ,EAAE,MAAM;IACzB,qFAAqF;IAC5E,QAAQ,EAAE,MAAM,EACzB,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,EACA,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,EAAE,cAAc;IAM1C,sCAAsC;IAChC,aAAa,CACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,YAAY,EAClB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC;IAK/B,0CAA0C;IACpC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAKtE,wDAAwD;IAClD,MAAM,CACV,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,CAAC;IAKxB,yCAAyC;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAK/D,yEAAyE;IACnE,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAK1C,kEAAkE;IAC5D,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;CAI/B"}

package/dist/canvas/core/CanvasInstance.js

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview Per-canvas handle returned by {@link DataCanvas.acquire}. Captures
+ * `(canvasId, tenantId)` once so callers don't repeat them on every op, and
+ * routes each call through the registry's TTL-touch + tenant validation gate
+ * before delegating to the provider.
+ * @module src/canvas/core/CanvasInstance
+ */
+/** Handle bound to a single canvas. Returned from {@link DataCanvas.acquire}. */
+export class CanvasInstance {
+    canvasId;
+    tenantId;
+    registry;
+    provider;
+    context;
+    /** True when {@link DataCanvas.acquire} created this canvas during the current call. */
+    isNew;
+    /** ISO 8601 expiry after the most recent operation extended the sliding TTL. */
+    expiresAt;
+    constructor(
+    /** Opaque canvas token. Surface this to callers; share it across agents. */
+    canvasId, 
+    /** Tenant the canvas is bound to. Resolved by the registry from `RequestContext`. */
+    tenantId, isNew, expiresAt, registry, provider, context) {
+        this.canvasId = canvasId;
+        this.tenantId = tenantId;
+        this.registry = registry;
+        this.provider = provider;
+        this.context = context;
+        this.isNew = isNew;
+        this.expiresAt = expiresAt;
+    }
+    /** Register a table on the canvas. */
+    async registerTable(name, rows, options) {
+        this.expiresAt = this.registry.touchOrThrow(this.canvasId, this.tenantId);
+        return await this.provider.registerTable(this.canvasId, name, rows, this.context, options);
+    }
+    /** Run a SQL query against the canvas. */
+    async query(sql, options) {
+        this.expiresAt = this.registry.touchOrThrow(this.canvasId, this.tenantId);
+        return await this.provider.query(this.canvasId, sql, this.context, options);
+    }
+    /** Export a canvas table to a path or stream target. */
+    async export(tableName, target, options) {
+        this.expiresAt = this.registry.touchOrThrow(this.canvasId, this.tenantId);
+        return await this.provider.export(this.canvasId, tableName, target, this.context, options);
+    }
+    /** Describe one or all canvas tables. */
+    async describe(options) {
+        this.expiresAt = this.registry.touchOrThrow(this.canvasId, this.tenantId);
+        return await this.provider.describe(this.canvasId, this.context, options);
+    }
+    /** Drop a single canvas table. Returns `true` when found and removed. */
+    async drop(name) {
+        this.expiresAt = this.registry.touchOrThrow(this.canvasId, this.tenantId);
+        return await this.provider.drop(this.canvasId, name, this.context);
+    }
+    /** Drop every table on the canvas. Returns the number dropped. */
+    async clear() {
+        this.expiresAt = this.registry.touchOrThrow(this.canvasId, this.tenantId);
+        return await this.provider.clear(this.canvasId, this.context);
+    }
+}
+//# sourceMappingURL=CanvasInstance.js.map

package/dist/canvas/core/CanvasInstance.js.map

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

package/dist/canvas/core/CanvasRegistry.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @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/canvas/core/CanvasRegistry
+ */
+import { type RequestContext } from '../../utils/internal/requestContext.js';
+import type { IDataCanvasProvider } from './IDataCanvasProvider.js';
+/** Tunable lifecycle constants for the registry. */
+export interface CanvasRegistryOptions {
+    /** Absolute cap from creation in milliseconds. Default 7d. */
+    absoluteCapMs: number;
+    /** Maximum active canvases per tenant. Default 100. */
+    maxCanvasesPerTenant: number;
+    /** Sweeper interval in milliseconds. Default 60s. Set to 0 to disable. */
+    sweeperIntervalMs: number;
+    /** Sliding TTL in milliseconds. Default 24h. */
+    ttlMs: number;
+}
+/**
+ * Default lifecycle constants. Mirrored in the config schema; exported so
+ * tests and downstream tooling can reference the same numbers.
+ */
+export declare const DEFAULT_CANVAS_REGISTRY_OPTIONS: CanvasRegistryOptions;
+/** Result of {@link CanvasRegistry.acquire}. */
+export interface AcquireResult {
+    canvasId: string;
+    /** Wall-clock expiry as ISO 8601, after the sliding extension. */
+    expiresAt: string;
+    /** True when the registry created the canvas during this acquire call. */
+    isNew: boolean;
+    tenantId: string;
+}
+/**
+ * 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 declare class CanvasRegistry {
+    private readonly provider;
+    private readonly options;
+    /** Injected for tests. Defaults to `Date.now`. */
+    private readonly clock;
+    private readonly idGenerator;
+    private readonly canvases;
+    /** Per-tenant index for cap enforcement and listing. */
+    private readonly byTenant;
+    private sweeperTimer;
+    private isShuttingDown;
+    constructor(provider: IDataCanvasProvider, options?: CanvasRegistryOptions, 
+    /** Injected for tests. Defaults to `Date.now`. */
+    clock?: () => number);
+    /**
+     * 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`.
+     */
+    acquire(maybeId: string | undefined, tenantId: string, context: RequestContext): Promise<AcquireResult>;
+    /**
+     * 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: string, tenantId: string): string;
+    /**
+     * Drop a canvas explicitly (e.g. tenant-initiated cleanup). Returns true
+     * when the canvas existed and was destroyed.
+     */
+    drop(canvasId: string, tenantId: string, context: RequestContext): Promise<boolean>;
+    /** Active canvas count for a tenant (used by tests and metrics surfaces). */
+    countForTenant(tenantId: string): number;
+    /** Total active canvases (used by tests and metrics surfaces). */
+    totalActive(): number;
+    /** Stop the sweeper and tear down every active canvas. Idempotent. */
+    shutdown(context: RequestContext): Promise<void>;
+    /** @internal Test/diagnostic hook — runs one sweep pass synchronously. */
+    sweep(): Promise<void>;
+    private lookup;
+    private touch;
+    private enforceTenantCap;
+    private mintId;
+    private indexByTenant;
+    private destroy;
+}
+//# sourceMappingURL=CanvasRegistry.d.ts.map

package/dist/canvas/core/CanvasRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CanvasRegistry.d.ts","sourceRoot":"","sources":["../../../src/canvas/core/CanvasRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAE,KAAK,cAAc,EAAyB,MAAM,oCAAoC,CAAC;AAEhG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAoBpE,oDAAoD;AACpD,MAAM,WAAW,qBAAqB;IACpC,8DAA8D;IAC9D,aAAa,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,0EAA0E;IAC1E,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,eAAO,MAAM,+BAA+B,EAAE,qBAK7C,CAAC;AAEF,gDAAgD;AAChD,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,qBAAa,cAAc;IASvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,kDAAkD;IAClD,OAAO,CAAC,QAAQ,CAAC,KAAK;IAXxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,wDAAwD;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAC3D,OAAO,CAAC,YAAY,CAA6C;IACjE,OAAO,CAAC,cAAc,CAAS;gBAGZ,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,GAAE,qBAAuD;IACjF,kDAAkD;IACjC,KAAK,GAAE,MAAM,MAAiB;IASjD;;;;;;;;;OASG;IACG,OAAO,CACX,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,CAAC;IAmDzB;;;;OAIG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IASxD;;;OAGG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAOzF,6EAA6E;IAC7E,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAIxC,kEAAkE;IAClE,WAAW,IAAI,MAAM;IAIrB,sEAAsE;IAChE,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAYtD,0EAA0E;IACpE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAwB5B,OAAO,CAAC,MAAM;IAYd,OAAO,CAAC,KAAK;IAQb,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,MAAM;IASd,OAAO,CAAC,aAAa;YASP,OAAO;CAiBtB"}

package/dist/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/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/canvas/core/CanvasRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CanvasRegistry.js","sourceRoot":"","sources":["../../../src/canvas/core/CanvasRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACpD,OAAO,EAAuB,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAChG,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAG9D;;;GAGG;AACH,MAAM,iBAAiB,GAAG,kEAAkE,CAAC;AAC7F,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAC5B,MAAM,eAAe,GAAG,qBAAqB,CAAC;AAwB9C;;;GAGG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAA0B;IACpE,KAAK,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;IAC1B,aAAa,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;IACtC,oBAAoB,EAAE,GAAG;IACzB,iBAAiB,EAAE,EAAE,GAAG,IAAI;CAC7B,CAAC;AAYF;;;;GAIG;AACH,MAAM,OAAO,cAAc;IASN;IACA;IAEA;IAXF,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;IAChC,QAAQ,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC5D,wDAAwD;IACvC,QAAQ,GAAG,IAAI,GAAG,EAAuB,CAAC;IACnD,YAAY,CAA6C;IACzD,cAAc,GAAG,KAAK,CAAC;IAE/B,YACmB,QAA6B,EAC7B,UAAiC,+BAA+B;IACjF,kDAAkD;IACjC,QAAsB,IAAI,CAAC,GAAG;QAH9B,aAAQ,GAAR,QAAQ,CAAqB;QAC7B,YAAO,GAAP,OAAO,CAAyD;QAEhE,UAAK,GAAL,KAAK,CAAyB;QAE/C,IAAI,OAAO,CAAC,iBAAiB,GAAG,CAAC,EAAE,CAAC;YAClC,IAAI,CAAC,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC,KAAK,EAAE,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;YACpF,0DAA0D;YAC1D,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,EAAE,CAAC;QAC9B,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,OAAO,CACX,OAA2B,EAC3B,QAAgB,EAChB,OAAuB;QAEvB,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,MAAM,QAAQ,CAAC,mCAAmC,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;QACpE,CAAC;QAED,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;YAC9C,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,QAAQ,CAAC,oEAAoE,EAAE;oBACnF,QAAQ,EAAE,OAAO;iBAClB,CAAC,CAAC;YACL,CAAC;YACD,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACnB,OAAO;gBACL,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,KAAK,EAAE,KAAK;gBACZ,SAAS,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE;aACpD,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QACzB,MAAM,MAAM,GAAiB;YAC3B,QAAQ;YACR,QAAQ;YACR,SAAS,EAAE,GAAG;YACd,cAAc,EAAE,GAAG;YACnB,SAAS,EAAE,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK;SACpC,CAAC;QACF,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACpC,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAEvC,MAAM,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAElD,MAAM,CAAC,KAAK,CAAC,iBAAiB,EAAE;YAC9B,GAAG,OAAO;YACV,QAAQ;YACR,QAAQ;YACR,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI;SAC7B,CAAC,CAAC;QAEH,OAAO;YACL,QAAQ;YACR,QAAQ;YACR,KAAK,EAAE,IAAI;YACX,SAAS,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE;SACpD,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,YAAY,CAAC,QAAgB,EAAE,QAAgB;QAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAC/C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,QAAQ,CAAC,8BAA8B,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC/D,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACnB,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC;IAClD,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI,CAAC,QAAgB,EAAE,QAAgB,EAAE,OAAuB;QACpE,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAC/C,IAAI,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QAC1B,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,6EAA6E;IAC7E,cAAc,CAAC,QAAgB;QAC7B,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC;IAChD,CAAC;IAED,kEAAkE;IAClE,WAAW;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;IAC5B,CAAC;IAED,sEAAsE;IACtE,KAAK,CAAC,QAAQ,CAAC,OAAuB;QACpC,IAAI,IAAI,CAAC,cAAc;YAAE,OAAO;QAChC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC3B,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACjC,IAAI,CAAC,YAAY,GAAG,SAAS,CAAC;QAChC,CAAC;QACD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;QACnD,MAAM,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;QACvE,MAAM,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;IACjC,CAAC;IAED,0EAA0E;IAC1E,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,cAAc;YAAE,OAAO;QAChC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QACzB,MAAM,OAAO,GAAmB,EAAE,CAAC;QACnC,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;YAC5C,IAAI,GAAG,IAAI,MAAM,CAAC,SAAS,IAAI,GAAG,GAAG,MAAM,CAAC,SAAS,IAAI,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,CAAC;gBACpF,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QACjC,MAAM,YAAY,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;YAC9D,SAAS,EAAE,sBAAsB;SAClC,CAAC,CAAC;QACH,MAAM,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;QAC5E,MAAM,CAAC,KAAK,CAAC,4CAA4C,EAAE;YACzD,GAAG,YAAY;YACf,cAAc,EAAE,OAAO,CAAC,MAAM;SAC/B,CAAC,CAAC;IACL,CAAC;IAED,wEAAwE;IACxE,YAAY;IACZ,wEAAwE;IAEhE,MAAM,CAAC,QAAgB,EAAE,QAAgB;QAC/C,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAC;YAAE,OAAO;QAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM;YAAE,OAAO;QACpB,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ;YAAE,OAAO;QACzC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QACzB,IAAI,GAAG,IAAI,MAAM,CAAC,SAAS,IAAI,GAAG,GAAG,MAAM,CAAC,SAAS,IAAI,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,CAAC;YACpF,OAAO;QACT,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAEO,KAAK,CAAC,MAAoB;QAChC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,cAAc,GAAG,GAAG,CAAC;QAC5B,MAAM,aAAa,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;QAC/C,MAAM,cAAc,GAAG,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC;QACrE,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC;IAC7D,CAAC;IAEO,gBAAgB,CAAC,QAAgB;QACvC,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC;QACrD,IAAI,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,oBAAoB,EAAE,CAAC;YAC/C,MAAM,WAAW,CACf,6CAA6C,IAAI,CAAC,OAAO,CAAC,oBAAoB,qEAAqE,EACnJ,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,oBAAoB,EAAE,CACzE,CAAC;QACJ,CAAC;IACH,CAAC;IAEO,MAAM;QACZ,4DAA4D;QAC5D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9B,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,oBAAoB,CAAC,gBAAgB,EAAE,iBAAiB,CAAC,CAAC;YACtF,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAE,OAAO,EAAE,CAAC;QACxC,CAAC;QACD,MAAM,QAAQ,CAAC,yDAAyD,CAAC,CAAC;IAC5E,CAAC;IAEO,aAAa,CAAC,QAAgB,EAAE,QAAgB;QACtD,IAAI,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACtC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QACnC,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACpB,CAAC;IAEO,KAAK,CAAC,OAAO,CAAC,MAAoB,EAAE,OAAuB;QACjE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACtC,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC/C,IAAI,GAAG,EAAE,CAAC;YACR,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC5B,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC;gBAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC5D,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC9D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,OAAO,CAAC,6CAA6C,EAAE;gBAC5D,GAAG,OAAO;gBACV,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;aACxD,CAAC,CAAC;QACL,CAAC;IACH,CAAC;CACF"}

package/dist/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/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/canvas/core/DataCanvas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DataCanvas.d.ts","sourceRoot":"","sources":["../../../src/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"}