/** * @fileoverview Adapter between BLS tools and the framework DataCanvas * primitive. Holds one shared canvas per tenant, generates `df_XXXXX_XXXXX` * table names, derives all-nullable schemas (sparse BLS columns must not trip * NOT NULL appender rollbacks), tracks per-table TTL + provenance in `ctx.state`, * and lazy-sweeps expired tables on every public op. * @module services/canvas-bridge/canvas-bridge */ import type { Context } from '@cyanheads/mcp-ts-core'; import { type ColumnSchema, type DataCanvas, type QueryResult } from '@cyanheads/mcp-ts-core/canvas'; /** Per-table provenance + TTL metadata persisted in `ctx.state`. */ export interface DataframeMeta { columnSchema: ColumnSchema[]; createdAt: string; expiresAt: string; maxRows: number | undefined; queryParams: Record; rowCount: number; sourceTool: string; tableName: string; truncated: boolean; } export interface RegisterDataframeResult { columnSchema: ColumnSchema[]; expiresAt: string; rowCount: number; tableName: string; } export declare function toDatasetField(registered: RegisterDataframeResult): { name: string; row_count: number; expires_at: string; }; export interface RegisterDataframeOptions { maxRows?: number; queryParams: Record; rows: Record[]; sourceTool: string; truncated?: boolean; } export interface BridgeQueryOptions { preview?: number; queryParams?: Record; registerAs?: string; rowLimit?: number; sourceTool?: string; } export declare function deriveAllNullableSchema(rows: Record[]): ColumnSchema[]; export declare class CanvasBridge { private readonly canvas; constructor(canvas: DataCanvas); /** * Register `options.rows` as a canvas table and return its handle. * * Throws on failure rather than returning a sentinel. Callers register a * dataframe precisely because the rows do not fit inline, so a swallowed * failure would leave them returning a truncated preview that reads as a * complete result. `canvas_registration_failed` is deliberately distinct from * `canvas_unavailable`: canvas is configured here — only this call failed, so * "enable canvas" is the wrong recovery to hand back. */ registerDataframe(ctx: Context, options: RegisterDataframeOptions): Promise; describe(ctx: Context, tableName?: string): Promise; query(ctx: Context, sql: string, options?: BridgeQueryOptions): Promise<{ result: QueryResult; meta?: DataframeMeta; }>; drop(ctx: Context, tableName: string): Promise; private sweepExpired; private iterateMeta; private acquireSharedCanvas; private mintTableName; } export declare function initCanvasBridge(canvas: DataCanvas | undefined): void; export declare function getCanvasBridge(): CanvasBridge | undefined; //# sourceMappingURL=canvas-bridge.d.ts.map