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

package/dist/normalizer/public-logicform.d.ts

@@ -0,0 +1,14 @@
+import type { LogicformType } from '../logicform-types';
+import type { ResolvedSemanticSchema } from '../semantic-types/index';
+/**
+ * The planner uses canonical relation paths (for example `customer_name`),
+ * while a LogicForm exposed to an application keeps the relation structure
+ * that the caller wrote.  This is the public view of a normalized form.
+ *
+ * This conversion deliberately only changes relation paths.  Scalar values,
+ * temporal bounds, generated predicates and operator arguments remain the
+ * values produced by the normalizer.
+ */
+type SchemaResolver = (schemaId: string) => ResolvedSemanticSchema;
+export declare const expandPublicLogicform: (logicform: LogicformType, schema: ResolvedSemanticSchema, resolveSchema?: SchemaResolver, source?: LogicformType) => LogicformType;
+export {};

package/dist/normalizer/query.d.ts

@@ -1,5 +1,6 @@
 import type { ResolvedSemanticSchema } from '../semantic-types/index';
 import type { LogicformType } from '../logicform-types';
 import type { NormalizeLogicformOptions } from './core';
-export declare const normalizeQueryObject: (query: Readonly<Record<string, unknown>>, schema: ResolvedSemanticSchema, options: NormalizeLogicformOptions) => Promise<Readonly<Record<string, unknown>>>;
-export declare const normalizeQuery: (query: LogicformType["query"], schema: ResolvedSemanticSchema, options: NormalizeLogicformOptions) => Promise<LogicformType["query"]>;
+import type { MainTimeRangeCollector } from './main-time-range';
+export declare const normalizeQueryObject: (query: Readonly<Record<string, unknown>>, schema: ResolvedSemanticSchema, options: NormalizeLogicformOptions, timeRange?: MainTimeRangeCollector, queryPath?: readonly (string | number)[]) => Promise<Readonly<Record<string, unknown>>>;
+export declare const normalizeQuery: (query: LogicformType["query"], schema: ResolvedSemanticSchema, options: NormalizeLogicformOptions, timeRange?: MainTimeRangeCollector) => Promise<LogicformType["query"]>;

package/dist/normalizer/random-data.d.ts

@@ -0,0 +1,2 @@
+import type { LogicformRandomDataType } from '../logicform-types';
+export declare const normalizeRandomData: (value: unknown, allowed?: boolean) => LogicformRandomDataType | undefined;

package/dist/operators/builtins/period-name.d.ts

@@ -1,2 +1,5 @@
 import type { LocaleTranslate } from '../../i18n/index';
+import type { OperatorFormulaTextContext } from '../types';
+/** Describe the target period, rather than serializing the period-shift wire protocol. */
+export declare const periodShiftFormulaText: ({ input, args }: OperatorFormulaTextContext) => string;
 export declare const periodComparisonName: (args: Readonly<Record<string, unknown>>, locale: string, t?: LocaleTranslate) => string;

package/dist/operators/builtins/time-range.d.ts

@@ -8,6 +8,6 @@ export interface ResolvedTimeRange {
     readonly queryWithoutTime?: QueryType;
 }
 export declare const requireTimestampProperty: (schema: ResolvedSemanticSchema, operator: string) => ResolvedSemanticProperty;
-export declare const resolveTimeRange: (query: QueryType, schema: ResolvedSemanticSchema, resolveSchema: (schemaId: string) => ResolvedSemanticSchema, operator: string) => ResolvedTimeRange;
-export declare const resolvePredTimeRange: (logicformQuery: QueryType | undefined, pred: PredItemType, schema: ResolvedSemanticSchema, resolveSchema: (schemaId: string) => ResolvedSemanticSchema, operator: string) => ResolvedTimeRange;
+export declare const resolveTimeRange: (query: QueryType, schema: ResolvedSemanticSchema, resolveSchema: (schemaId: string) => ResolvedSemanticSchema, operator: string, defaultBoundary?: string | number | Date) => ResolvedTimeRange;
+export declare const resolvePredTimeRange: (logicformQuery: QueryType | undefined, pred: PredItemType, schema: ResolvedSemanticSchema, resolveSchema: (schemaId: string) => ResolvedSemanticSchema, operator: string, defaultBoundary?: string | number | Date) => ResolvedTimeRange;
 export declare const withTimeCondition: (query: QueryType | undefined, propertyName: string, condition: unknown) => QueryType;

package/dist/operators/formula-text.d.ts

@@ -0,0 +1,10 @@
+import type { OperatorDefinition, OperatorFormulaTextContext } from './types';
+/** Keep arbitrary custom/SQL expressions grouped when another operator consumes them. */
+export declare function groupFormulaText(formula: string): string;
+export declare function groupFormulaText(formula: string | null): string | null;
+export declare const functionFormulaText: (name: string) => (context: OperatorFormulaTextContext) => string;
+/** Missing formulas stay null, including when consumed by another expression. */
+export declare const operatorFormulaText: (operator: OperatorDefinition, context: Omit<OperatorFormulaTextContext, "input" | "inputs"> & {
+    readonly input?: string | null;
+    readonly inputs: readonly (string | null)[];
+}) => string | null;

