semanticdb-v2 2.0.0-alpha.5 → 2.0.0-alpha.6

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

@@ -1,5 +1,4 @@
-import type { PoolAttributes } from 'oracledb';
-import type { CoreComputeProvider, DataRow, ProviderExecutionRequest } from './provider';
+import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest } from './provider';
 type OracleBind = string | number | boolean | Date | Buffer | null;
 export interface OracleConnectionLike {
     execute(sql: string, binds: OracleBind[], options: {
@@ -14,12 +13,22 @@ export interface OraclePoolLike {
     getConnection(): Promise<OracleConnectionLike>;
     close(drainTime?: number): Promise<void>;
 }
+export interface OracleConnectionOptions {
+    readonly user?: string;
+    readonly password?: string;
+    readonly connectString?: string;
+    readonly poolMin?: number;
+    readonly poolMax?: number;
+    readonly poolIncrement?: number;
+    readonly poolTimeout?: number;
+    readonly [option: string]: unknown;
+}
 export interface OracleDriverLike {
-    createPool(options: PoolAttributes): Promise<OraclePoolLike>;
+    createPool(options: OracleConnectionOptions): Promise<OraclePoolLike>;
 }
 export interface OracleProviderOptions {
     /** Passed to oracledb.createPool(). Thin mode is used unless the caller initialized Thick mode. */
-    readonly connection?: PoolAttributes;
+    readonly connection?: object;
     /** Injectable pool for applications that own pool creation or for tests. */
     readonly pool?: OraclePoolLike;
     /** Injectable driver factory used to test lazy pool creation. */
@@ -37,11 +46,13 @@ export declare class OracleProvider implements CoreComputeProvider {
     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;
     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;
     expandArray(arrayExpression: string, alias: string, column: string): {

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

@@ -1,20 +1,32 @@
-import type { PoolConfig } from 'pg';
-import type { CoreComputeProvider, DataRow, ProviderExecutionRequest } from './provider';
+import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest } from './provider';
 export interface PostgreSQLPoolLike {
     query(sql: string, values: unknown[]): Promise<{
         readonly rows: unknown;
     }>;
     end(): Promise<void>;
 }
+export interface PostgreSQLConnectionOptions {
+    readonly connectionString?: string;
+    readonly host?: string;
+    readonly port?: number;
+    readonly user?: string;
+    readonly password?: string;
+    readonly database?: string;
+    readonly ssl?: unknown;
+    readonly max?: number;
+    readonly idleTimeoutMillis?: number;
+    readonly connectionTimeoutMillis?: number;
+    readonly [option: string]: unknown;
+}
 export interface PostgreSQLProviderOptions {
-    readonly connection?: PoolConfig;
+    readonly connection?: object;
     readonly pool?: PostgreSQLPoolLike;
 }
 export declare class PostgreSQLProvider implements CoreComputeProvider {
+    #private;
     readonly kind: "postgresql";
     readonly supportsHavingAlias = false;
     readonly supportsRecursiveCte = true;
-    private readonly pool;
     constructor(options?: PostgreSQLProviderOptions);
     quoteIdentifier(identifier: string): string;
     tableAlias(expression: string, alias: string): string;
@@ -22,11 +34,13 @@ export declare class PostgreSQLProvider implements CoreComputeProvider {
     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;
     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;
     expandArray(arrayExpression: string, alias: string, column: string): {

package/dist/physical/provider.d.ts

@@ -1,5 +1,10 @@
 export type DataRow = Record<string, unknown>;
 export type SqlParameters = readonly unknown[];
+export type DatePart = 'second' | 'minute' | 'hour' | 'weekday' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+/** Module-augmentation seam for application-owned Provider kinds. */
+export interface ProviderKindExtensions {
+}
+export type ProviderKind = 'clickhouse' | 'databricks' | 'dameng' | 'doris' | 'duckdb' | 'gbase' | 'maxcompute' | 'mysql' | 'oracle' | 'postgresql' | 'snowflake' | 'sqlserver' | 'starrocks' | Extract<keyof ProviderKindExtensions, string>;
 export interface ProviderExecutionRequest {
     readonly sql: string;
     readonly parameters: SqlParameters;
@@ -12,6 +17,8 @@ export interface SqlRenderCapabilities {
     tableAlias(expression: string, alias: string): string;
     paginate(sql: string, pageSize: number, offset: number): string;
     dateBucket(expression: string, level: string): string;
+    /** Extract a numeric date component. weekday uses Monday=1 through Sunday=7. */
+    datePart(expression: string, part: DatePart): string;
     dateShift(expression: string, granularity: string, offset: number): string;
     datePeriodBoundary?(expression: string, granularity: string, boundary: 'start' | 'end'): string;
     /** Cast a bound literal to the semantic type required by the SQL expression. */
@@ -22,9 +29,13 @@ export interface SqlRenderCapabilities {
     stringify(expression: string): string;
     concat(expressions: readonly string[]): string;
     substring(expression: string, start: number, length: number): string;
+    /** Return the number of characters in a string expression. */
+    stringLength(expression: string): string;
     regex(expression: string, pattern: string, options?: string): string;
     /** Whether the dialect supports a WITH RECURSIVE subquery. */
     readonly supportsRecursiveCte?: boolean;
+    /** Recursive-term set operator. Defaults to UNION when omitted. */
+    readonly recursiveCteUnion?: 'UNION' | 'UNION ALL';
     arrayContains?(arrayExpression: string, valueExpression: string): string;
     expandArray?(arrayExpression: string, alias: string, column: string): {
         readonly joinSql: string;
@@ -35,7 +46,7 @@ export interface SqlRenderCapabilities {
  * Internal physical database contract used by the compiler and executor.
  */
 export interface CoreComputeProvider extends SqlRenderCapabilities {
-    readonly kind: 'clickhouse' | 'doris' | 'mysql' | 'oracle' | 'postgresql' | 'snowflake' | 'starrocks';
+    readonly kind: ProviderKind;
     /** Maximum items accepted by one SQL IN expression, when the dialect has a limit. */
     readonly maxInListItems?: number;
     parameter(index: number, value: unknown): string;

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

@@ -1,5 +1,4 @@
-import type { ConnectionOptions } from 'snowflake-sdk';
-import type { CoreComputeProvider, DataRow, ProviderExecutionRequest } from './provider';
+import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest } from './provider';
 type SnowflakeBind = string | number | boolean | null;
 export interface SnowflakeStatementLike {
     cancel(callback?: (error?: Error) => void): void;
@@ -13,9 +12,20 @@ export interface SnowflakeConnectionLike {
     }): SnowflakeStatementLike;
     destroy(callback: (error?: Error) => void): unknown;
 }
+export interface SnowflakeConnectionOptions {
+    readonly account?: string;
+    readonly username?: string;
+    readonly password?: string;
+    readonly warehouse?: string;
+    readonly database?: string;
+    readonly schema?: string;
+    readonly role?: string;
+    readonly authenticator?: string;
+    readonly [option: string]: unknown;
+}
 export interface SnowflakeProviderOptions {
     /** Options passed to snowflake-sdk's createConnection(). */
-    readonly connection?: ConnectionOptions;
+    readonly connection?: object;
     /** Injectable SDK connection used by tests or caller-managed connection factories. */
     readonly client?: SnowflakeConnectionLike;
 }
@@ -29,11 +39,13 @@ export declare class SnowflakeProvider implements CoreComputeProvider {
     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;
     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;
     expandArray(arrayExpression: string, alias: string, column: string): {

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

@@ -0,0 +1,65 @@
+import type { CoreComputeProvider, DataRow, DatePart, ProviderExecutionRequest } from './provider';
+type SQLServerBind = string | number | boolean | Date | Buffer | null;
+export interface SQLServerRequestLike {
+    input(name: string, value: SQLServerBind): this;
+    query(sql: string): Promise<{
+        readonly recordset?: unknown;
+    }>;
+    cancel(): void;
+}
+export interface SQLServerPoolLike {
+    connect(): Promise<unknown>;
+    request(): SQLServerRequestLike;
+    close(): Promise<void>;
+}
+export interface SQLServerDriverLike {
+    readonly ConnectionPool: new (options: object) => SQLServerPoolLike;
+}
+export interface SQLServerConnectionOptions {
+    readonly host?: string;
+    readonly server?: string;
+    readonly port?: number;
+    readonly user?: string;
+    readonly password?: string;
+    readonly database?: string;
+    readonly options?: Readonly<Record<string, unknown>>;
+    readonly pool?: Readonly<Record<string, unknown>>;
+    readonly requestTimeout?: number;
+    readonly connectionTimeout?: number;
+    readonly [option: string]: unknown;
+}
+export interface SQLServerProviderOptions {
+    readonly connection?: SQLServerConnectionOptions;
+    readonly pool?: SQLServerPoolLike;
+    readonly driver?: SQLServerDriverLike;
+}
+export declare const sqlServerPoolOptions: (connection: SQLServerConnectionOptions) => object;
+export declare class SQLServerProvider implements CoreComputeProvider {
+    #private;
+    readonly kind: "sqlserver";
+    readonly supportsHavingAlias = false;
+    constructor(options?: SQLServerProviderOptions);
+    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;
+    castValue(expression: string, type: 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;
+    expandArray(arrayExpression: string, alias: string, column: string): {
+        readonly joinSql: string;
+        readonly valueExpression: string;
+    };
+    execute(execution: ProviderExecutionRequest): Promise<DataRow[]>;
+    close(): Promise<void>;
+}
+export {};

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

@@ -1,6 +1,7 @@
 import { MySQLProtocolProvider } from './mysql-protocol-provider';
-import type { MySQLProtocolPoolLike, MySQLProtocolProviderOptions } from './mysql-protocol-provider';
+import type { MySQLProtocolPoolLike, MySQLProtocolConnectionOptions, MySQLProtocolProviderOptions } from './mysql-protocol-provider';
 export type StarRocksPoolLike = MySQLProtocolPoolLike;
+export type StarRocksConnectionOptions = MySQLProtocolConnectionOptions;
 export type StarRocksProviderOptions = MySQLProtocolProviderOptions;
 /** StarRocks adapter using its MySQL-compatible protocol and SQL surface. */
 export declare class StarRocksProvider extends MySQLProtocolProvider {

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) => QueryLineage;
+export declare const buildLineage: (plan: LogicalPlan, schema: ResolvedSemanticSchema, provider: CoreComputeProvider, operators?: OperatorRegistry, providerForConnection?: (connectionId: string) => CoreComputeProvider) => QueryLineage;

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

@@ -1,6 +1,8 @@
 import type { LogicformType } 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 { ResolvedSemanticProperty } from '../semantic-types/index';
 import { type PlannerSemanticRegistry } from './semantics/index';
@@ -8,8 +10,13 @@ import type { LogicalPlan } from './types';
 export declare const createResultSchema: (plan: LogicalPlan, sourceSchema: ResolvedSemanticSchema) => ResolvedSemanticSchema;
 export declare const createDerivedSourceSchema: (sourcePlan: LogicalPlan, outerSchema: ResolvedSemanticSchema) => ResolvedSemanticSchema;
 export interface CreateLogicalPlanOptions {
+    readonly plugins?: readonly SemanticDBPlugin[];
     readonly resolveSchema?: (schemaId: string) => ResolvedSemanticSchema;
+    /** Prefer physical mappings colocated with the execution's main connection. */
+    readonly preferredConnectionId?: string;
     readonly canUsePropertyRowIdentity?: (schema: ResolvedSemanticSchema, property: ResolvedSemanticProperty) => boolean;
     readonly semanticRegistry?: PlannerSemanticRegistry;
+    /** Observe each physical Schema mapping decision made during planning. */
+    readonly onSchemaMappingSelection?: (selection: SchemaMappingSelection) => void;
 }
 export declare const createLogicalPlan: (logicform: LogicformType, schema: ResolvedSemanticSchema, operators?: OperatorRegistry, schemaMappings?: SchemaMappingRegistry, options?: CreateLogicalPlanOptions) => LogicalPlan;

package/dist/planner/index.d.ts

@@ -1,7 +1,9 @@
 export { buildLineage } from './build-lineage';
 export { createDerivedSourceSchema, createLogicalPlan, createResultSchema } from './create-logical-plan';
 export type { CreateLogicalPlanOptions } from './create-logical-plan';
-export type { Expression, ArrayExpansionPlan, FieldReferencePlan, GroupLimitPlan, JoinPlan, LogicalQuerySubquery, LogicalRecursiveQuery, LogicalOrdinalQuery, LineageColumnSource, LineageOutput, LogicalPlan, OrderPlan, ObservationPeriodPlan, PaginationPlan, ProjectionPlan, QueryLineage, RowIdentityPlan, ValidityPeriodPlan, } from './types';
-export { isLogicalQuerySubquery, isLogicalRecursiveQuery } from './types';
+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 { isLogicalQuerySubquery, isLogicalQueryOperator } from './types';
 export { isLogicalOrdinalQuery } from './types';
+export { isLogicalExpressionQuery } from './types';
 export * from './semantics/index';
+export { createPlannerSemanticRegistry } from './semantics/registry-defaults';

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

@@ -0,0 +1,7 @@
+import type { LogicformType } from '../logicform-types';
+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. */
+export declare const mappingGranularityReason: (logicform: LogicformType, schema: ResolvedSemanticSchema, mapping: SchemaMappingDefinition, resolveSchema?: (schemaId: string) => ResolvedSemanticSchema, plugins?: readonly SemanticDBPlugin[], operators?: OperatorRegistry) => string | undefined;

package/dist/planner/rewrite-nested-components.d.ts

@@ -0,0 +1,8 @@
+import type { LogicformType } from '../logicform-types';
+import type { OperatorRegistry } from '../operators/index';
+/**
+ * Lift component inputs into a derived LogicForm so ordinary expression operators can consume
+ * their result columns. The inner LogicForm owns source-grain work; the outer LogicForm owns
+ * result operations and the expression path above every component.
+ */
+export declare const rewriteNestedComponents: (logicform: LogicformType, operators: OperatorRegistry) => LogicformType | undefined;

package/dist/planner/select-schema-mapping.d.ts

@@ -1,6 +1,8 @@
 import type { LogicformType } from '../logicform-types';
-import type { SchemaMappingDefinition, SchemaMappingRegistry } from '../schema-mappings/index';
+import type { SemanticDBPlugin } from '../plugins/index';
+import type { SchemaMappingDefinition, SchemaMappingRegistry, SchemaMappingSelection } from '../schema-mappings/index';
 import type { ResolvedSemanticSchema } from '../semantic-types/index';
+import { type OperatorRegistry } from '../operators/index';
 export interface PredMappingRewrite {
     readonly predIndex: number;
     readonly column: string;
@@ -9,6 +11,18 @@ export interface SelectedSchemaMapping {
     readonly mapping: SchemaMappingDefinition;
     readonly logicform: LogicformType;
     readonly predRewrites: readonly PredMappingRewrite[];
+    readonly selection: SchemaMappingSelection;
+}
+export interface MappedPropertySource {
+    readonly column: string;
+    readonly sourceRef?: string;
 }
 export declare const mappedPropertyColumn: (mapping: SchemaMappingDefinition, schema: ResolvedSemanticSchema, reference: string) => string | undefined;
-export declare const selectSchemaMapping: (logicform: LogicformType, schema: ResolvedSemanticSchema, mappings: SchemaMappingRegistry) => SelectedSchemaMapping;
+export declare const mappedPropertySource: (mapping: SchemaMappingDefinition, schema: ResolvedSemanticSchema, reference: string) => MappedPropertySource | undefined;
+export declare const selectSchemaMapping: (logicform: LogicformType, schema: ResolvedSemanticSchema, mappings: SchemaMappingRegistry, options?: {
+    readonly preferredConnectionId?: string;
+    readonly resolveSchema?: (schemaId: string) => ResolvedSemanticSchema;
+    /** Extra plugins used by this execution; must also be supplied when registering plugin grains. */
+    readonly plugins?: readonly SemanticDBPlugin[];
+    readonly operators?: OperatorRegistry;
+}) => SelectedSchemaMapping;

package/dist/planner/semantics/index.d.ts

@@ -1,6 +1,2 @@
-export * from './observation/index';
-export * from './validity/index';
-export * from './lifecycle/index';
 export { PlannerSemanticRegistry } from './registry';
 export type { PlannerSemanticResolution, PlannerSemanticQueryContext, PlannerSemanticRule, PlannerSemanticRuleContext, } from './registry';
-export { createPlannerSemanticRegistry } from './registry-defaults';

package/dist/planner/semantics/periods.d.ts

@@ -0,0 +1,13 @@
+import type { TimeGranularity } from '../../semantic-types/index';
+export interface Period {
+    readonly label: string;
+    readonly start: string;
+    readonly end: string;
+}
+export interface PeriodErrorContext {
+    readonly codePrefix: string;
+    readonly label: string;
+}
+export declare const isTimeGranularity: (value: unknown) => value is TimeGranularity;
+/** Expand one bounded time condition into natural boundaries at the requested granularity. */
+export declare const resolvePeriods: (condition: unknown, granularity: TimeGranularity, context: PeriodErrorContext) => readonly Period[];

package/dist/planner/semantics/registry-defaults.d.ts

@@ -1,2 +1,3 @@
 import { PlannerSemanticRegistry } from './registry';
-export declare const createPlannerSemanticRegistry: () => PlannerSemanticRegistry;
+import type { SemanticDBPlugin } from '../../plugins/index';
+export declare const createPlannerSemanticRegistry: (plugins?: readonly SemanticDBPlugin[]) => PlannerSemanticRegistry;

package/dist/planner/types.d.ts

@@ -2,6 +2,7 @@ import type { CoreComputeProvider } from '../physical/index';
 import type { LogicformType } from '../logicform-types';
 import type { ResultProperty } from '../operators/index';
 import type { ComparableCategoryDefinition, TimeGranularity } from '../semantic-types/index';
+import type { QueryOperatorDefinition } from '../plugins/index';
 export interface FieldReferencePlan {
     readonly schemaId: string;
     readonly property: string;
@@ -20,24 +21,33 @@ export interface LogicalQuerySubquery {
     readonly kind: 'logicform-subquery';
     readonly plan: LogicalPlan;
 }
-export interface LogicalRecursiveQuery {
-    readonly kind: 'recursive-query';
-    readonly schemaId: string;
-    readonly source: string;
-    readonly sourceSql?: string;
-    readonly idColumn: string;
-    readonly parentColumn: string;
-    readonly roots: readonly unknown[];
-    readonly includeSelf: boolean;
+export interface LogicalQueryOperator {
+    readonly kind: 'query-operator';
+    readonly operator: string;
+    readonly value: unknown;
+    readonly sources?: readonly {
+        readonly schemaId: string;
+        readonly source: string;
+        readonly connectionId?: string;
+    }[];
+    /** Capability selected during planning; omitted only by manually constructed plans. */
+    readonly definition?: QueryOperatorDefinition;
 }
 export interface LogicalOrdinalQuery {
     readonly kind: 'ordinal-query';
     readonly comparable: ComparableCategoryDefinition;
     readonly condition: unknown;
 }
+export interface LogicalExpressionQuery {
+    readonly kind: 'expression-query';
+    readonly expression: Expression;
+    readonly condition: unknown;
+    readonly properties: readonly string[];
+}
 export declare const isLogicalQuerySubquery: (value: unknown) => value is LogicalQuerySubquery;
-export declare const isLogicalRecursiveQuery: (value: unknown) => value is LogicalRecursiveQuery;
+export declare const isLogicalQueryOperator: (value: unknown) => value is LogicalQueryOperator;
 export declare const isLogicalOrdinalQuery: (value: unknown) => value is LogicalOrdinalQuery;
+export declare const isLogicalExpressionQuery: (value: unknown) => value is LogicalExpressionQuery;
 export type Expression = {
     readonly kind: 'array-element';
     readonly schemaId: string;
@@ -111,20 +121,45 @@ export interface JoinPlan {
     readonly sourceColumn: string;
     readonly sourceSql?: string;
     readonly sourceTimestampColumn?: string;
-    readonly sourceTimestampGranularity?: TimeGranularity;
     readonly targetSchemaId: string;
+    /** Physical connection selected for the target Schema mapping. */
+    readonly targetConnectionId?: string;
     readonly targetSource: string;
     readonly targetSourceSql?: string;
     readonly targetAlias: string;
     readonly targetColumn: string;
     readonly targetSql?: string;
     readonly targetTimestampColumn?: string;
-    readonly targetTimestampGranularity?: TimeGranularity;
-    /** Half-open validity interval columns on a versioned entity target. */
-    readonly targetValidityStartColumn?: string;
-    readonly targetValidityEndColumn?: string;
+    readonly temporalCondition?: TemporalJoinConditionPlan;
     readonly sourceArrayExpansionPath?: string;
 }
+export type TemporalJoinConditionPlan = {
+    readonly kind: 'date-bucket-equal';
+    readonly sourceColumn: string;
+    readonly targetColumn: string;
+    readonly sourceGranularity: TimeGranularity;
+    readonly targetGranularity: TimeGranularity;
+} | {
+    readonly kind: 'point-in-interval';
+    readonly pointSide: 'source' | 'target';
+    readonly pointColumn: string;
+    readonly intervalSide: 'source' | 'target';
+    readonly startColumn: string;
+    readonly endColumn: string;
+};
+export interface EnrichmentJoinPlan {
+    readonly kind: 'enrichment-left';
+    readonly id: string;
+    readonly source: string;
+    readonly sourceSql?: string;
+    readonly alias: string;
+    readonly baseAlias: string;
+    readonly keys: readonly {
+        readonly baseColumn: string;
+        readonly targetColumn: string;
+    }[];
+    readonly temporalCondition?: TemporalJoinConditionPlan;
+}
 export interface ArrayExpansionPlan {
     readonly path: string;
     readonly sourceAlias: string;
@@ -147,29 +182,24 @@ export interface GroupLimitPlan {
     readonly partitionBy: readonly string[];
     readonly orderBy: readonly OrderPlan[];
 }
-export interface ValidityPeriodPlan {
-    readonly alias: string;
-    readonly labelColumn: string;
-    readonly asOfColumn: string;
-    readonly sourceAlias: string;
-    readonly startColumn: string;
-    readonly endColumn: string;
-    readonly periods: readonly {
-        readonly label: string;
-        readonly asOf: string;
-    }[];
-}
-export interface ObservationPeriodPlan {
+export interface PeriodSourcePlan {
     readonly alias: string;
     readonly labelColumn: string;
     readonly asOfColumn: string;
     readonly sourceAlias: string;
-    readonly lookupAlias: string;
-    readonly timestampColumn: string;
     readonly periods: readonly {
         readonly label: string;
         readonly asOf: string;
     }[];
+    readonly match: {
+        readonly kind: 'interval';
+        readonly startColumn: string;
+        readonly endColumn: string;
+    } | {
+        readonly kind: 'latest';
+        readonly lookupAlias: string;
+        readonly timestampColumn: string;
+    };
 }
 export type RowIdentityPlan = {
     readonly kind: 'group';
@@ -188,6 +218,8 @@ export type RowIdentityPlan = {
 export interface LogicalPlan {
     readonly schemaId: string;
     readonly source: string;
+    /** Physical connection selected for this plan's source mapping. */
+    readonly connectionId?: string;
     /** Trusted derived-table SQL supplied by the selected physical mapping. */
     readonly sourceSql?: string;
     /** Physical mapping selected by the Planner for this logical Schema. */
@@ -202,11 +234,11 @@ export interface LogicalPlan {
     readonly fields: Readonly<Record<string, string>>;
     readonly fieldReferences?: Readonly<Record<string, FieldReferencePlan>>;
     readonly joins?: readonly JoinPlan[];
+    /** Physical extensions of this mapping, added only when a mapped property uses them. */
+    readonly enrichmentJoins?: readonly EnrichmentJoinPlan[];
     readonly arrayExpansions?: readonly ArrayExpansionPlan[];
-    /** Period spine used to evaluate a valid-time entity once per requested period. */
-    readonly validityPeriods?: ValidityPeriodPlan;
-    /** Period spine used to select the latest snapshot at each requested boundary. */
-    readonly observationPeriods?: ObservationPeriodPlan;
+    /** Generated period rows matched to a source by a plugin-selected generic strategy. */
+    readonly periodSource?: PeriodSourcePlan;
     readonly projections: readonly ProjectionPlan[];
     readonly columnProperties?: readonly ResultProperty[];
     readonly groupBy: readonly ProjectionPlan[];
@@ -235,6 +267,11 @@ export interface QueryLineage {
         readonly schemaName: string;
         readonly physicalTable: string;
         readonly provider: CoreComputeProvider['kind'];
+        readonly connectionId?: string;
+        readonly connections?: readonly {
+            readonly connectionId: string;
+            readonly provider: CoreComputeProvider['kind'];
+        }[];
     };
     readonly outputs: readonly LineageOutput[];
     readonly filters: readonly LineageColumnSource[];

package/dist/plugins/hierarchy/index.d.ts

@@ -1,3 +1,3 @@
 import type { SemanticDBPlugin } from '../types';
-export type { HierarchyDefinition, HierarchyLevelDefinition, ResolvedHierarchyDefinition, } from './types';
+export type { HierarchyDefinition, HierarchyLevelDefinition, ResolvedHierarchyDefinition, SchemaMappingHierarchyGranularity, } from './types';
 export declare const hierarchyPlugin: SemanticDBPlugin;

package/dist/plugins/hierarchy/mapping-granularity.d.ts

@@ -0,0 +1,4 @@
+import type { MappingGranularityPlugin } from '../types';
+import type { SchemaMappingHierarchyGranularity } from './types';
+export declare const isMappingHierarchyGranularity: (value: unknown) => value is SchemaMappingHierarchyGranularity;
+export declare const hierarchyMappingGranularity: MappingGranularityPlugin;

package/dist/plugins/hierarchy/types.d.ts

@@ -1,3 +1,13 @@
+export interface SchemaMappingHierarchyGranularity {
+    readonly kind: 'hierarchy';
+    /** Physical level name or synonym declared by the referenced hierarchy Schema. */
+    readonly level: string;
+}
+declare module '../../schema-mappings/types' {
+    interface SchemaMappingGranularityExtensions {
+        readonly hierarchy: SchemaMappingHierarchyGranularity;
+    }
+}
 export interface HierarchyLevelDefinition {
     readonly name: string;
     readonly syno?: readonly string[];
@@ -17,6 +27,13 @@ export interface ResolvedHierarchyDefinition extends Omit<HierarchyDefinition, '
     readonly storage: 'compact' | 'zero-padded';
 }
 declare module '../../semantic-types/types' {
+    interface SemanticPropertyDraft {
+        /** Default hierarchy level for an Entity relation. */
+        readonly level?: string;
+    }
+    interface ResolvedSemanticProperty {
+        readonly level?: string;
+    }
     interface SemanticSchemaMetadata {
         readonly hierarchy?: HierarchyDefinition;
     }

package/dist/plugins/index.d.ts

@@ -1,5 +1,14 @@
 import type { SemanticDBPlugin } from './types';
-export type { LegacySchemaPluginContext, SchemaMetadataPlugin, SemanticDBPlugin } from './types';
+import type { LogicformType } from '../logicform-types';
+import type { ResolvedSemanticSchema } from '../semantic-types/index';
+export type { LegacySchemaPluginContext, MappingGranularityContext, MappingGranularityPlugin, QueryOperatorAuthorizeContext, QueryOperatorCompileContext, QueryOperatorDefinition, QueryOperatorNormalizeContext, QueryOperatorPhysicalSource, QueryOperatorPlanContext, QueryOperatorPlanResult, PropertyMetadataPlugin, SchemaMetadataPlugin, SemanticDBPlugin, OutputHandlerContext, OutputHandlerDefinition, IntervalSemanticProperties, IntervalSemanticsDefinition, PlannerPeriodDefinition, PlannerPeriodEvaluation, RelationSemanticsDefinition, RelationTemporalPlan, TimeWatermarkLogicformContext, SchemaMappingPlugin, } from './types';
+export type { SchemaMappingHierarchyGranularity } from './hierarchy/index';
+export type { RecursiveQueryType } from './recursive/index';
 /** Built-in capabilities are composed here; feature implementations live in their own folders. */
 export declare const builtinPlugins: readonly SemanticDBPlugin[];
 export declare const resolvePlugins: (plugins?: readonly SemanticDBPlugin[]) => readonly SemanticDBPlugin[];
+export declare const findQueryOperator: (name: string, plugins?: readonly SemanticDBPlugin[]) => import("./types").QueryOperatorDefinition | undefined;
+export declare const findOutputHandler: (type: string, plugins?: readonly SemanticDBPlugin[]) => import("./types").OutputHandlerDefinition | undefined;
+export declare const resolveIntervalSemanticProperties: (schema: ResolvedSemanticSchema, plugins?: readonly SemanticDBPlugin[]) => import("./types").IntervalSemanticProperties | undefined;
+export declare const resolveRelationTemporalPlan: (sourceSchema: ResolvedSemanticSchema, targetSchema: ResolvedSemanticSchema, plugins?: readonly SemanticDBPlugin[]) => import("./types").RelationTemporalPlan | undefined;
+export declare const resolvePlannerPeriodEvaluation: (logicform: LogicformType, schema: ResolvedSemanticSchema, plugins?: readonly SemanticDBPlugin[]) => import("./types").PlannerPeriodEvaluation | undefined;

package/dist/{planner/semantics → plugins}/observation/classification.d.ts

@@ -1,3 +1,3 @@
-import type { ResolvedSemanticProperty, ResolvedSemanticSchema } from '../../../semantic-types/index';
+import type { ResolvedSemanticProperty, ResolvedSemanticSchema } from '../../semantic-types/index';
 export declare const isObservationProperty: (property: ResolvedSemanticProperty | undefined, schema?: Pick<ResolvedSemanticSchema, "temporalSemantics">) => boolean;
 export declare const observationProperties: (schema: Pick<ResolvedSemanticSchema, "properties" | "temporalSemantics">) => readonly ResolvedSemanticProperty[];

package/dist/plugins/observation/index.d.ts

@@ -0,0 +1,17 @@
+import type { SemanticDBPlugin } from '../types';
+type SchemaTemporalSemantics = 'normal' | 'snapshot';
+export { isObservationProperty, observationProperties } from './classification';
+export { resolveObservationOperatorPolicy, type ObservationOperatorPolicy, } from './operator-policy';
+export { removeObservationTimeCondition, resolveObservationPeriodSpec, } from './periods';
+export type { ObservationPeriodMetric, ObservationPeriodSpec } from './periods';
+export { observationSemanticRule } from './rule';
+export type { ObservationOperator, ObservationTemporalMetadata } from './types';
+declare module '../../semantic-types/types' {
+    interface SemanticSchemaMetadata {
+        readonly temporalSemantics?: SchemaTemporalSemantics;
+    }
+    interface ResolvedSemanticSchemaMetadata {
+        readonly temporalSemantics?: SchemaTemporalSemantics;
+    }
+}
+export declare const observationPlugin: SemanticDBPlugin;