semanticdb-v2 2.0.0-alpha.11 → 2.0.0-alpha.12

package/dist/operators/types.d.ts

@@ -1,12 +1,33 @@
-import type { PrimalType, ResolvedSemanticProperty, ResolvedSemanticSchema, TimeGranularity, ComparableCategoryDefinition } from '../semantic-types/index';
+import type { PrimalType, ResolvedSemanticProperty, ResolvedSemanticSchema, TimeGranularity, ComparableCategoryDefinition, SemanticTypeRegistry } from '../semantic-types/index';
 import type { LogicformType, PredItemType, QueryType } from '../logicform-types';
 import type { DataRow } from '../physical/index';
 import type { Expression, LogicalPlan } from '../planner/index';
 import type { LocaleTranslate } from '../i18n/index';
+import type dayjs from 'dayjs';
+/** One unambiguous, inclusive date interval in the main query. */
+export interface ResolvedTimeRange {
+    readonly schemaId: string;
+    readonly propertyId: string;
+    readonly queryPath: readonly (string | number)[];
+    /** Expanded question interval, before applying the time watermark. */
+    readonly requestedRange: {
+        readonly start: string;
+        readonly end: string;
+    };
+    /** Interval used by the normalized data query. */
+    readonly effectiveRange: {
+        readonly start: string;
+        readonly end: string;
+    };
+    /** Resolved watermark, not necessarily the raw database maximum. */
+    readonly timeWatermark?: string;
+}
 /** Immutable data shared by all Operator hooks during one LogicForm execution. */
 export interface OperatorExecutionContext {
     /** Complete rows from the unique Schema marked with `is_calendar`. */
     readonly calendar?: readonly Readonly<DataRow>[];
+    /** Available after main-query normalization; child queries do not replace it. */
+    readonly timeRange?: ResolvedTimeRange;
 }
 interface OperatorHookContext {
     /** Always supplied by the executor; optional for direct unit-level hook invocation. */
@@ -44,16 +65,13 @@ export interface OperatorSqlContext extends OperatorHookContext {
     /** Operator-specific LogicForm arguments. */
     readonly args: Readonly<Record<string, unknown>>;
 }
-/** Context passed to an operator evaluated after the provider returns rows. */
-export interface OperatorEvaluateContext extends OperatorHookContext {
-    /** Value produced by the nested expression, or undefined for a propertyless operator. */
-    readonly input: unknown;
-    /** Operator-specific LogicForm arguments. */
-    readonly args: Readonly<Record<string, unknown>>;
-}
 /** A logical output column produced by one LogicForm projection. */
 export interface ResultProperty {
     readonly name: string;
+    /** Ordered child metric properties; names match the exposed component value keys. */
+    readonly componentProperties?: readonly ResultProperty[];
+    /** Readable calculation using logical property names; excludes query/groupby context. */
+    readonly formulaText?: string | null;
     readonly type: string;
     readonly primal_type: PrimalType;
     readonly isArray: boolean;
@@ -92,6 +110,8 @@ export type ResultPropertyTemporalMetadata = {
     }[];
 } | ResultPropertyTemporalMetadataExtensions[keyof ResultPropertyTemporalMetadataExtensions];
 export interface OperatorOutputPropertyContext extends OperatorHookContext {
+    /** Registry for resolving output semantic types, including application-defined types. */
+    readonly semanticTypes?: SemanticTypeRegistry;
     /** Final alias assigned to this operator's single output column. */
     readonly name: string;
     /** Original Schema property when the operator starts from a physical property. */
@@ -110,6 +130,49 @@ export interface OperatorPeriodEvaluationContext extends OperatorHookContext {
     readonly schema: ResolvedSemanticSchema;
     readonly inputProperty?: ResolvedSemanticProperty;
 }
+/** Helpers supplied to a runtime metric during one execution. */
+export interface OperatorRuntimeConfig {
+    readonly result_only: true;
+    /** The current metric projection. */
+    readonly pred: PredItemType;
+    readonly name?: string;
+    readonly args?: Readonly<Record<string, unknown>>;
+    readonly locale: string;
+    readonly signal?: AbortSignal;
+    readonly [key: string]: unknown;
+}
+export interface OperatorRuntimeExecute {
+    (logicform: LogicformType, config: {
+        readonly result_only: true;
+    }): Promise<DataRow[]>;
+    (logicform: LogicformType, config?: {
+        readonly result_only?: false;
+    }): Promise<{
+        readonly result: readonly Readonly<DataRow>[];
+        readonly total?: number;
+    }>;
+}
+export interface OperatorRuntimeHelpers {
+    readonly execute: OperatorRuntimeExecute;
+    /** Merge arrays by `_id`, preserving first-seen order; later columns win. */
+    readonly mergeByID: (results: readonly (readonly Readonly<DataRow>[])[]) => DataRow[];
+    readonly config: OperatorRuntimeConfig;
+    readonly schemas: Readonly<Record<string, ResolvedSemanticSchema>>;
+    readonly getSchema: (schemaId: string) => ResolvedSemanticSchema;
+    readonly getProperty: (schemaId: string, property: string) => ResolvedSemanticProperty;
+    readonly signal?: AbortSignal;
+    readonly locale: string;
+    readonly now: Date;
+    readonly log: (...values: unknown[]) => void;
+    readonly md5: (value: string) => string;
+    readonly fetch: typeof globalThis.fetch;
+    readonly dayjs: typeof dayjs;
+    /** Compatibility alias; this is dayjs, not the Moment.js package. */
+    readonly moment: typeof dayjs;
+    readonly [key: string]: unknown;
+}
+export type OperatorRuntimeValue = unknown;
+export type OperatorRuntimeRun = (logicform: LogicformType, schema: ResolvedSemanticSchema, config: OperatorRuntimeConfig, helpers: OperatorRuntimeHelpers) => OperatorRuntimeValue;
 export interface OperatorDefaultNameContext extends OperatorHookContext {
     /** Name produced by the direct pred inputs or localized row label. */
     readonly operandName: string;
@@ -174,6 +237,9 @@ export interface OperatorRewriteLogicformContext extends OperatorHookContext {
     readonly getOperator?: (name: string) => OperatorDefinition;
 }
 export interface OperatorComponentContext extends OperatorHookContext {
+    readonly dayjs: typeof dayjs;
+    /** Compatibility alias; this is dayjs, not the Moment.js package. */
+    readonly moment: typeof dayjs;
     /** Normalized input LogicForm; having, sort, limit, limitBy, and page stay on the merged result. */
     readonly logicform: LogicformType;
     /** Caller-authored normalized input before executor row policies, with result operations removed. */
@@ -199,6 +265,8 @@ export interface OperatorQueryComponent {
     readonly kind: 'query';
     /** Internal LogicForm executed by the normal planner/compiler/provider pipeline. */
     readonly logicform: LogicformType;
+    /** Original projections whose semantic policies apply to the generated metric expressions. */
+    readonly semanticPreds?: readonly PredItemType[];
     /** Apply permissions and normalize this dynamically generated LogicForm before planning. */
     readonly prepare?: boolean;
     /** Optional result-key mapping used before component rows are merged. */
@@ -214,6 +282,7 @@ export interface OperatorComponentQuery {
     /** Final result-column name for this child component. */
     readonly name: string;
     readonly logicform: LogicformType;
+    readonly literal?: never;
     readonly prepare?: boolean;
     readonly mapResult?: (rows: readonly DataRow[]) => DataRow[];
     readonly groupKeyShifts?: readonly OperatorGroupKeyShift[];
@@ -226,22 +295,37 @@ export interface OperatorComponentQuery {
      */
     readonly joinKeys?: readonly string[];
 }
+/** A precomputed finite numeric value, broadcast to every result group. */
+export interface OperatorComponentLiteral {
+    readonly name: string;
+    readonly literal: number;
+    readonly logicform?: never;
+}
+export type OperatorComponentInput = OperatorComponentQuery | OperatorComponentLiteral;
 export interface OperatorComponentCalculation {
-    readonly components: readonly OperatorComponentQuery[];
-    /** Provider-independent formula referring to component names. */
+    readonly components: readonly OperatorComponentInput[];
+    /** Provider-independent formula referring to component names; also exposed verbatim as result formulaText. */
     readonly expression: string;
 }
 export interface OperatorJavaScriptCalculation {
     readonly kind: 'js';
-    readonly components: readonly OperatorComponentQuery[];
+    readonly components: readonly OperatorComponentInput[];
     readonly mergeRow: (values: DataRow) => unknown;
 }
 export type OperatorExecutionComponent = OperatorQueryComponent | OperatorComponentCalculation | OperatorJavaScriptCalculation;
+export interface OperatorFormulaTextContext extends OperatorHookContext {
+    readonly schema: ResolvedSemanticSchema;
+    /** Recursively expanded single-input formula, independent of its output alias. */
+    readonly input?: string;
+    /** Recursively expanded multi-input formulas, in operand order. */
+    readonly inputs: readonly string[];
+    readonly args: Readonly<Record<string, unknown>>;
+}
 /**
  * Extension contract for one LogicForm operator.
  *
  * `kind` is the semantic category used by planning and execution. Its variant
- * requires the corresponding SQL, JavaScript, window, or component contract.
+ * requires the corresponding SQL, window, or component contract.
  * The planner recursively connects nested `pred` expressions and uses
  * `getOutputProperty` to describe the resulting one-column logical schema.
  */
@@ -252,6 +336,8 @@ interface OperatorDefinitionBase {
     readonly description?: string;
     /** Produce the normalized output name when the PredItem does not declare one. */
     readonly defaultName: (context: OperatorDefaultNameContext) => string;
+    /** Describe the calculation independently of the generated or authored output name. */
+    readonly getFormulaText?: (context: OperatorFormulaTextContext) => string;
     /** Translation key for the generated name. Defaults to `operator.${name}`. */
     readonly defaultNameKey?: string | ((context: OperatorDefaultNameContext) => string);
     /** defaultName already used the translator and must not be translated a second time. */
@@ -295,43 +381,40 @@ interface OperatorDefinitionBase {
 export type OperatorWindowFunction = 'rank' | 'rowNumber';
 export type OperatorDefinition = OperatorDefinitionBase & ({
     readonly kind: 'scalar';
+    /** Isolate a non-empty pred.query before computing this expression. */
+    readonly createQueryComponent?: (context: OperatorComponentContext) => OperatorQueryComponent;
     /** Convert the operator and its input expression into SQL. */
     readonly toSQL: (context: OperatorSqlContext) => string;
-    readonly evaluate?: (context: OperatorEvaluateContext) => unknown;
-    readonly createComponent?: never;
-    readonly windowFunction?: never;
-} | {
-    readonly kind: 'scalar';
-    readonly toSQL?: (context: OperatorSqlContext) => string;
-    /** JavaScript evaluator for this operator. */
-    readonly evaluate: (context: OperatorEvaluateContext) => unknown;
     readonly createComponent?: never;
     readonly windowFunction?: never;
 } | {
     readonly kind: 'aggregate';
     readonly toSQL: (context: OperatorSqlContext) => string;
-    readonly evaluate?: (context: OperatorEvaluateContext) => unknown;
     readonly createComponent?: never;
     readonly windowFunction?: never;
 } | {
     readonly kind: 'component';
     readonly toSQL?: never;
-    readonly evaluate?: never;
     readonly createComponent: (context: OperatorComponentContext) => OperatorExecutionComponent;
     readonly windowFunction?: never;
 } | {
     readonly kind: 'window';
     readonly toSQL?: never;
-    readonly evaluate?: never;
     readonly createComponent?: never;
     /** Plan this operator as a SQL window expression. */
     readonly windowFunction: OperatorWindowFunction;
 } | {
     readonly kind: 'logical';
     readonly toSQL?: never;
-    readonly evaluate?: never;
     readonly createComponent?: never;
     readonly windowFunction?: never;
     readonly planExpression: (context: OperatorPlanExpressionContext) => Expression;
+} | {
+    readonly kind: 'runtime';
+    readonly toSQL?: never;
+    readonly createComponent?: never;
+    readonly windowFunction?: never;
+    /** Evaluate a metric using application services and return a scalar or result rows. */
+    readonly run: OperatorRuntimeRun;
 });
 export {};

package/dist/permissions/index.d.ts

@@ -1,3 +1,4 @@
 export { applyPermissions, assertLogicformAllowed, getSchemaPermissions, isColumnAllowed, validatePermissions, } from './permissions';
 export type { PermissionSchemaResolver, } from './permissions';
-export type { ColumnPermissions, Permissions, SchemaPermissions, } from './types';
+export type { ColumnPermissions, MetricPermissions, Permissions, SchemaPermissions, } from './types';
+export { assertMetricCallsAllowed, validateSchemaMetricPermissions } from './metric-permissions';

package/dist/permissions/metric-permissions.d.ts

@@ -0,0 +1,9 @@
+import { type LogicformType } from '../logicform-types';
+import type { OperatorRegistry } from '../operators/index';
+import type { ResolvedSemanticSchema } from '../semantic-types/index';
+import type { PermissionSchemaResolver } from './permissions';
+import type { Permissions } from './types';
+/** Validate only a Schema reached by this execution; registry membership alone is insufficient. */
+export declare const validateSchemaMetricPermissions: (schema: ResolvedSemanticSchema, permissions: Permissions | undefined, operators: OperatorRegistry) => void;
+/** Check caller expressions before rewrites, and generated expressions before compilation. */
+export declare const assertMetricCallsAllowed: (form: LogicformType, permissions: Permissions | undefined, resolveSchema: PermissionSchemaResolver, operators: OperatorRegistry) => void;

package/dist/permissions/permissions.d.ts

@@ -1,10 +1,11 @@
 import type { LogicformType } from '../logicform-types';
 import type { ResolvedSemanticProperty, ResolvedSemanticSchema } from '../semantic-types/index';
+import type { OperatorRegistry } from '../operators/index';
 import type { Permissions, SchemaPermissions } from './types';
 import type { SemanticDBPlugin } from '../plugins/index';
 export type PermissionSchemaResolver = (schemaId: string) => ResolvedSemanticSchema;
 export declare const getSchemaPermissions: (permissions: Permissions | undefined, schemaId: string) => SchemaPermissions | undefined;
 export declare const isColumnAllowed: (permissions: Permissions | undefined, schemaId: string, property: Pick<ResolvedSemanticProperty, "id" | "name">) => boolean;
-export declare const assertLogicformAllowed: (logicform: LogicformType, permissions: Permissions | undefined, resolveSchema: PermissionSchemaResolver, plugins?: readonly SemanticDBPlugin[]) => void;
-export declare const applyPermissions: (logicform: LogicformType, permissions: Permissions | undefined, resolveSchema: PermissionSchemaResolver, authorize?: boolean, appliedSchemas?: ReadonlySet<string>, plugins?: readonly SemanticDBPlugin[]) => LogicformType;
-export declare const validatePermissions: (permissions: Permissions | undefined, resolveSchema: PermissionSchemaResolver) => void;
+export declare const assertLogicformAllowed: (logicform: LogicformType, permissions: Permissions | undefined, resolveSchema: PermissionSchemaResolver, plugins?: readonly SemanticDBPlugin[], trustedQueries?: ReadonlyMap<string, ReadonlySet<string>>) => void;
+export declare const applyPermissions: (logicform: LogicformType, permissions: Permissions | undefined, resolveSchema: PermissionSchemaResolver, authorize?: boolean, appliedSchemas?: ReadonlySet<string>, plugins?: readonly SemanticDBPlugin[], operators?: OperatorRegistry) => LogicformType;
+export declare const validatePermissions: (permissions: Permissions | undefined, resolveSchema: PermissionSchemaResolver, schemaIds?: Iterable<string>) => void;

package/dist/permissions/types.d.ts

@@ -2,7 +2,12 @@ import type { QueryType } from '../logicform-types';
 export interface ColumnPermissions {
     readonly whitelist: readonly string[];
 }
+/** Omitted: unrestricted for compatibility. []: deny all. '*': all Schema metrics. */
+export interface MetricPermissions {
+    readonly whitelist: readonly string[] | '*';
+}
 export interface SchemaPermissions {
+    readonly metricPermissions?: MetricPermissions;
     readonly rowPermissions?: QueryType;
     readonly columnPermissions?: ColumnPermissions;
 }

package/dist/physical/connection.d.ts

@@ -1,3 +1,4 @@
+import type { DuckDBConnectionOptions } from './duckdb-provider';
 import type { CoreComputeProvider } from './provider';
 import type { ClickHouseProviderOptions } from './clickhouse-provider';
 import type { DatabricksConnectionOptions } from './databricks-provider';
@@ -19,6 +20,9 @@ export interface DatabaseConnectionBase {
 export interface DatabaseConnectionExtensions {
 }
 export type BuiltinDatabaseConnection = ({
+    readonly id: string;
+    readonly kind: 'duckdb';
+} & DuckDBConnectionOptions) | ({
     readonly id: string;
     readonly kind: 'mysql';
 } & MySQLConnectionOptions) | ({

package/dist/physical/db-connector.d.ts

@@ -1,3 +1,5 @@
+import type { ReadImportFileOptions, ReadImportFileResult } from '../file-import/index';
+import type { ImportRowsRequest, ImportRowsResult } from './import-types';
 import type { DatabaseConnection, ProviderRegistry } from './connection';
 import type { DatabaseTable, SQLResult, SqlParameters, TableListRequest, DescribeTableRequest, TableDescription } from './provider';
 export interface DBConnectorOptions {
@@ -14,10 +16,18 @@ export interface GetTableListOptions extends DBConnectorOptions, TableListReques
 }
 export interface DescribeTableOptions extends DBConnectorOptions, DescribeTableRequest {
 }
+export interface ImportFileOptions extends DBConnectorOptions, ReadImportFileOptions, Omit<ImportRowsRequest, 'rows'> {
+}
+export interface ImportFileResult extends ImportRowsResult {
+    readonly format: ReadImportFileResult['format'];
+    readonly encoding?: ReadImportFileResult['encoding'];
+    readonly sheet?: string;
+}
 /** Trusted physical operations; no LogicForm permissions, rewriting, or caching. */
 export declare const DBConnector: Readonly<{
     runSQL: (options: RunSQLOptions) => Promise<SQLResult>;
     getTableList: (options: GetTableListOptions) => Promise<DatabaseTable[]>;
     describeTable: (options: DescribeTableOptions) => Promise<TableDescription>;
+    importFile: (options: ImportFileOptions) => Promise<ImportFileResult>;
     close: () => Promise<void>;
 }>;

package/dist/physical/duckdb-coordinator-provider.d.ts

@@ -1,36 +1,16 @@
-import type { CoreComputeProvider, DataRow, DatePart, ProviderExecutionRequest } from './provider';
+import { DuckDBSql } from './duckdb-sql';
+import type { CoreComputeProvider, DataRow, ProviderExecutionRequest } from './provider';
 export type DuckDBCoordinatorColumnKind = 'boolean' | 'date' | 'number' | 'string';
 export interface DuckDBCoordinatorColumn {
     readonly name: string;
     readonly kind: DuckDBCoordinatorColumnKind;
 }
 /** In-process SQL engine used only to combine results from separate physical connections. */
-export declare class DuckDBCoordinatorProvider implements CoreComputeProvider {
+export declare class DuckDBCoordinatorProvider extends DuckDBSql implements CoreComputeProvider {
     private readonly instance;
     private readonly connection;
-    readonly kind: "duckdb";
-    readonly supportsHavingAlias = true;
-    readonly supportsRecursiveCte = true;
     static create(): Promise<DuckDBCoordinatorProvider>;
     private constructor();
-    quoteIdentifier(identifier: string): string;
-    tableAlias(expression: string, alias: string): string;
-    paginate(sql: string, pageSize: number, offset: number): string;
-    parameter(index: number, value: unknown): string;
-    displayQuery(sql: string, parameters: readonly unknown[]): string;
-    dateBucket(expression: string, level: string): string;
-    datePart(expression: string, part: DatePart): string;
-    dateShift(expression: string, granularity: string, offset: number): string;
-    datePeriodBoundary(expression: string, granularity: string, boundary: 'start' | 'end'): string;
-    castValue(expression: string, type: string): string;
-    scalarExtremum(operator: 'least' | 'greatest', expressions: readonly string[]): string;
-    aggregateFunction(name: string, expression?: string): string;
-    stringify(expression: string): string;
-    concat(expressions: readonly string[]): string;
-    substring(expression: string, start: number, length: number): string;
-    stringLength(expression: string): string;
-    regex(expression: string, pattern: string, options?: string): string;
-    arrayContains(arrayExpression: string, valueExpression: string): string;
     materialize(tableName: string, inputColumns: readonly DuckDBCoordinatorColumn[], rows: readonly DataRow[]): Promise<void>;
     execute(request: ProviderExecutionRequest): Promise<DataRow[]>;
     close(): Promise<void>;

package/dist/physical/duckdb-dataset.d.ts

@@ -0,0 +1,23 @@
+import type { DuckDBConnection } from '@duckdb/node-api';
+import type { ImportColumn, ImportRowsRequest, ImportRowsResult } from './import-types';
+interface DatasetBatch {
+    readonly id: string;
+    readonly file: string;
+    readonly hash: string;
+    readonly rowCount: number;
+}
+interface DatasetTable {
+    readonly name: string;
+    readonly columns: readonly ImportColumn[];
+    readonly batches: readonly DatasetBatch[];
+}
+export interface DatasetManifest {
+    readonly format: 1;
+    readonly version: string;
+    readonly tables: readonly DatasetTable[];
+}
+/** Readers load one atomically published manifest; old batch files stay readable. */
+export declare const readDatasetManifest: (directory: string) => Promise<DatasetManifest>;
+export declare const registerDatasetViews: (connection: DuckDBConnection, directory: string, manifest: DatasetManifest) => Promise<void>;
+export declare const importDatasetRows: (directory: string, request: ImportRowsRequest, lockTimeoutMs: number) => Promise<ImportRowsResult>;
+export {};

package/dist/physical/duckdb-provider.d.ts

@@ -0,0 +1,26 @@
+import { DuckDBSql } from './duckdb-sql';
+import type { ImportRowsRequest, ImportRowsResult } from './import-types';
+import type { CoreComputeProvider, DataRow, DatabaseTable, DescribeTableRequest, ProviderExecutionRequest, SQLResult, TableDescription, TableListRequest } from './provider';
+export type DuckDBConnectionOptions = {
+    readonly path: string;
+    readonly readOnly?: boolean;
+    readonly directory?: never;
+    readonly lockTimeoutMs?: never;
+} | {
+    readonly directory: string;
+    readonly lockTimeoutMs?: number;
+    readonly path?: never;
+    readonly readOnly?: never;
+};
+/** A customer-owned DuckDB file or a managed directory of published Parquet datasets. */
+export declare class DuckDBProvider extends DuckDBSql implements CoreComputeProvider {
+    #private;
+    constructor(options: DuckDBConnectionOptions);
+    getDataVersion(): Promise<string | undefined>;
+    importRows(request: ImportRowsRequest): Promise<ImportRowsResult>;
+    execute(request: ProviderExecutionRequest): Promise<DataRow[]>;
+    runSQL(request: ProviderExecutionRequest): Promise<SQLResult>;
+    getTableList(request: TableListRequest): Promise<DatabaseTable[]>;
+    describeTable(request: DescribeTableRequest): Promise<TableDescription>;
+    close(): Promise<void>;
+}

package/dist/physical/duckdb-sql.d.ts

@@ -0,0 +1,33 @@
+import type { DuckDBValue } from '@duckdb/node-api';
+import type { DatePart } from './provider';
+export declare const duckdbParameter: (value: unknown, label?: string) => DuckDBValue;
+export declare const duckdbLiteral: (value: string) => string;
+/** Shared dialect for physical DuckDB connections and the federated coordinator. */
+export declare class DuckDBSql {
+    readonly kind: "duckdb";
+    readonly supportsHavingAlias = true;
+    readonly supportsRecursiveCte = true;
+    quoteIdentifier(identifier: string): string;
+    tableAlias(expression: string, alias: string): string;
+    paginate(sql: string, pageSize: number, offset: number): string;
+    parameter(index: number, value: unknown): string;
+    displayQuery(sql: string, parameters: readonly unknown[]): string;
+    dateBucket(expression: string, level: string): string;
+    datePart(expression: string, part: DatePart): string;
+    dateShift(expression: string, granularity: string, offset: number): string;
+    datePeriodBoundary(expression: string, granularity: string, boundary: 'start' | 'end'): string;
+    castValue(expression: string, type: string): string;
+    scalarExtremum(operator: 'least' | 'greatest', expressions: readonly string[]): string;
+    aggregateFunction(name: string, expression?: string): string;
+    stringify(expression: string): string;
+    concat(expressions: readonly string[]): string;
+    substring(expression: string, start: number, length: number): string;
+    stringLength(expression: string): string;
+    regex(expression: string, pattern: string, options?: string): string;
+    arrayContains(arrayExpression: string, valueExpression: string): string;
+    normalizeStringArray(expression: string): string;
+    expandArray(arrayExpression: string, alias: string, column: string): {
+        joinSql: string;
+        valueExpression: string;
+    };
+}

package/dist/physical/import-types.d.ts

@@ -0,0 +1,23 @@
+import type { DataRow } from './provider';
+export interface ImportColumn {
+    readonly name: string;
+    readonly type: 'string' | 'number' | 'boolean' | 'date' | 'timestamp';
+    readonly nullable?: boolean;
+}
+/** Database-neutral write capability. Files are parsed before reaching a provider. */
+export interface ImportRowsRequest {
+    readonly table: string;
+    readonly columns: readonly ImportColumn[];
+    readonly rows: readonly DataRow[];
+    /** Stable caller-supplied identity, e.g. a business date. */
+    readonly batchId: string;
+    readonly mode?: 'append' | 'replace-batch' | 'replace';
+    readonly signal?: AbortSignal;
+}
+export interface ImportRowsResult {
+    readonly table: string;
+    readonly batchId: string;
+    readonly rowCount: number;
+    readonly version: string;
+    readonly status: 'imported' | 'unchanged';
+}

package/dist/physical/import-validation.d.ts

@@ -0,0 +1,14 @@
+import type { ImportColumn, ImportRowsRequest } from './import-types';
+import type { DataRow } from './provider';
+export declare const importSqlType: (type: ImportColumn["type"]) => string;
+export declare const validateImportColumns: (columns: unknown) => asserts columns is readonly ImportColumn[];
+export declare const normalizeImport: (request: ImportRowsRequest) => {
+    columns: {
+        name: string;
+        type: "string" | "number" | "boolean" | "date" | "timestamp";
+        nullable: boolean;
+    }[];
+    rows: DataRow[];
+    mode: "replace" | "append" | "replace-batch";
+    hash: string;
+};

package/dist/physical/index.d.ts

@@ -2,6 +2,10 @@
 export type { CoreComputeProvider, DatePart, DataRow, DatabaseTable, SQLResult, TableListRequest, DescribeTableRequest, DatabaseColumn, TableDescription, ProviderExecutionRequest, ProviderKind, ProviderKindExtensions, SqlRenderCapabilities, SqlParameters, } from './provider';
 export { ConnectionRegistry, getConnectionProvider, closeConnections } from './connection-registry';
 export { DBConnector } from './db-connector';
+export { DuckDBProvider } from './duckdb-provider';
+export type { DuckDBConnectionOptions } from './duckdb-provider';
+export type { ImportColumn, ImportRowsRequest, ImportRowsResult } from './import-types';
+export type { ImportFileOptions, ImportFileResult } from './db-connector';
 export type { DBConnectorOptions, RunSQLOptions, GetTableListOptions, DescribeTableOptions } from './db-connector';
 export { builtinProviderDefinitions, createProvider, defaultProviderRegistry, ProviderRegistry, } from './connection';
 export type { BuiltinDatabaseConnection, DatabaseConnection, DatabaseConnectionBase, DatabaseConnectionExtensions, ProviderDefinition, } from './connection';

package/dist/physical/postgresql-provider.d.ts

@@ -38,6 +38,7 @@ export declare class PostgreSQLProvider implements CoreComputeProvider {
     dateBucket(expression: string, level: string): string;
     datePart(expression: string, part: DatePart): string;
     dateShift(expression: string, granularity: string, offset: number): string;
+    castValue(expression: string, type: string): string;
     aggregateFunction(name: string, expression?: string): string;
     stringify(expression: string): string;
     concat(expressions: readonly string[]): string;

package/dist/physical/provider.d.ts

@@ -1,3 +1,4 @@
+import type { ImportRowsRequest, ImportRowsResult } from './import-types';
 export type DataRow = Record<string, unknown>;
 export type SqlParameters = readonly unknown[];
 export type DatePart = 'second' | 'minute' | 'hour' | 'weekday' | 'day' | 'week' | 'month' | 'quarter' | 'year';
@@ -100,5 +101,8 @@ export interface CoreComputeProvider extends SqlRenderCapabilities {
     /** Optional physical metadata capability, independent of semantic Schemas. */
     getTableList?(request: TableListRequest): Promise<DatabaseTable[]>;
     describeTable?(request: DescribeTableRequest): Promise<TableDescription>;
+    importRows?(request: ImportRowsRequest): Promise<ImportRowsResult>;
+    /** Published dataset revision, used to isolate cached queries across imports. */
+    getDataVersion?(): Promise<string | undefined>;
     close(): Promise<void>;
 }

package/dist/planner/build-lineage.d.ts

@@ -2,4 +2,4 @@ import type { OperatorRegistry } from '../operators/index';
 import type { CoreComputeProvider } from '../physical/index';
 import type { ResolvedSemanticSchema } from '../semantic-types/index';
 import type { LogicalPlan, QueryLineage } from './types';
-export declare const buildLineage: (plan: LogicalPlan, schema: ResolvedSemanticSchema, provider: CoreComputeProvider, operators?: OperatorRegistry, providerForConnection?: (connectionId: string) => CoreComputeProvider) => QueryLineage;
+export declare const buildLineage: (plan: LogicalPlan, schema: ResolvedSemanticSchema, provider: CoreComputeProvider, operators?: OperatorRegistry, providerForConnection?: (connectionId: string) => CoreComputeProvider, resolveSchema?: (schemaId: string) => ResolvedSemanticSchema) => QueryLineage;

package/dist/planner/create-logical-plan.d.ts

@@ -1,15 +1,24 @@
-import type { LogicformType } from '../logicform-types';
+import type { LogicformType, PredItemType } from '../logicform-types';
 import type { OperatorRegistry } from '../operators/index';
 import { SchemaMappingRegistry } from '../schema-mappings/index';
 import type { SchemaMappingSelection } from '../schema-mappings/index';
 import type { SemanticDBPlugin } from '../plugins/index';
-import type { ResolvedSemanticSchema } from '../semantic-types/index';
+import type { ResolvedSemanticSchema, SemanticTypeRegistry } from '../semantic-types/index';
 import type { ResolvedSemanticProperty } from '../semantic-types/index';
+import type { ResultProperty } from '../operators/index';
 import { type PlannerSemanticRegistry } from './semantics/index';
 import type { LogicalPlan } from './types';
+export declare const createResultProperty: (property: ResultProperty) => ResolvedSemanticProperty;
 export declare const createResultSchema: (plan: LogicalPlan, sourceSchema: ResolvedSemanticSchema) => ResolvedSemanticSchema;
 export declare const createDerivedSourceSchema: (sourcePlan: LogicalPlan, outerSchema: ResolvedSemanticSchema) => ResolvedSemanticSchema;
 export interface CreateLogicalPlanOptions {
+    /** Executor authorization for each form, including forms introduced by operator rewrites. */
+    readonly authorizeLogicform?: (logicform: LogicformType) => void;
+    readonly semanticTypes?: SemanticTypeRegistry;
+    /** Authorize logical inputs introduced by Mapping computations. */
+    readonly authorizeComputationInput?: (schema: ResolvedSemanticSchema, reference: string) => void;
+    /** Original semantic projections for this generated query only, aligned with its preds. */
+    readonly semanticPreds?: readonly PredItemType[];
     /** Normalized nested LogicForms whose asynchronous partition plans were prepared by the executor. */
     readonly preplannedPartitions?: ReadonlyMap<string, LogicalPlan>;
     /** Restrict the root physical Schema to one candidate during partition planning. */

package/dist/planner/index.d.ts

@@ -1,9 +1,10 @@
 export { buildLineage } from './build-lineage';
-export { createDerivedSourceSchema, createLogicalPlan, createResultSchema } from './create-logical-plan';
+export { createDerivedSourceSchema, createLogicalPlan, createResultProperty, createResultSchema } from './create-logical-plan';
 export type { CreateLogicalPlanOptions } from './create-logical-plan';
-export type { Expression, ArrayExpansionPlan, EnrichmentJoinPlan, FieldReferencePlan, GroupLimitPlan, JoinPlan, LogicalQuerySubquery, LogicalQueryOperator, LogicalOrdinalQuery, LogicalExpressionQuery, LineageColumnSource, LineageOutput, LogicalPlan, OrderPlan, PaginationPlan, ProjectionPlan, QueryLineage, RowIdentityPlan, PeriodSourcePlan, TemporalJoinConditionPlan, } from './types';
+export type { Expression, ArrayExpansionPlan, EnrichmentJoinPlan, FieldReferencePlan, GroupLimitPlan, JoinPlan, LogicalQuerySubquery, LogicalOutputReference, LogicalQueryOperator, LogicalOrdinalQuery, LogicalExpressionQuery, LineageColumnSource, LineageOutput, LogicalPlan, OrderPlan, PaginationPlan, PhysicalQueryFilterPlan, ProjectionPlan, QueryLineage, RowIdentityPlan, PeriodSourcePlan, TemporalJoinConditionPlan, } from './types';
 export { isLogicalQuerySubquery, isLogicalQueryOperator } from './types';
 export { isLogicalOrdinalQuery } from './types';
 export { isLogicalExpressionQuery } from './types';
+export { isLogicalOutputReference } from './types';
 export * from './semantics/index';
 export { createPlannerSemanticRegistry } from './semantics/registry-defaults';

package/dist/planner/mapping-granularity.d.ts

@@ -3,5 +3,5 @@ import type { SemanticDBPlugin } from '../plugins/index';
 import { type OperatorRegistry } from '../operators/index';
 import { type SchemaMappingDefinition } from '../schema-mappings/index';
 import type { ResolvedSemanticSchema } from '../semantic-types/index';
-/** Checks grouped-source Property coverage and delegates plugin-owned physical grains. */
+/** Checks physical-grain Property coverage and delegates plugin-owned grains. */
 export declare const mappingGranularityReason: (logicform: LogicformType, schema: ResolvedSemanticSchema, mapping: SchemaMappingDefinition, resolveSchema?: (schemaId: string) => ResolvedSemanticSchema, plugins?: readonly SemanticDBPlugin[], operators?: OperatorRegistry) => string | undefined;

package/dist/planner/materialize-computations.d.ts

@@ -0,0 +1,3 @@
+import type { LogicalPlan } from './types';
+/** Isolate row computations from aggregate/query scopes, without SQL-text pruning. */
+export declare const materializeComputations: (plan: LogicalPlan) => LogicalPlan;