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

package/dist/compiler/shorten-sql.d.ts

@@ -1,2 +1,2 @@
-/** Conservatively remove unused aliased columns from nested SELECT projections. */
+/** Conservatively simplify nested SELECT projections and pass-through views. */
 export declare const shortenSQL: (sql: string) => string;

package/dist/errors.d.ts

@@ -1,5 +1,8 @@
+import { type LocaleRegistry } from './i18n/index';
 export declare class SemanticDBError extends Error {
     readonly code: string;
     readonly details?: Readonly<Record<string, unknown>> | undefined;
     constructor(code: string, message: string, details?: Readonly<Record<string, unknown>> | undefined);
+    /** Return the user-facing message for an execution locale. */
+    localizedMessage(locale?: string, locales?: LocaleRegistry): string;
 }

package/dist/executor/compatibility.d.ts

@@ -1,6 +1,19 @@
 import type { SemanticSchemaDraft } from '../semantic-types/index';
 import type { SemanticDBPlugin } from '../plugins/index';
+import type { SchemaMappingDefinition } from '../schema-mappings/index';
 export { normalizeLegacyLogicform } from '../compatibility/logicform';
 /** Converts legacy Schema/Property identifiers without mutating caller data. */
 export declare const normalizeSchemas: (input: Readonly<Record<string, SemanticSchemaDraft>>, externalPlugins?: readonly SemanticDBPlugin[], legacy?: boolean) => Readonly<Record<string, SemanticSchemaDraft>>;
+declare const legacyEmptySource: unique symbol;
+type LegacyEmptyMapping = SchemaMappingDefinition & {
+    readonly [legacyEmptySource]: true;
+};
+export declare const isLegacyEmptyMapping: (mapping: SchemaMappingDefinition | undefined) => mapping is LegacyEmptyMapping;
+/**
+ * Adds an execution-local mapping for legacy Schemas without an explicit v2
+ * mapping. `from` SQL wins over the Schema-id table fallback when `db` exists.
+ * Only a Schema without either `from` or `db` gets an empty mapping so the
+ * planner can still produce the result shape. Existing mappings always win.
+ */
+export declare const normalizeLegacySchemaMappings: (schemas: Readonly<Record<string, SemanticSchemaDraft>>, mappings: readonly SchemaMappingDefinition[], defaultConnectionId?: string, requiredSchemaIds?: readonly string[], emptyConnectionIds?: readonly string[]) => readonly SchemaMappingDefinition[];
 export { normalizeLegacyLogicform as normalizeLogicform } from '../compatibility/logicform';

package/dist/executor/components.d.ts

@@ -1,9 +1,14 @@
 import type { LogicformType } from '../logicform-types';
-import type { OperatorExecutionComponent, OperatorRegistry } from '../operators/index';
+import type { OperatorComponentCalculation, OperatorJavaScriptCalculation, OperatorQueryComponent, OperatorRegistry } from '../operators/index';
 import type { DataRow } from '../physical/index';
 import type { LogicalPlan } from '../planner/index';
 import type { ResolvedSemanticSchema } from '../semantic-types/index';
-export type ExecutionUnit = OperatorExecutionComponent;
-export declare const createExecutionUnits: (logicform: LogicformType, plan: LogicalPlan, schema: ResolvedSemanticSchema, operators: OperatorRegistry, resolveSchema: (schemaId: string) => ResolvedSemanticSchema, sourceLogicform?: LogicformType) => readonly ExecutionUnit[] | undefined;
+import { type LocaleTranslate } from '../i18n/index';
+export type ExecutionUnit = OperatorQueryComponent | (OperatorComponentCalculation & {
+    readonly outputName: string;
+}) | (OperatorJavaScriptCalculation & {
+    readonly outputName: string;
+});
+export declare const createExecutionUnits: (logicform: LogicformType, plan: LogicalPlan, schema: ResolvedSemanticSchema, operators: OperatorRegistry, resolveSchema: (schemaId: string) => ResolvedSemanticSchema, sourceLogicform?: LogicformType, locale?: string, t?: LocaleTranslate) => readonly ExecutionUnit[] | undefined;
 export declare const mergeComponentRows: (results: readonly (readonly DataRow[])[], groupNames: readonly string[]) => DataRow[];
 export declare const mergeExecutionResults: (results: readonly (readonly DataRow[])[], plan: LogicalPlan) => DataRow[];

package/dist/executor/connection-registry.d.ts

@@ -1,12 +1 @@
-import type { CoreComputeProvider, DatabaseConnection } from '../physical/index';
-type ProviderFactory = (connection: DatabaseConnection) => CoreComputeProvider;
-export declare class ConnectionRegistry {
-    #private;
-    private readonly create;
-    constructor(create?: ProviderFactory);
-    get(connection: DatabaseConnection): CoreComputeProvider;
-    close(): Promise<void>;
-}
-export declare const getConnectionProvider: (connection: DatabaseConnection) => CoreComputeProvider;
-export declare const closeConnections: () => Promise<void>;
-export {};
+export { ConnectionRegistry, getConnectionProvider, closeConnections } from '../physical/index';

package/dist/executor/execute-query.d.ts