package/dist/operators/index.d.ts

@@ -3,6 +3,7 @@ import { OperatorRegistry } from './registry';
 export { OperatorRegistry } from './registry';
 export { resolveOperator } from './resolve';
 export { bindTrustedSqlExpression } from './sql-expression';
-export type { OperatorDefinition, OperatorDefaultNameContext, OperatorExecutionContext, OperatorComponentContext, OperatorComponentCalculation, OperatorComponentQuery, OperatorExecutionComponent, OperatorGroupKeyShift, OperatorJavaScriptCalculation, OperatorQueryComponent, OperatorEvaluateContext, OperatorOutputPropertyContext, OperatorPeriodBoundaryPolicy, OperatorPeriodBoundaryPolicyContext, OperatorNormalizePredContext, OperatorPlanExpressionContext, OperatorPeriodEvaluationContext, OperatorPlanInputContext, OperatorPlannedInput, OperatorRewriteLogicformContext, OperatorValidatePlanContext, OperatorSqlCapabilities, OperatorSqlContext, ResultProperty, ResultPropertyTemporalMetadata, ResultPropertyTemporalMetadataExtensions, } from './types';
+export { groupFormulaText, operatorFormulaText } from './formula-text';
+export type { OperatorDefinition, OperatorDefaultNameContext, OperatorFormulaTextContext, OperatorExecutionContext, ResolvedTimeRange, OperatorComponentContext, OperatorComponentCalculation, OperatorComponentQuery, OperatorComponentLiteral, OperatorComponentInput, OperatorExecutionComponent, OperatorGroupKeyShift, OperatorJavaScriptCalculation, OperatorQueryComponent, OperatorOutputPropertyContext, OperatorPeriodBoundaryPolicy, OperatorPeriodBoundaryPolicyContext, OperatorNormalizePredContext, OperatorPlanExpressionContext, OperatorPeriodEvaluationContext, OperatorRuntimeHelpers, OperatorRuntimeConfig, OperatorRuntimeExecute, OperatorRuntimeRun, OperatorRuntimeValue, OperatorPlanInputContext, OperatorPlannedInput, OperatorRewriteLogicformContext, OperatorValidatePlanContext, OperatorSqlCapabilities, OperatorSqlContext, ResultProperty, ResultPropertyTemporalMetadata, ResultPropertyTemporalMetadataExtensions, } from './types';
 export declare const builtinOperators: readonly import("./types").OperatorDefinition[];
 export declare const createOperatorRegistry: (plugins?: readonly SemanticDBPlugin[]) => OperatorRegistry;

package/dist/operators/registry.d.ts

@@ -2,11 +2,18 @@ import type { OperatorDefinition, OperatorExecutionContext, OperatorPeriodEvalua
 export declare class OperatorRegistry {
     #private;
     readonly executionContext: OperatorExecutionContext;
-    constructor(definitions?: readonly OperatorDefinition[], executionContext?: OperatorExecutionContext);
+    constructor(definitions?: readonly OperatorDefinition[], executionContext?: OperatorExecutionContext, builtinDefinitions?: readonly OperatorDefinition[]);
     withExecutionContext(executionContext: OperatorExecutionContext): OperatorRegistry;
     register(input: OperatorDefinition): this;
+    /** Built-in status comes from registry construction, never an operator's spelling. */
+    isBuiltin(name: string): boolean;
     get(name: string): OperatorDefinition;
     requiresPerPeriodEvaluation(name: string, context: OperatorPeriodEvaluationContext): boolean;
+    /** Whether this predicate needs an executor query component. */
+    isComponent(pred: {
+        readonly operator?: string;
+        readonly query?: Readonly<Record<string, unknown>>;
+    }): boolean;
     has(name: string): boolean;
     definitions(): readonly OperatorDefinition[];
 }

package/dist/operators/types.d.ts

@@ -1,12 +1,33 @@
-import type { PrimalType, ResolvedSemanticProperty, ResolvedSemanticSchema, TimeGranularity, ComparableCategoryDefinition } from '../semantic-types/index';
-import type { LogicformType, PredItemType } from '../logicform-types';
+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,42 +265,67 @@ 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. */
     readonly mapResult?: (rows: readonly DataRow[]) => DataRow[];
     /** SQL-side transformations that align this component's group keys with the base component. */
     readonly groupKeyShifts?: readonly OperatorGroupKeyShift[];
+    /** Shift an already partitioned current query into this comparison period. */
+    readonly partitionQuery?: (currentShardQuery: QueryType) => QueryType;
+    /** Unshifted metric used to choose the same Mapping for a standalone comparison. */
+    readonly partitionCurrentLogicform?: LogicformType;
 }
 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[];
+    /** Name of the current-period component whose selected Mapping this query inherits. */
+    readonly comparisonOf?: string;
+    readonly partitionQuery?: (currentShardQuery: QueryType) => QueryType;
     /**
      * Group output names used to join this component back to the first component.
      * When omitted, the compiler joins on the groupby outputs shared by both components.
      */
     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.
  */
@@ -245,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. */
@@ -288,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;