@quereus/quereus 0.1.0

package/dist/src/runtime/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../../src/runtime/scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,KAAK,EAAE,WAAW,EAAqB,MAAM,oBAAoB,CAAC;AAMzE,KAAK,iBAAiB,GAAG,MAAM,GAAG,IAAI,CAAC;AAoCvC,qBAAa,SAAS;IACrB,QAAQ,CAAC,YAAY,EAAE,WAAW,EAAE,CAAM;IAC1C,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,EAAE,iBAAiB,EAAE,CAAC;gBAE/B,IAAI,EAAE,WAAW;IAwB7B,GAAG,CAAC,GAAG,EAAE,cAAc,GAAG,WAAW;IAUrC,OAAO,CAAC,YAAY;YA4BN,QAAQ;IA4CtB,OAAO,CAAC,cAAc;YAiDR,mBAAmB;IAwEjC,OAAO,CAAC,cAAc;YA6CR,mBAAmB;IAgDjC,OAAO,CAAC,yBAAyB;YAgCnB,8BAA8B;IAqB5C,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,mBAAmB;IA+B3B;;OAEG;IACH,UAAU,IAAI,uBAAuB,EAAE;CAQvC"}

package/dist/src/runtime/scheduler.js

@@ -0,0 +1,385 @@
+import { isAsyncIterable } from "./utils.js";
+import { createLogger } from "../common/logger.js";
+const log = createLogger('runtime:metrics');
+/** Symbol to mark wrapped iterables to prevent double-wrapping */
+const TRACED_ITERABLE_SYMBOL = Symbol('tracedIterable');
+/**
+ * Wraps an async iterable to emit row-level trace events
+ */
+function wrapIterableForTracing(src, ctx, instructionIndex, instruction) {
+    // Prevent double-wrapping
+    if (src[TRACED_ITERABLE_SYMBOL]) {
+        return src;
+    }
+    const tracer = ctx.tracer;
+    const wrapped = (async function* () {
+        let rowIndex = 0;
+        for await (const row of src) {
+            // Only emit row trace events for valid rows (non-empty arrays)
+            if (Array.isArray(row) && row.length > 0) {
+                tracer.traceRow(instructionIndex, instruction, rowIndex++, row);
+            }
+            yield row;
+        }
+    })();
+    // Mark as already wrapped
+    wrapped[TRACED_ITERABLE_SYMBOL] = true;
+    return wrapped;
+}
+export class Scheduler {
+    instructions = [];
+    /** Index of the instruction that consumes the output of each instruction. */
+    destinations;
+    constructor(root) {
+        const argIndexes = [];
+        const buildPlan = (inst) => {
+            const instArgIndexes = inst.params.map(p => buildPlan(p));
+            const currentIndex = this.instructions.push(inst) - 1;
+            argIndexes[currentIndex] = instArgIndexes;
+            return currentIndex;
+        };
+        buildPlan(root);
+        this.destinations = new Array(this.instructions.length).fill(null);
+        for (let instIndex = 0; instIndex < this.instructions.length; ++instIndex) {
+            const instArgIndexes = argIndexes[instIndex];
+            if (instArgIndexes) {
+                for (let argIndex = 0; argIndex < instArgIndexes.length; ++argIndex) {
+                    this.destinations[instArgIndexes[argIndex]] = instIndex;
+                }
+            }
+        }
+    }
+    run(ctx) {
+        if (ctx.enableMetrics) {
+            return this.runWithMetrics(ctx);
+        }
+        else if (!ctx.tracer) {
+            return this.runOptimized(ctx);
+        }
+        else {
+            return this.runWithTracing(ctx);
+        }
+    }
+    runOptimized(ctx) {
+        // Argument lists for each instruction.
+        const instrArgs = new Array(this.instructions.length).fill(null).map(() => []);
+        // Running output
+        let output;
+        // Run synchronously until we hit a promise
+        for (let i = 0; i < this.instructions.length; ++i) {
+            const args = instrArgs[i]; // Guaranteed not to contain promises
+            instrArgs[i] = undefined; // Clear args as we go to minimize memory usage.
+            output = this.instructions[i].run(ctx, ...args);
+            // If the instruction returned a promise, switch to async mode for rest of instructions
+            if (output instanceof Promise) {
+                return this.runAsync(ctx, instrArgs, i, output);
+            }
+            // Store synchronous output
+            const destination = this.destinations[i];
+            if (destination !== null) {
+                instrArgs[destination].push(output);
+            }
+        }
+        return output;
+    }
+    async runAsync(ctx, instrArgs, startIndex, pendingOutput) {
+        // Instruction indexes that have promise arguments
+        const hasPromise = [];
+        let output = pendingOutput;
+        // Store the output from the transition instruction
+        const transitionDestination = this.destinations[startIndex];
+        if (transitionDestination !== null) {
+            instrArgs[transitionDestination].push(output);
+            hasPromise[transitionDestination] = true;
+        }
+        // Continue with remaining instructions asynchronously
+        for (let i = startIndex + 1; i < this.instructions.length; ++i) {
+            let args = instrArgs[i];
+            instrArgs[i] = undefined;
+            // Resolve any promise arguments
+            if (hasPromise[i]) {
+                args = await Promise.all(args);
+            }
+            // Run the instruction
+            output = this.instructions[i].run(ctx, ...args);
+            // Store the output
+            const destination = this.destinations[i];
+            if (destination !== null) {
+                instrArgs[destination].push(output);
+                if (output instanceof Promise) {
+                    hasPromise[destination] = true;
+                }
+            }
+        }
+        return output;
+    }
+    runWithTracing(ctx) {
+        // Argument lists for each instruction.
+        const instrArgs = new Array(this.instructions.length).fill(null).map(() => []);
+        // Running output
+        let output;
+        // Run synchronously until we hit a promise
+        for (let i = 0; i < this.instructions.length; ++i) {
+            const instruction = this.instructions[i];
+            const args = instrArgs[i]; // Guaranteed not to contain promises
+            instrArgs[i] = undefined; // Clear args as we go to minimize memory usage.
+            // Trace input
+            ctx.tracer.traceInput(i, instruction, args);
+            try {
+                output = instruction.run(ctx, ...args);
+                // If the instruction returned a promise, switch to async mode for rest of instructions
+                if (output instanceof Promise) {
+                    return this.runAsyncWithTracing(ctx, instrArgs, i, output);
+                }
+                // Wrap async iterables for row-level tracing
+                if (isAsyncIterable(output)) {
+                    output = wrapIterableForTracing(output, ctx, i, instruction);
+                }
+                // Trace output - handle promises properly
+                ctx.tracer.traceOutput(i, instruction, output);
+                // Keep the original output (promise or value) for flow control
+            }
+            catch (error) {
+                // Trace error
+                ctx.tracer.traceError(i, instruction, error);
+                throw error; // Re-throw the error
+            }
+            // Store synchronous output
+            const destination = this.destinations[i];
+            if (destination !== null) {
+                instrArgs[destination].push(output);
+            }
+        }
+        return output;
+    }
+    async runAsyncWithTracing(ctx, instrArgs, startIndex, pendingOutput) {
+        // Handle the initial pending output
+        let resolvedPendingOutput = await pendingOutput;
+        if (isAsyncIterable(resolvedPendingOutput)) {
+            resolvedPendingOutput = wrapIterableForTracing(resolvedPendingOutput, ctx, startIndex, this.instructions[startIndex]);
+        }
+        ctx.tracer.traceOutput(startIndex, this.instructions[startIndex], resolvedPendingOutput);
+        // Instruction indexes that have promise arguments
+        const hasPromise = [];
+        let output = resolvedPendingOutput;
+        // Store the output from the transition instruction
+        const transitionDestination = this.destinations[startIndex];
+        if (transitionDestination !== null) {
+            instrArgs[transitionDestination].push(output);
+            hasPromise[transitionDestination] = true;
+        }
+        // Continue with remaining instructions asynchronously
+        for (let i = startIndex + 1; i < this.instructions.length; ++i) {
+            const instruction = this.instructions[i];
+            let args = instrArgs[i];
+            instrArgs[i] = undefined;
+            // Resolve any promise arguments
+            if (hasPromise[i]) {
+                args = await Promise.all(args);
+            }
+            // Trace input
+            ctx.tracer.traceInput(i, instruction, args);
+            try {
+                output = instruction.run(ctx, ...args);
+                // Resolve and wrap async output for tracing
+                let resolvedOutput = output instanceof Promise ? await output : output;
+                if (isAsyncIterable(resolvedOutput)) {
+                    resolvedOutput = wrapIterableForTracing(resolvedOutput, ctx, i, instruction);
+                    output = resolvedOutput; // Update output to the wrapped version
+                }
+                // Trace output
+                ctx.tracer.traceOutput(i, instruction, resolvedOutput);
+                // Keep the original output (promise or value) for flow control
+            }
+            catch (error) {
+                // Trace error
+                ctx.tracer.traceError(i, instruction, error);
+                throw error; // Re-throw the error
+            }
+            // Store the output
+            const destination = this.destinations[i];
+            if (destination !== null) {
+                instrArgs[destination].push(output);
+                if (output instanceof Promise) {
+                    hasPromise[destination] = true;
+                }
+            }
+        }
+        return output;
+    }
+    runWithMetrics(ctx) {
+        // Initialize metrics for all instructions
+        for (const instruction of this.instructions) {
+            if (!instruction.runtimeStats) {
+                instruction.runtimeStats = {
+                    in: 0,
+                    out: 0,
+                    elapsedNs: 0n,
+                    executions: 0
+                };
+            }
+        }
+        // Argument lists for each instruction.
+        const instrArgs = new Array(this.instructions.length).fill(null).map(() => []);
+        // Running output
+        let output;
+        // Run synchronously until we hit a promise
+        for (let i = 0; i < this.instructions.length; ++i) {
+            const instruction = this.instructions[i];
+            const args = instrArgs[i];
+            instrArgs[i] = undefined; // Clear args as we go to minimize memory usage.
+            // Run with metrics collection
+            output = this.runInstructionWithMetrics(instruction, ctx, args);
+            // If the instruction returned a promise, switch to async mode for rest of instructions
+            if (output instanceof Promise) {
+                return this.runAsyncWithMetrics(ctx, instrArgs, i, output);
+            }
+            // Store synchronous output
+            const destination = this.destinations[i];
+            if (destination !== null) {
+                instrArgs[destination].push(output);
+            }
+        }
+        // Log aggregate metrics if debugging is enabled
+        this.logAggregateMetrics();
+        return output;
+    }
+    async runAsyncWithMetrics(ctx, instrArgs, startIndex, pendingOutput) {
+        // Instruction indexes that have promise arguments
+        const hasPromise = [];
+        let output = pendingOutput;
+        // Store the output from the transition instruction
+        const transitionDestination = this.destinations[startIndex];
+        if (transitionDestination !== null) {
+            instrArgs[transitionDestination].push(output);
+            hasPromise[transitionDestination] = true;
+        }
+        // Continue with remaining instructions asynchronously
+        for (let i = startIndex + 1; i < this.instructions.length; ++i) {
+            const instruction = this.instructions[i];
+            let args = instrArgs[i];
+            instrArgs[i] = undefined;
+            // Resolve any promise arguments
+            if (hasPromise[i]) {
+                args = await Promise.all(args);
+            }
+            // Run with metrics collection
+            output = await this.runInstructionWithMetricsAsync(instruction, ctx, args);
+            // Store the output
+            const destination = this.destinations[i];
+            if (destination !== null) {
+                instrArgs[destination].push(output);
+                if (output instanceof Promise) {
+                    hasPromise[destination] = true;
+                }
+            }
+        }
+        // Log aggregate metrics if debugging is enabled
+        this.logAggregateMetrics();
+        return output;
+    }
+    runInstructionWithMetrics(instruction, ctx, args) {
+        const stats = instruction.runtimeStats;
+        const start = process.hrtime.bigint();
+        stats.executions++;
+        stats.in += this.countInputs(args);
+        try {
+            const result = instruction.run(ctx, ...args);
+            if (result instanceof Promise) {
+                // Handle async results separately
+                return result.then(resolved => {
+                    stats.out += this.countOutputs(resolved);
+                    stats.elapsedNs += process.hrtime.bigint() - start;
+                    return resolved;
+                }).catch(error => {
+                    stats.elapsedNs += process.hrtime.bigint() - start;
+                    throw error;
+                });
+            }
+            else {
+                // Sync result
+                stats.out += this.countOutputs(result);
+                stats.elapsedNs += process.hrtime.bigint() - start;
+                return result;
+            }
+        }
+        catch (error) {
+            stats.elapsedNs += process.hrtime.bigint() - start;
+            throw error;
+        }
+    }
+    async runInstructionWithMetricsAsync(instruction, ctx, args) {
+        const stats = instruction.runtimeStats;
+        const start = process.hrtime.bigint();
+        stats.executions++;
+        stats.in += this.countInputs(args);
+        try {
+            const result = instruction.run(ctx, ...args);
+            const resolved = result instanceof Promise ? await result : result;
+            stats.out += this.countOutputs(resolved);
+            stats.elapsedNs += process.hrtime.bigint() - start;
+            return resolved;
+        }
+        catch (error) {
+            stats.elapsedNs += process.hrtime.bigint() - start;
+            throw error;
+        }
+    }
+    countInputs(args) {
+        let count = 0;
+        for (const arg of args) {
+            if (Array.isArray(arg)) {
+                count += arg.length; // Count array elements
+            }
+            else if (isAsyncIterable(arg)) {
+                count += 1; // Count iterables as 1 (we can't know size without consuming)
+            }
+            else {
+                count += 1; // Count other values as 1
+            }
+        }
+        return count;
+    }
+    countOutputs(result) {
+        if (Array.isArray(result)) {
+            return result.length;
+        }
+        else if (isAsyncIterable(result)) {
+            return 1; // Count iterables as 1 (we can't know size without consuming)
+        }
+        else {
+            return 1;
+        }
+    }
+    logAggregateMetrics() {
+        if (!log.enabled && !log.extend('stats').enabled) {
+            return;
+        }
+        const statsLog = log.extend('stats');
+        statsLog('Execution metrics summary:');
+        let totalTime = 0n;
+        for (let i = 0; i < this.instructions.length; i++) {
+            const instruction = this.instructions[i];
+            const stats = instruction.runtimeStats;
+            if (stats) {
+                const elapsedMs = Number(stats.elapsedNs) / 1_000_000;
+                totalTime += stats.elapsedNs;
+                statsLog('  [%d] %s: %d exec, %d in, %d out, %.2fms', i, instruction.note || 'unknown', stats.executions, stats.in, stats.out, elapsedMs);
+            }
+        }
+        const totalMs = Number(totalTime) / 1_000_000;
+        statsLog('Total execution time: %.2fms', totalMs);
+    }
+    /**
+     * Get runtime statistics for all instructions
+     */
+    getMetrics() {
+        return this.instructions.map(instr => instr.runtimeStats || {
+            in: 0,
+            out: 0,
+            elapsedNs: 0n,
+            executions: 0
+        });
+    }
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/src/runtime/scheduler.js.map

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

package/dist/src/runtime/types.d.ts

@@ -0,0 +1,109 @@
+import type { RuntimeValue, SqlParameters, OutputValue, Row } from "../common/types.js";
+import type { Database } from "../core/database.js";
+import type { Statement } from "../core/statement.js";
+import type { RowDescriptor, RowGetter, TableDescriptor, TableGetter } from "../planner/nodes/plan-node.js";
+import type { Scheduler } from "./scheduler.js";
+import type { EmissionContext } from "./emission-context.js";
+import type { VirtualTableConnection } from "../vtab/connection.js";
+export type RuntimeContext = {
+    db: Database;
+    stmt: Statement | null;
+    params: SqlParameters;
+    /** Row contexts by row descriptor */
+    context: Map<RowDescriptor, RowGetter>;
+    /** Table contexts by table name, used for recursive CTEs or other temporary table situations */
+    tableContexts: Map<TableDescriptor, TableGetter>;
+    /** Debug tracer for instruction execution, if enabled */
+    tracer?: InstructionTracer;
+    /** Active connection for the current transaction context */
+    activeConnection?: VirtualTableConnection;
+    /** Whether to collect runtime execution metrics */
+    enableMetrics: boolean;
+};
+export type InstructionRun = (ctx: RuntimeContext, ...args: any[]) => OutputValue;
+export type Instruction = {
+    params: Instruction[];
+    run: InstructionRun;
+    /** Optional human-readable note about what this instruction does */
+    note?: string;
+    /** Optional sub-programs used to execute this instruction - this is here for tracing purposes */
+    programs?: Scheduler[];
+    /** Optional emission context for schema validation */
+    emissionContext?: EmissionContext;
+    /** Optional runtime statistics collected during execution */
+    runtimeStats?: InstructionRuntimeStats;
+};
+/**
+ * Runtime statistics for instruction execution
+ */
+export interface InstructionRuntimeStats {
+    /** Number of input values/rows processed */
+    in: number;
+    /** Number of output values/rows produced */
+    out: number;
+    /** Total execution time in nanoseconds */
+    elapsedNs: bigint;
+    /** Number of times this instruction was executed */
+    executions: number;
+}
+/** * Trace event for instruction execution. */
+export interface InstructionTraceEvent {
+    instructionIndex: number;
+    note?: string;
+    type: 'input' | 'output' | 'row' | 'error';
+    timestamp: number;
+    args?: RuntimeValue[];
+    result?: OutputValue;
+    error?: string;
+    /** Information about sub-programs if this instruction has any */
+    subPrograms?: SubProgramInfo[];
+    /** Row index within the async iterable (for 'row' type events) */
+    rowIndex?: number;
+    /** Row data (for 'row' type events) */
+    row?: Row;
+}
+/** Information about a sub-program for tracing purposes */
+export interface SubProgramInfo {
+    programIndex: number;
+    instructionCount: number;
+    rootNote?: string;
+}
+/** * Interface for tracing instruction execution. */
+export interface InstructionTracer {
+    /** Called before an instruction executes */
+    traceInput(instructionIndex: number, instruction: Instruction, args: RuntimeValue[]): void;
+    /** Called after an instruction executes */
+    traceOutput(instructionIndex: number, instruction: Instruction, result: OutputValue): void;
+    /** Called when an instruction throws an error */
+    traceError(instructionIndex: number, instruction: Instruction, error: Error): void;
+    /** Called for each row emitted by an async iterable instruction */
+    traceRow(instructionIndex: number, instruction: Instruction, rowIndex: number, row: Row): void;
+    /** Gets collected trace events (if supported by the tracer) */
+    getTraceEvents?(): InstructionTraceEvent[];
+    /** Gets information about all sub-programs encountered during tracing */
+    getSubPrograms?(): Map<number, {
+        scheduler: Scheduler;
+        parentInstructionIndex: number;
+    }>;
+}
+/** * Tracer that collects execution events for later analysis. */
+export declare class CollectingInstructionTracer implements InstructionTracer {
+    private events;
+    private subPrograms;
+    private nextSubProgramId;
+    traceInput(instructionIndex: number, instruction: Instruction, args: RuntimeValue[]): void;
+    traceOutput(instructionIndex: number, instruction: Instruction, result: OutputValue): void;
+    traceError(instructionIndex: number, instruction: Instruction, error: Error): void;
+    traceRow(instructionIndex: number, instruction: Instruction, rowIndex: number, row: Row): void;
+    getTraceEvents(): InstructionTraceEvent[];
+    getSubPrograms(): Map<number, {
+        scheduler: Scheduler;
+        parentInstructionIndex: number;
+    }>;
+    clear(): void;
+    private collectSubProgramInfo;
+    private cloneArgs;
+    private cloneResult;
+    private cloneValue;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/runtime/types.d.ts.map

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

package/dist/src/runtime/types.js

@@ -0,0 +1,90 @@
+/** * Tracer that collects execution events for later analysis. */
+export class CollectingInstructionTracer {
+    events = [];
+    subPrograms = new Map();
+    nextSubProgramId = 0;
+    traceInput(instructionIndex, instruction, args) {
+        const subPrograms = this.collectSubProgramInfo(instructionIndex, instruction);
+        this.events.push({
+            instructionIndex,
+            note: instruction.note,
+            type: 'input',
+            timestamp: Date.now(),
+            args: this.cloneArgs(args),
+            subPrograms
+        });
+    }
+    traceOutput(instructionIndex, instruction, result) {
+        this.events.push({
+            instructionIndex,
+            note: instruction.note,
+            type: 'output',
+            timestamp: Date.now(),
+            result: this.cloneResult(result)
+        });
+    }
+    traceError(instructionIndex, instruction, error) {
+        this.events.push({
+            instructionIndex,
+            note: instruction.note,
+            type: 'error',
+            timestamp: Date.now(),
+            error: error.message
+        });
+    }
+    traceRow(instructionIndex, instruction, rowIndex, row) {
+        this.events.push({
+            instructionIndex,
+            note: instruction.note,
+            type: 'row',
+            timestamp: Date.now(),
+            rowIndex,
+            row
+        });
+    }
+    getTraceEvents() {
+        return [...this.events];
+    }
+    getSubPrograms() {
+        return new Map(this.subPrograms);
+    }
+    clear() {
+        this.events = [];
+        this.subPrograms.clear();
+        this.nextSubProgramId = 0;
+    }
+    collectSubProgramInfo(instructionIndex, instruction) {
+        if (!instruction.programs || instruction.programs.length === 0) {
+            return undefined;
+        }
+        return instruction.programs.map(scheduler => {
+            const programId = this.nextSubProgramId++;
+            this.subPrograms.set(programId, { scheduler, parentInstructionIndex: instructionIndex });
+            return {
+                programIndex: programId,
+                instructionCount: scheduler.instructions.length,
+                rootNote: scheduler.instructions[scheduler.instructions.length - 1]?.note
+            };
+        });
+    }
+    cloneArgs(args) {
+        return args.map(arg => this.cloneValue(arg));
+    }
+    cloneResult(result) {
+        return this.cloneValue(result);
+    }
+    cloneValue(value) {
+        if (value === null || value === undefined)
+            return value;
+        if (typeof value === 'function')
+            return '[Function]';
+        if (typeof value === 'object' && Symbol.asyncIterator in value)
+            return '[AsyncIterable]';
+        if (Array.isArray(value))
+            return value.map(v => this.cloneValue(v));
+        if (typeof value === 'object')
+            return '[Object]';
+        return value;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/src/runtime/types.js.map

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

package/dist/src/runtime/utils.d.ts

@@ -0,0 +1,32 @@
+import type { TableSchema } from '../schema/table.js';
+import type { VirtualTable } from '../vtab/table.js';
+import type { RuntimeContext } from './types.js';
+import type { VirtualTableConnection } from '../vtab/connection.js';
+import type { RowDescriptor } from '../planner/nodes/plan-node.js';
+export declare const ctxLog: import("debug").Debugger;
+export declare function isAsyncIterable<T>(value: unknown): value is AsyncIterable<T>;
+export declare function asyncIterableToArray<T>(iterable: AsyncIterable<T>): Promise<T[]>;
+/**
+ * Helper to get or create a VirtualTable connection for a given table.
+ * This ensures transaction consistency by reusing connections within the same context.
+ */
+export declare function getVTableConnection(ctx: RuntimeContext, tableSchema: TableSchema): Promise<VirtualTableConnection>;
+/**
+ * Helper to get the VirtualTable instance for a given TableReferenceNode.
+ * This is the legacy method that creates ephemeral instances.
+ * When reusing connections, this will also inject the existing connection into the VirtualTable.
+ */
+export declare function getVTable(ctx: RuntimeContext, tableSchema: TableSchema): Promise<VirtualTable>;
+/**
+ * Helper to properly disconnect and unregister a VirtualTable instance.
+ */
+export declare function disconnectVTable(ctx: RuntimeContext, vtab: VirtualTable): Promise<void>;
+/**
+ * Helper function to log context push operations
+ */
+export declare function logContextPush(descriptor: RowDescriptor, note: string, attributes?: any[]): void;
+/**
+ * Helper function to log context pop operations
+ */
+export declare function logContextPop(descriptor: RowDescriptor, note: string): void;
+//# sourceMappingURL=utils.d.ts.map

package/dist/src/runtime/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/runtime/utils.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAIpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAInE,eAAO,MAAM,MAAM,0BAAkC,CAAC;AAEtD,wBAAgB,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAAC,CAAC,CAAC,CAE5E;AAED,wBAAsB,oBAAoB,CAAC,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAMtF;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAuCxH;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CA6BpG;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAO7F;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,GAAG,EAAE,QAIzF;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,QAGpE"}