@@ -1,13 +1,19 @@
 import type { CompiledQuery } from '../compiler/index';
 import type { DataRow } from '../physical/index';
 import type { LogicalPlan } from '../planner/index';
-import type { InternalExecuteOptions } from './types';
+import type { SchemaMappingDefinition, SchemaMappingRegistry } from '../schema-mappings/index';
+import type { InternalExecuteOptions, SqlExecutionSource } from './types';
+export type SqlExecutionSourceReporter = (source: SqlExecutionSource) => void;
 export interface PhysicalQuerySource {
     readonly schemaId: string;
     readonly source: string;
+    readonly connectionId?: string;
+    /** Base mapping source that owns an enrichment source. */
+    readonly mappingSource?: string;
 }
+export declare const resolvePhysicalSourceMapping: (source: PhysicalQuerySource, mappings: SchemaMappingRegistry) => SchemaMappingDefinition | undefined;
 export declare const collectPlanSources: (plan: LogicalPlan) => readonly PhysicalQuerySource[];
 export declare const mergePhysicalSources: (groups: readonly (readonly PhysicalQuerySource[])[]) => readonly PhysicalQuerySource[];
-export declare const executeCompiledQuery: (compiled: CompiledQuery, sources: readonly PhysicalQuerySource[], options: Pick<InternalExecuteOptions, "cache" | "provider" | "schemaMappings" | "signal">) => Promise<DataRow[]>;
+export declare const executeCompiledQuery: (compiled: CompiledQuery, sources: readonly PhysicalQuerySource[], options: Pick<InternalExecuteOptions, "cache" | "provider" | "schemaMappings" | "signal" | "connectionId">, reportExecutionSource?: SqlExecutionSourceReporter) => Promise<DataRow[]>;
 /** Apply final SQL shaping after all plans, views, and derived sources are compiled. */
 export declare const shortenCompiledQuery: (compiled: CompiledQuery) => CompiledQuery;

package/dist/executor/federated-execution.d.ts

@@ -0,0 +1,38 @@
+import type { CompiledQuery } from '../compiler/index';
+import type { LogicformType } from '../logicform-types';
+import type { OperatorRegistry } from '../operators/index';
+import type { CoreComputeProvider, DataRow } from '../physical/index';
+import type { LogicalPlan } from '../planner/index';
+import type { SchemaMappingRegistry } from '../schema-mappings/index';
+import type { SqlExecutionSourceReporter } from './execute-query';
+import type { InternalExecuteOptions } from './types';
+export declare const coordinatorConnectionId = "__semanticdb_coordinator__";
+export interface FederatedCompiledQuery {
+    readonly compiled: CompiledQuery;
+    readonly connectionId: string;
+    readonly provider: CoreComputeProvider;
+    readonly type: 'computation' | 'total';
+    readonly logicform: LogicformType;
+}
+interface FederatedExecutionOptions {
+    readonly logicform: LogicformType;
+    readonly operators: OperatorRegistry;
+    readonly schemaMappings: SchemaMappingRegistry;
+    readonly providerForConnection: (connectionId: string) => CoreComputeProvider;
+    readonly cache?: InternalExecuteOptions['cache'];
+    readonly signal?: AbortSignal;
+    readonly maxMaterializedRows: number;
+    readonly onCompiled: (query: FederatedCompiledQuery) => SqlExecutionSourceReporter;
+}
+export interface FederatedExecutionResult {
+    readonly rows: DataRow[];
+    readonly total: number;
+    readonly connections: readonly {
+        readonly connectionId: string;
+        readonly provider: CoreComputeProvider['kind'];
+    }[];
+}
+export declare const planConnectionIds: (plan: LogicalPlan, schemaMappings: SchemaMappingRegistry) => readonly string[];
+export declare const isFederatedComposition: (plan: LogicalPlan, schemaMappings: SchemaMappingRegistry) => boolean;
+export declare const executeFederatedComposition: (plan: LogicalPlan, options: FederatedExecutionOptions) => Promise<FederatedExecutionResult>;
+export {};

package/dist/executor/fetch-entities.d.ts

@@ -1,3 +1,4 @@
+import type { LogicformType } from '../logicform-types';
 import type { OperatorRegistry } from '../operators/index';
 import type { DataRow } from '../physical/index';
 import type { SchemaMappingRegistry } from '../schema-mappings/index';
@@ -8,19 +9,24 @@ import type { Permissions } from '../permissions/index';
 import type { ResolvedSemanticSchema, SemanticTypeRegistry } from '../semantic-types/index';
 import type { EntityFetchRequest } from './result-hydrator/index';
 import type { SemanticDBPlugin } from '../plugins/index';
+import type { SqlExecutionSourceReporter } from './execute-query';
+import type { LocaleRegistry } from '../i18n/index';
 interface FetchEntityOptions {
     readonly version: string;
     readonly operators: OperatorRegistry;
     readonly locale?: string;
+    readonly localeRegistry?: LocaleRegistry;
     readonly schemaMappings: SchemaMappingRegistry;
     readonly semanticTypes: SemanticTypeRegistry;
     readonly plugins?: readonly SemanticDBPlugin[];
     readonly resolveSchema: (schemaId: string) => ResolvedSemanticSchema;
     readonly permissions?: Permissions;
     readonly provider: CoreComputeProvider;
+    readonly providerForConnection?: (connectionId: string) => CoreComputeProvider;
+    readonly preferredConnectionId?: string;
     readonly cache?: QueryCacheExecutionOptions;
     readonly signal?: AbortSignal;
-    readonly onCompiled?: (compiled: CompiledQuery) => void;
+    readonly onCompiled?: (compiled: CompiledQuery, logicform: LogicformType, provider: CoreComputeProvider, connectionId?: string) => SqlExecutionSourceReporter | undefined;
 }
 export declare const fetchEntities: (request: EntityFetchRequest, options: FetchEntityOptions) => Promise<DataRow[]>;
 export {};

package/dist/executor/index.d.ts

@@ -1,3 +1,3 @@
 export { execute } from './execute';
 export { closeConnections } from './connection-registry';
-export type { ExecuteOptions, ExecuteFailureResult, ExecuteProgressEvent, ExecuteResult, ExecuteSuccessResult, ExecutedSql, ExecutedSqlType, PartialExecuteResult, ProgressCallback, } from './types';
+export type { ExecuteOptions, ExecuteFailureResult, ExecuteProgressEvent, ExecuteResult, ExecuteSuccessResult, ExecutedSql, ExecutedSqlType, SqlExecutionSource, PartialExecuteResult, ProgressCallback, } from './types';

package/dist/executor/result-hydrator/types.d.ts

@@ -1,6 +1,7 @@
 import type { ResultProperty } from '../../operators/index';
 import type { DataRow } from '../../physical/index';
 import type { ResolvedSemanticProperty, ResolvedSemanticSchema, SemanticTypeRegistry } from '../../semantic-types/index';
+import type { SemanticDBPlugin } from '../../plugins/index';
 export type HydrationProperty = Pick<ResultProperty, 'isArray' | 'name' | 'primal_type' | 'ref' | 'type'> | ResolvedSemanticProperty;
 export interface EntityFetchRequest {
     readonly schema: ResolvedSemanticSchema;
@@ -11,4 +12,5 @@ export interface ResultHydratorOptions {
     readonly semanticTypes: SemanticTypeRegistry;
     readonly resolveSchema: (schemaId: string) => ResolvedSemanticSchema;
     readonly fetchEntities: (request: EntityFetchRequest) => Promise<readonly DataRow[]>;
+    readonly plugins?: readonly SemanticDBPlugin[];
 }

package/dist/executor/row-identity.d.ts

@@ -1,4 +1,5 @@
 import type { DataRow } from '../physical/index';
 import type { RowIdentityPlan } from '../planner/index';
-export declare const groupRowIdentity: (row: DataRow, names: readonly string[]) => string;
+export declare const identityPart: (value: unknown) => string;
+export declare const groupRowIdentity: (row: DataRow, names: readonly string[], separator?: string, nullLabel?: string) => string;
 export declare const addRowIdentities: (rows: readonly DataRow[], identity: RowIdentityPlan) => DataRow[];

package/dist/executor/total.d.ts

@@ -0,0 +1,11 @@
+import type { CompiledQuery } from '../compiler/index';
+import type { CoreComputeProvider, DataRow } from '../physical/index';
+import type { LogicalPlan } from '../planner/index';
+import type { LogicformType } from '../logicform-types';
+/** Remove global result paging while retaining HAVING and per-group limitBy semantics. */
+export declare const withoutGlobalPagination: (plan: LogicalPlan) => LogicalPlan;
+/** Describe the total SQL with the same unpaged global result as its plan. */
+export declare const withoutGlobalPaginationLogicform: (logicform: LogicformType) => LogicformType;
+/** Count the rows produced by a complete unpaginated logical result. */
+export declare const compileTotalQuery: (unpaged: CompiledQuery, provider: CoreComputeProvider) => CompiledQuery;
+export declare const readTotal: (rows: readonly DataRow[]) => number;

package/dist/executor/types.d.ts

@@ -1,14 +1,14 @@
-import type { OperatorRegistry } from '../operators/index';
-import type { CoreComputeProvider, DataRow, SqlParameters } from '../physical/index';
+import type { OperatorDefinition, OperatorExecutionContext, OperatorRegistry } from '../operators/index';
+import type { CoreComputeProvider, DataRow, ProviderRegistry, SqlParameters } from '../physical/index';
 import type { DatabaseConnection } from '../physical/index';
 import type { LogicalPlan, QueryLineage } from '../planner/index';
-import type { SchemaMappingRegistry } from '../schema-mappings/index';
-import type { ResolvedSemanticSchema, SemanticSchemaDraft, SemanticTypeRegistry } from '../semantic-types/index';
-import type { LogicformType } from '../logicform-types';
-import type { QueryCacheExecutionOptions } from '../cache/index';
+import type { SchemaMappingDefinition, SchemaMappingRegistry, SchemaMappingSelection } from '../schema-mappings/index';
+import type { ResolvedSemanticSchema, SemanticSchemaDraft, SemanticTypeRegistry, TimeWatermarkPolicy } from '../semantic-types/index';
+import type { LogicformType, PublicLogicformType } from '../logicform-types';
+import type { QueryCacheConfiguration, QueryCacheExecutionOptions } from '../cache/index';
 import type { Permissions } from '../permissions/index';
-import type { CustomFunctions } from '../custom-functions/index';
 import type { SemanticDBPlugin } from '../plugins/index';
+import type { LocaleInput, LocaleRegistry } from '../i18n/index';
 export type ExecuteProgressEvent = {
     readonly stage: 'started';
     readonly logicform: LogicformType;
@@ -36,6 +36,7 @@ export type ExecuteProgressEvent = {
 } | {
     readonly stage: 'executing';
     readonly provider: CoreComputeProvider['kind'];
+    readonly connectionId?: string;
     readonly partialResult: PartialExecuteResult;
 } | {
     readonly stage: 'hydrating';
@@ -56,63 +57,107 @@ export type ExecuteProgressEvent = {
 export type ProgressCallback = (event: ExecuteProgressEvent) => void | Promise<void>;
 interface ExecuteBaseOptions {
     readonly schemas: Readonly<Record<string, SemanticSchemaDraft>>;
-    readonly schemaMappings: SchemaMappingRegistry;
+    /** Caller-owned Registry; plugin SemanticTypes are copied into the execution Registry. */
     readonly semanticTypes?: SemanticTypeRegistry;
-    readonly operators?: OperatorRegistry;
+    /** Caller-defined Operators; explicit definitions override same-name built-ins or plugin Operators. */
+    readonly operators?: OperatorDefinition | readonly OperatorDefinition[];
     /** Caller-owned capability plugins appended to the built-in plugin set for this execution. */
     readonly plugins?: readonly SemanticDBPlugin[];
     /** Locale for generated human-readable PredItem names. Defaults to zh-CN. */
     readonly locale?: string;
+    /** Additional or overriding locale files used by generated names and messages. */
+    readonly locales?: LocaleInput;
     /** Table, row, and column permissions for this execution. */
     readonly permissions?: Permissions;
-    /** Legacy-compatible dynamically supplied composite metric definitions. */
-    readonly customFunctions?: CustomFunctions;
-    /** Third argument passed to mergeComponents/genMergeSQL callbacks. */
-    readonly customFunctionConfig?: Readonly<Record<string, unknown>>;
-    /** Optional caller-owned cache shared across executions. */
-    readonly cache?: QueryCacheExecutionOptions;
     readonly onProgress?: ProgressCallback;
     readonly signal?: AbortSignal;
+    /** Default time watermark policy; Schema and Property policies override it. */
+    readonly timeWatermark?: TimeWatermarkPolicy;
+    /** Resource limits for in-process combination of separate physical connections. */
+    readonly federation?: {
+        /** Defaults to 100,000 rows across all materialized aggregate branches. */
+        readonly maxMaterializedRows?: number;
+    };
 }
 export interface ExecuteOptions extends ExecuteBaseOptions {
+    /** Physical mappings supplied as JSON definitions. */
+    readonly schemaMappings: readonly SchemaMappingDefinition[];
     /** Database connections addressable by SchemaMappingDefinition.connectionId. */
     readonly connections: readonly DatabaseConnection[];
+    /** Provider factories used for built-in or application-defined connection kinds. */
+    readonly providerRegistry?: ProviderRegistry;
+    /** JSON configuration for an internally owned and reused query-cache connection. */
+    readonly cache?: QueryCacheConfiguration;
 }
 /** Internal execution seam used by executor tests after a provider has been resolved. */
-export interface InternalExecuteOptions extends ExecuteBaseOptions {
+export interface InternalExecuteOptions extends Omit<ExecuteBaseOptions, 'operators'> {
+    readonly operators?: OperatorRegistry;
+    /** The public execution boundary has already merged built-in, plugin, and explicit Operators. */
+    readonly operatorsResolved?: boolean;
+    /** Present for nested executions to reuse or intentionally suppress calendar preloading. */
+    readonly executionContext?: OperatorExecutionContext;
+    /** The public execution boundary has already merged plugin SemanticTypes. */
+    readonly semanticTypesResolved?: boolean;
+    readonly localeRegistry?: LocaleRegistry;
     readonly provider: CoreComputeProvider;
+    /** Resolve providers for additional physical connections in a federated execution. */
+    readonly providerForConnection?: (connectionId: string) => CoreComputeProvider;
+    readonly schemaMappings: SchemaMappingRegistry;
+    /** Cache connection already resolved at the public execution boundary. */
+    readonly cache?: QueryCacheExecutionOptions;
     /** Selected connection for public execution; omitted only by internal provider tests. */
     readonly connectionId?: string;
 }
 export interface ExecuteSuccessResult {
     readonly result: DataRow[];
+    /** Result rows or grouped rows before global limit/page pagination. */
+    readonly total: number;
     /** Schema describing the computed result rows. */
     readonly schema: ResolvedSemanticSchema;
-    readonly normedLogicform: LogicformType;
+    readonly normedLogicform: PublicLogicformType;
     readonly sqls: readonly ExecutedSql[];
     readonly lineage: QueryLineage;
     readonly provider: CoreComputeProvider['kind'];
+    /** Physical connections that contributed rows to this result. */
+    readonly providers: readonly {
+        readonly connectionId: string;
+        readonly provider: CoreComputeProvider['kind'];
+    }[];
+    /** Physical mapping decisions, including why every non-selected candidate lost. */
+    readonly schemaMappingSelections: readonly SchemaMappingSelection[];
+    /** Plugin-owned materialization for a custom LogicForm output type. */
+    readonly output?: unknown;
 }
 export interface ExecuteFailureResult {
     readonly errorCode: '100';
     readonly error: string;
     readonly result: readonly [];
     readonly schema?: ResolvedSemanticSchema;
-    readonly normedLogicform: LogicformType;
+    readonly normedLogicform: PublicLogicformType;
     readonly sqls: readonly ExecutedSql[];
     readonly provider?: CoreComputeProvider['kind'];
     readonly lineage?: QueryLineage;
 }
 export type ExecuteResult = ExecuteSuccessResult | ExecuteFailureResult;
-export type ExecutedSqlType = 'computation' | 'semantic-resolution';
+export type ExecutedSqlType = 'computation' | 'semantic-resolution' | 'total';
+export type SqlExecutionSource = 'cache' | 'database';
 export interface ExecutedSql {
     /** Why this SQL participates in the LogicForm execution. */
     readonly type: ExecutedSqlType;
+    /** Physical connection that executed this SQL, or the in-process coordinator id. */
+    readonly connectionId?: string;
+    readonly provider?: CoreComputeProvider['kind'];
+    /** Human-readable, localized explanation of why this SQL is executed. */
+    readonly explain: string;
+    /** Normalized LogicForm represented by this SQL statement. */
+    readonly logicform: PublicLogicformType;
     /** Parameterized SQL used for provider execution and cache identity. */
     readonly sql: string;
     readonly parameters: SqlParameters;
     /** Dialect-formatted diagnostic SQL. SemanticDB never executes this string. */
     readonly displaySql: string;
+    /** Actual row source. Absent only before execution, such as in the compiled progress event. */
+    readonly executionSource?: SqlExecutionSource;
 }
 export type PartialExecuteResult = Partial<ExecuteSuccessResult>;
 export {};

package/dist/i18n/index.d.ts

@@ -0,0 +1,4 @@
+export { createLocaleRegistry, defaultLocaleRegistry, LocaleRegistry } from './registry';
+export type { LocaleDefinition, LocaleInput, LocaleTranslate } from './types';
+export { enUS } from './locales/en-US';
+export { zhCN } from './locales/zh-CN';

package/dist/i18n/locales/en-US.d.ts

@@ -0,0 +1,2 @@
+import type { LocaleDefinition } from '../types';
+export declare const enUS: LocaleDefinition;

package/dist/i18n/locales/zh-CN.d.ts

@@ -0,0 +1,2 @@
+import type { LocaleDefinition } from '../types';
+export declare const zhCN: LocaleDefinition;

package/dist/i18n/registry.d.ts

@@ -0,0 +1,13 @@
+import type { LocaleDefinition, LocaleInput, LocaleTranslate } from './types';
+export declare class LocaleRegistry {
+    private readonly definitions;
+    private readonly i18n;
+    constructor(locales?: LocaleInput);
+    register(locales: LocaleInput | undefined): this;
+    resolve(locale?: string): LocaleDefinition;
+    has(locale: string): boolean;
+    translate(locale: string, key: string, fallback?: string, values?: Readonly<Record<string, unknown>>): string;
+    translator(locale?: string): LocaleTranslate;
+}
+export declare const createLocaleRegistry: (locales?: LocaleInput) => LocaleRegistry;
+export declare const defaultLocaleRegistry: LocaleRegistry;

package/dist/i18n/types.d.ts

@@ -0,0 +1,9 @@
+/** A locale file consumed by SemanticDB's naming and error messages. */
+export interface LocaleDefinition {
+    /** BCP-47 locale tag, for example `zh-CN` or `en-US`. */
+    readonly locale: string;
+    /** Translation messages keyed by a stable SemanticDB message key. */
+    readonly messages: Readonly<Record<string, string>>;
+}
+export type LocaleInput = LocaleDefinition | readonly LocaleDefinition[];
+export type LocaleTranslate = (key: string, fallback?: string, values?: Readonly<Record<string, unknown>>) => string;

package/dist/index.d.ts

@@ -1,26 +1,26 @@
+export { createLocaleRegistry, defaultLocaleRegistry, LocaleRegistry, enUS, zhCN, } from './i18n/index';
+export type { LocaleDefinition, LocaleInput, LocaleTranslate } from './i18n/index';
 export declare const Logicform: Readonly<{
     execute: (inputLogicform: import("./logicform-types").LogicformType, inputOptions: import(".").ExecuteOptions) => Promise<import(".").ExecuteResult>;
     close: () => Promise<void>;
-    genComponents: (pred: import("./logicform-types").PredItemType, options: import(".").GenMetricComponentsOptions) => import(".").MetricComponentNode;
 }>;
 export { SemanticDBError } from './errors';
 export { builtinSemanticTypes, createSemanticTypeRegistry, resolveSchema, SemanticTypeRegistry, validateResolvedSchema, } from './semantic-types/index';
-export { builtinOperators, createOperatorRegistry, OperatorRegistry, } from './operators/index';
-export type { LegacySchemaPluginContext, SchemaMetadataPlugin, SemanticDBPlugin, } from './plugins/index';
-export { SchemaMappingRegistry, } from './schema-mappings/index';
-export type { AbsoluteDateValue, CompareOperator, CalendarDateValue, DateTimeValue, DateValue, ExpressionItemType, LogicformType, PeriodShiftTime, PredItemType, QueryLogicalOperand, RecursiveQueryType, RelationQueryType, QueryType, QueryValueType, QueryValueTypeWithCompareOperator, RelativeDateValue, RepresentationType, } from './logicform-types';
-export { CALENDAR_DATES_TABLE, CALENDAR_RELATIONS_TABLE, CALENDAR_SYSTEM_SCHEMA_IDS, calendarSystemSchemas, ProviderCalendarRelationStore, resolveCalendarPeriod, resolveCalendarPeriodFromStore, selectCalendarDates, } from './calendar/index';
-export type { CalendarAlignment, CalendarComparison, CalendarDateRow, CalendarRelation, CalendarRelationRow, ResolvedCalendarPeriod, } from './calendar/index';
-export type { CalendarRelationStore } from './calendar/index';
-export type { PrimalType, PropertySqlDefinition, ResolvedSemanticProperty, ResolvedSemanticSchema, SemanticTypeNormalizeContext, SemanticPropertyDraft, SemanticSchemaDraft, SemanticTypeDefinition, SemanticTypeResultContext, SemanticTypeResultProperty, TemporalSemantics, TimeGranularity, } from './semantic-types/index';
-export type { HierarchyDefinition, HierarchyLevelDefinition, ResolvedHierarchyDefinition, } from './plugins/hierarchy/index';
-export type { DataRow, SqlParameters, DatabaseConnection, } from './physical/index';
-export type { OperatorDefinition, OperatorDefaultNameContext, OperatorComponentContext, OperatorCteCalculation, OperatorCteComponent, OperatorCteSqlContext, OperatorExecutionComponent, OperatorPlanInputContext, OperatorPlannedInput, OperatorGroupKeyShift, OperatorJavaScriptCalculation, OperatorQueryComponent, OperatorEvaluateContext, OperatorOutputPropertyContext, OperatorSqlCapabilities, OperatorSqlContext, ResultProperty, ResultPropertyTemporalMetadata, } from './operators/index';
-export type { SchemaMappingDefinition, SchemaMappingPredDefinition, SchemaMappingPredMatch, SourceFreshnessPolicy, } from './schema-mappings/index';
-export type { QueryCache, QueryCacheExecutionOptions, QueryCacheIdentity, QueryCacheWriteOptions, } from './cache/index';
-export type { ExecuteOptions, ExecuteFailureResult, ExecuteProgressEvent, ExecuteResult, ExecuteSuccessResult, ExecutedSql, ExecutedSqlType, PartialExecuteResult, ProgressCallback, } from './executor/index';
+export { builtinOperators, createOperatorRegistry, OperatorRegistry, resolveOperator, } from './operators/index';
+export type { LegacySchemaPluginContext, MappingGranularityContext, MappingGranularityPlugin, OutputHandlerContext, OutputHandlerDefinition, IntervalSemanticProperties, IntervalSemanticsDefinition, PlannerPeriodDefinition, PlannerPeriodEvaluation, RelationSemanticsDefinition, RelationTemporalPlan, TimeWatermarkLogicformContext, PropertyMetadataPlugin, QueryOperatorCompileContext, QueryOperatorAuthorizeContext, QueryOperatorDefinition, QueryOperatorNormalizeContext, QueryOperatorPhysicalSource, QueryOperatorPlanContext, QueryOperatorPlanResult, SchemaMetadataPlugin, SchemaMappingPlugin, SemanticDBPlugin, } from './plugins/index';
+export { SchemaMappingRegistry, fromYiAskSchemaMapping, } from './schema-mappings/index';
+export type { AbsoluteDateValue, CompareOperator, DatePartQueryComparison, DatePartQueryOperand, DateTimeValue, DateValue, EntityIdType, ExpressionItemType, LogicformType, NumericQueryComparison, NumericQueryOperand, PublicLogicformType, PeriodShiftTime, PredItemType, QueryLogicalOperand, QueryExpressionType, RelationQueryType, QueryType, QueryValueType, QueryValueTypeWithCompareOperator, RelativeDateValue, RepresentationType, } from './logicform-types';
+export type { RecursiveQueryType } from './plugins/index';
+export type { PrimalType, PropertyHierarchyDefinition, PropertySqlDefinition, ResolvedSemanticProperty, ResolvedSemanticSchema, SemanticTypeNormalizeContext, SemanticPropertyDraft, SemanticSchemaDraft, SemanticTypeDefinition, SemanticTypeResultContext, SemanticTypeResultProperty, TimeGranularity, TimeWatermarkPolicy, } from './semantic-types/index';
+export type { DataRow, SqlParameters, BuiltinDatabaseConnection, DatabaseConnection, DatabaseConnectionBase, DatabaseConnectionExtensions, ProviderDefinition, ProviderKind, ProviderKindExtensions, } from './physical/index';
+export { DBConnector, ProviderRegistry } from './physical/index';
+export type { DBConnectorOptions, RunSQLOptions, GetTableListOptions, DescribeTableOptions, DescribeTableRequest, DatabaseColumn, TableDescription, DatabaseTable, SQLResult, TableListRequest, } from './physical/index';
+export type { OperatorDefinition, OperatorDefaultNameContext, OperatorExecutionContext, OperatorComponentContext, OperatorComponentCalculation, OperatorComponentQuery, OperatorExecutionComponent, OperatorPlanInputContext, OperatorPlannedInput, OperatorGroupKeyShift, OperatorJavaScriptCalculation, OperatorQueryComponent, OperatorEvaluateContext, OperatorOutputPropertyContext, OperatorSqlCapabilities, OperatorSqlContext, ResultProperty, ResultPropertyTemporalMetadata, ResultPropertyTemporalMetadataExtensions, } from './operators/index';
+export type { SchemaMappingDefinition, SchemaMappingEnrichmentDefinition, SchemaMappingEnrichmentKey, SchemaMappingItem, SchemaMappingGranularity, SchemaMappingGranularityExtensions, SchemaMappingPointTemporalDefinition, SchemaMappingPredDefinition, SchemaMappingPredMatch, SchemaMappingSelection, RejectedSchemaMapping, SourceFreshnessPolicy, YiAskSchemaMappingItem, YiAskSchemaMappingRecord, } from './schema-mappings/index';
+export { QueryCacheManager } from './cache/index';
+export type { InvalidateQueryCacheSourceOptions, QueryCacheConfiguration, } from './cache/index';
+export type { ExecuteOptions, ExecuteFailureResult, ExecuteProgressEvent, ExecuteResult, ExecuteSuccessResult, ExecutedSql, ExecutedSqlType, SqlExecutionSource, PartialExecuteResult, ProgressCallback, } from './executor/index';
 export type { ColumnPermissions, Permissions, SchemaPermissions, } from './permissions/index';
-export type { CustomFunctionColumnProperty, CustomFunctionDefinition, CustomFunctionHelpers, CustomFunctionSqlContext, CustomFunctions, GenComponents, GenComponentsContext, GenMergeSQL, GenMetricComponentsOptions, MergeComponents, MetricComponentNode, } from './custom-functions/index';
 export type { CreateLogicalPlanOptions, LogicalPlan, QueryLineage, } from './planner/index';
 export { PlannerSemanticRegistry, createPlannerSemanticRegistry, } from './planner/index';
 export type { PlannerSemanticResolution, PlannerSemanticQueryContext, PlannerSemanticRule, PlannerSemanticRuleContext, } from './planner/index';

package/dist/logicform-types.d.ts

@@ -19,29 +19,15 @@ export interface AbsoluteDateValue {
     readonly second?: number;
     readonly period?: 'am' | 'pm';
 }
-/** A business-calendar period resolved to natural days before planning. */
-export interface CalendarDateValue {
-    readonly calendar: string;
-    readonly key?: string;
-    readonly year?: number;
-    readonly quarter?: number;
-    readonly month?: number;
-    readonly week?: number;
-    readonly day?: number;
-    readonly relativeDay?: number | readonly number[];
-}
 /** Period reference used by operators such as `$periodShift`. */
 export type PeriodShiftTime = RelativeDateValue | AbsoluteDateValue;
 /** A date value before semantic-type normalization. */
-export type DateValue = string | RelativeDateValue | AbsoluteDateValue | CalendarDateValue;
-export type CompareOperator = '$eq' | '$gt' | '$gte' | '$lt' | '$lte' | '$ne' | '$in' | '$nin' | '$exists' | '$regex' | '$contains' | '$recursive' | '$and' | '$or';
-export interface RecursiveQueryType {
-    readonly schema?: string;
-    readonly root?: QueryValueType;
-    readonly roots?: QueryValueType[];
-    readonly includeSelf?: boolean;
-    readonly idProperty?: string;
-    readonly parentProperty?: string;
+export type DateValue = string | RelativeDateValue | AbsoluteDateValue;
+/** Stable entity identity. Numeric IDs must be safe integers. */
+export type EntityIdType = string | number;
+export type CompareOperator = '$eq' | '$gt' | '$gte' | '$lt' | '$lte' | '$ne' | '$in' | '$nin' | '$exists' | '$regex' | '$contains' | '$startsWith' | '$length' | '$and' | '$or' | '$second' | '$minute' | '$hour' | '$weekday' | '$day' | '$week' | '$month' | '$quarter' | '$year' | Extract<keyof QueryOperatorExtensions, string>;
+/** Module-augmentation seam for plugin-owned field Query Operators. */
+export interface QueryOperatorExtensions {
 }
 export type QueryValueType = null | string | number | boolean | DateValue | RelationQueryType | LogicformType | string[] | number[] | boolean[] | DateValue[] | RelationQueryType[] | LogicformType[];
 /** A query scoped through an object relation. Version is inherited from the parent LogicForm. */
@@ -50,9 +36,29 @@ export interface RelationQueryType {
     readonly schema: string;
     readonly query: QueryType;
     /** Stable entity identity. `placeholder` preserves context without adding an ID filter. */
-    readonly entity_id?: string;
+    readonly entity_id?: EntityIdType;
 }
 export type QueryLogicalOperand = QueryValueType | QueryValueTypeWithCompareOperator;
+/** Apply a scalar pred expression, then test its result against a condition. */
+export interface QueryExpressionType {
+    readonly pred: PredItemType;
+    readonly condition: QueryLogicalOperand;
+}
+export type NumericQueryOperand = number | number[] | NumericQueryComparison;
+export type NumericQueryComparison = Partial<{
+    $eq: number;
+    $gt: number;
+    $gte: number;
+    $lt: number;
+    $lte: number;
+    $ne: number;
+    $in: number[];
+    $nin: number[];
+    $and: NumericQueryOperand[];
+    $or: NumericQueryOperand[];
+}>;
+export type DatePartQueryOperand = NumericQueryOperand;
+export type DatePartQueryComparison = NumericQueryComparison;
 export type QueryValueTypeWithCompareOperator = Partial<{
     $eq: QueryValueType;
     $gt: QueryValueType;
@@ -65,34 +71,49 @@ export type QueryValueTypeWithCompareOperator = Partial<{
     $exists: QueryValueType;
     $regex: QueryValueType;
     $contains: QueryValueType;
+    $startsWith: string;
+    $length: NumericQueryOperand;
+    $second: DatePartQueryOperand;
+    $minute: DatePartQueryOperand;
+    $hour: DatePartQueryOperand;
+    /** ISO weekday: Monday=1 through Sunday=7. */
+    $weekday: DatePartQueryOperand;
+    /** Day of month. */
+    $day: DatePartQueryOperand;
+    /** ISO week of year. */
+    $week: DatePartQueryOperand;
+    $month: DatePartQueryOperand;
+    $quarter: DatePartQueryOperand;
+    $year: DatePartQueryOperand;
     args?: {
         readonly options?: string;
     };
-    $recursive: QueryValueType | RecursiveQueryType;
     $and: QueryLogicalOperand[];
     $or: QueryLogicalOperand[];
-}> & {
+}> & Partial<QueryOperatorExtensions> & {
     readonly schema?: never;
 };
-export type QueryType = Record<string, QueryValueType | QueryValueTypeWithCompareOperator | QueryType[] | undefined> & {
+export type QueryType = Record<string, QueryValueType | QueryValueTypeWithCompareOperator | QueryExpressionType | QueryType[] | undefined> & {
     readonly $and?: QueryType[];
     readonly $or?: QueryType[];
+    readonly $expr?: QueryExpressionType;
 };
 export interface ExpressionItemType {
     operator?: string;
-    pred?: string | ExpressionItemType;
-    /** Structural operands for multi-input operators. Operator options remain in `args`. */
-    components?: ExpressionItemType[];
+    /** Operator input. Arrays represent ordered multi-input predicates. */
+    pred?: string | ExpressionItemType | (string | ExpressionItemType)[];
     name?: string;
     schema?: string;
     args?: Record<string, unknown>;
 }
 export interface PredItemType extends ExpressionItemType {
-    pred?: string | PredItemType;
-    components?: PredItemType[];
+    pred?: string | PredItemType | (string | PredItemType)[];
     query?: QueryType;
 }
-export type LogicformOutputTypeValue = 'url' | 'data' | 'export' | 'sql' | 'sqlComponents';
+/** Module-augmentation seam for plugin-owned output types. */
+export interface LogicformOutputExtensions {
+}
+export type LogicformOutputTypeValue = 'url' | 'data' | 'export' | 'sql' | 'sqlComponents' | Extract<keyof LogicformOutputExtensions, string>;
 export interface LogicformOutputType {
     type: LogicformOutputTypeValue;
     filename?: string;
@@ -102,10 +123,10 @@ export interface LogicformType {
     version: string;
     /** Required for a physical leaf. Derived and composed nodes inherit their field space. */
     schema?: string;
-    /** Complete child LogicForms whose result columns are combined by their shared row identity. */
-    logicforms?: LogicformType[];
     query?: QueryType;
     preds?: PredItemType[];
+    /** Output/reference aliases for properties contributed by another Schema. */
+    propertyResolve?: Readonly<Record<string, Readonly<Record<string, string>>>>;
     groupby?: PredItemType[];
     sort?: Record<string, 1 | -1>;
     having?: QueryType;
@@ -115,11 +136,10 @@ export interface LogicformType {
     page?: number;
     representation?: RepresentationType;
     /** Stable entity identity. `placeholder` preserves context without adding an ID filter. */
-    entity_id?: string;
+    entity_id?: EntityIdType;
     from?: LogicformType;
     currency?: string;
 }
+/** Public normalized shape; composition is represented by Planner subplans. */
+export type PublicLogicformType = LogicformType;
 export declare const isLogicform: (value: unknown) => value is LogicformType;
-export declare const isComposedLogicform: (value: LogicformType) => value is LogicformType & {
-    readonly logicforms: LogicformType[];
-};