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

package/README.md

@@ -34,8 +34,9 @@ const response = await Logicform.execute(
     connections: [{
       id: 'analytics',
       kind: 'clickhouse',
-      url: 'http://localhost:8123',
-      username: 'default',
+      host: 'localhost',
+      port: 8123,
+      user: 'default',
       password: process.env.CLICKHOUSE_PASSWORD,
       database: 'analytics',
     }],
@@ -56,19 +57,28 @@ query shaped as `{ schema, query }` is part of its parent LogicForm and inherits
 
 PredItems without an explicit `name` receive a human-readable name during normalization. Generated
 names default to Chinese; pass `locale: 'en-US'` in `ExecuteOptions` for the built-in English
-names. Every operator owns its localized default names and receives the requested locale directly:
+names. SemanticDB ships `zh-CN` and `en-US` locale files backed by i18next. Applications can add or
+override locale files through `ExecuteOptions.locales`:
 
 ```ts
-operators.register({
-  name: '$weightedAverage',
-  defaultName: ({ operandName, locale }) => locale.toLowerCase().startsWith('en')
-    ? `Weighted average of ${operandName}`
-    : `${operandName}加权平均值`,
-  kind: 'aggregate',
-  toSQL: ({ column }) => `weighted_avg(${column})`,
+await Logicform.execute(logicform, {
+  locale: 'ja-JP',
+  locales: {
+    locale: 'ja-JP',
+    messages: {
+      'operator.$sum': '{operandName}の合計',
+      'component.numerator': '{outputName} 分子',
+      'component.denominator': '{outputName} 分母',
+    },
+  },
+  // schemas, schemaMappings, connections, ...
 });
 ```
 
+Locale lookup uses the exact locale first, then the matching language, and finally `zh-CN`.
+Multiple locale files can be supplied as an array. A custom operator still owns its fallback name
+through `defaultName()` and can call the context's `t()` helper when it defines translation keys.
+
 The same locale applies to `preds`, `groupby`, nested expressions, custom-function subqueries,
 and entity-population queries. A PredItem's normalized `query` is included in its
 generated name, for example `门店为上海的销售额合计`. Operator-specific `args` also participate
@@ -181,6 +191,12 @@ Composite metrics are regular `OperatorDefinition` values with `kind: 'component
 them in the same `OperatorRegistry` as scalar and aggregate operators. Operator names are free-form;
 the `$` prefix is a convention used by built-in operators, not a requirement.
 
+Every composite component is exposed in result rows by default. Its `name` is its final result-column
+name and may contain Chinese characters or spaces. Built-ins derive child names from the parent output,
+for example `总销售额占比分子` and `总销售额占比分母`. Operators do not return `outputName` or an
+exposure flag; the executor owns the parent output binding. Components are joined on groupby output
+names shared by both sides unless an exceptional custom operator explicitly supplies `joinKeys`.
+
 See [Register an operator](docs/register-operator.md) for the component contract.
 
 The root entry point accepts a `connections` array of `DatabaseConnection` items. Every item has a unique `id`; set `kind` to `mysql`,

package/dist/compiler/compile-cte.d.ts

@@ -24,4 +24,4 @@ export interface PreparedCteQuery {
  * CTE preserves those ranges while allowing the provider to execute one query.
  */
 export declare const compileCteQueries: (units: readonly PreparedCteQuery[], outputPlan: LogicalPlan, provider: CoreComputeProvider, operators?: OperatorRegistry) => CompiledQuery;
-export declare const compileCteCalculation: (calculation: OperatorComponentCalculation, components: readonly PreparedCteComponent[], outputPlan: LogicalPlan, provider: CoreComputeProvider, operators: OperatorRegistry) => CompiledQuery;
+export declare const compileCteCalculation: (calculation: OperatorComponentCalculation, components: readonly PreparedCteComponent[], outputPlan: LogicalPlan, outputName: string, provider: CoreComputeProvider, operators: OperatorRegistry) => CompiledQuery;

package/dist/errors.d.ts

@@ -1,7 +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): string;
+    localizedMessage(locale?: string, locales?: LocaleRegistry): string;
 }

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/fetch-entities.d.ts

@@ -9,10 +9,12 @@ 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 { 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[];

package/dist/executor/types.d.ts

@@ -1,4 +1,4 @@
-import type { OperatorRegistry } from '../operators/index';
+import type { OperatorDefinition, OperatorRegistry } from '../operators/index';
 import type { CoreComputeProvider, DataRow, SqlParameters } from '../physical/index';
 import type { DatabaseConnection } from '../physical/index';
 import type { LogicalPlan, QueryLineage } from '../planner/index';
@@ -8,6 +8,7 @@ import type { LogicformType, PublicLogicformType } from '../logicform-types';
 import type { QueryCacheExecutionOptions } from '../cache/index';
 import type { Permissions } from '../permissions/index';
 import type { SemanticDBPlugin } from '../plugins/index';
+import type { LocaleInput, LocaleRegistry } from '../i18n/index';
 export type ExecuteProgressEvent = {
     readonly stage: 'started';
     readonly logicform: LogicformType;
@@ -56,11 +57,14 @@ export type ProgressCallback = (event: ExecuteProgressEvent) => void | Promise<v
 interface ExecuteBaseOptions {
     readonly schemas: Readonly<Record<string, SemanticSchemaDraft>>;
     readonly semanticTypes?: SemanticTypeRegistry;
-    readonly operators?: OperatorRegistry;
+    /** Caller-defined operators supplied as plain definition objects. */
+    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;
     /** Optional caller-owned cache shared across executions. */
@@ -77,7 +81,9 @@ export interface ExecuteOptions extends ExecuteBaseOptions {
     readonly connections: readonly DatabaseConnection[];
 }
 /** 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;
+    readonly localeRegistry?: LocaleRegistry;
     readonly provider: CoreComputeProvider;
     readonly schemaMappings: SchemaMappingRegistry;
     /** Selected connection for public execution; omitted only by internal provider tests. */

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,17 +1,19 @@
+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>;
 }>;
 export { SemanticDBError } from './errors';
 export { builtinSemanticTypes, createSemanticTypeRegistry, resolveSchema, SemanticTypeRegistry, validateResolvedSchema, } from './semantic-types/index';
-export { builtinOperators, createOperatorRegistry, OperatorRegistry, } from './operators/index';
+export { builtinOperators, createOperatorRegistry, OperatorRegistry, resolveOperator, } from './operators/index';
 export type { LegacySchemaPluginContext, SchemaMetadataPlugin, SemanticDBPlugin, } from './plugins/index';
 export { SchemaMappingRegistry, fromYiAskSchemaMapping, } from './schema-mappings/index';
 export type { AbsoluteDateValue, CompareOperator, CalendarDateValue, DateTimeValue, DateValue, EntityIdType, ExpressionItemType, LogicformType, PublicLogicformType, 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, TimeWatermarkPolicy, } from './semantic-types/index';
+export type { PrimalType, PropertyHierarchyDefinition, PropertySqlDefinition, ResolvedSemanticProperty, ResolvedSemanticSchema, SemanticTypeNormalizeContext, SemanticPropertyDraft, SemanticSchemaDraft, SemanticTypeDefinition, SemanticTypeResultContext, SemanticTypeResultProperty, TemporalSemantics, TimeGranularity, TimeWatermarkPolicy, } 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, OperatorComponentCalculation, OperatorComponentQuery, OperatorExecutionComponent, OperatorPlanInputContext, OperatorPlannedInput, OperatorGroupKeyShift, OperatorJavaScriptCalculation, OperatorQueryComponent, OperatorEvaluateContext, OperatorOutputPropertyContext, OperatorSqlCapabilities, OperatorSqlContext, ResultProperty, ResultPropertyTemporalMetadata, } from './operators/index';

package/dist/normalizer/core.d.ts

@@ -2,12 +2,17 @@ import type { LogicformType } from '../logicform-types';
 import type { OperatorRegistry } from '../operators/index';
 import type { ResolvedSemanticProperty, ResolvedSemanticSchema, SemanticTypeRegistry } from '../semantic-types/index';
 import type { SemanticDBPlugin } from '../plugins/index';
+import type { LocaleInput, LocaleRegistry } from '../i18n/index';
 export interface NormalizeLogicformOptions {
     readonly semanticTypes: SemanticTypeRegistry;
     readonly operators?: OperatorRegistry;
     readonly plugins?: readonly SemanticDBPlugin[];
     /** Locale used for generated human-readable PredItem names. Defaults to zh-CN. */
     readonly locale?: string;
+    /** Additional or overriding locale files used for generated names. */
+    readonly locales?: LocaleInput;
+    /** Internal registry shared by recursive normalization calls. */
+    readonly localeRegistry?: LocaleRegistry;
     readonly now?: Date;
     readonly resolveSchema?: (schemaId: string) => ResolvedSemanticSchema;
     readonly requestTimeWatermark?: (schema: ResolvedSemanticSchema, property: ResolvedSemanticProperty, requestedUpperBound: Date) => Promise<Date | undefined>;

package/dist/normalizer/default-pred-name.d.ts

@@ -1,6 +1,8 @@
 import type { PredItemType } from '../logicform-types';
 import type { OperatorRegistry } from '../operators/index';
+import { type LocaleRegistry } from '../i18n/index';
 export interface DefaultPredNameOptions {
     readonly locale?: string;
+    readonly localeRegistry?: LocaleRegistry;
 }
 export declare const defaultPredName: (pred: PredItemType, operators: OperatorRegistry, options?: DefaultPredNameOptions) => string;

package/dist/normalizer/index.d.ts

@@ -1,3 +1,4 @@
 export { normalizeLogicform } from './normalize-logicform';
 export { defaultPredName } from './default-pred-name';
 export { assertSupportedLogicformVersion } from './version';
+export { inferPropertyResolvePath } from './property-resolve';

package/dist/normalizer/property-resolve.d.ts

@@ -1,5 +1,6 @@
 import type { LogicformType } from '../logicform-types';
 import type { ResolvedSemanticSchema } from '../semantic-types/index';
 import type { NormalizeLogicformOptions } from './core';
+export declare const inferPropertyResolvePath: (rootSchema: ResolvedSemanticSchema, reference: string, targetSchema: ResolvedSemanticSchema, resolveSchema?: (schemaId: string) => ResolvedSemanticSchema) => string | undefined;
 /** Adds cross-Schema aliases after both legacy and v2 forms share normalization. */
 export declare const normalizePropertyResolve: (logicform: LogicformType, rootSchema: ResolvedSemanticSchema, options: NormalizeLogicformOptions) => LogicformType;

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

@@ -1 +1,2 @@
-export declare const periodComparisonName: (args: Readonly<Record<string, unknown>>, locale: string) => string;
+import type { LocaleTranslate } from '../../i18n/index';
+export declare const periodComparisonName: (args: Readonly<Record<string, unknown>>, locale: string, t?: LocaleTranslate) => string;

package/dist/operators/index.d.ts

@@ -1,6 +1,7 @@
 import type { SemanticDBPlugin } from '../plugins/index';
 import { OperatorRegistry } from './registry';
 export { OperatorRegistry } from './registry';
+export { resolveOperator } from './resolve';
 export { bindTrustedSqlExpression } from './sql-expression';
 export type { OperatorDefinition, OperatorDefaultNameContext, OperatorComponentContext, OperatorComponentCalculation, OperatorComponentQuery, OperatorExecutionComponent, OperatorGroupKeyShift, OperatorJavaScriptCalculation, OperatorQueryComponent, OperatorEvaluateContext, OperatorOutputPropertyContext, OperatorObservationPolicy, OperatorObservationPolicyContext, OperatorNormalizePredContext, OperatorPlanExpressionContext, OperatorPeriodEvaluationContext, OperatorPlanInputContext, OperatorPlannedInput, OperatorRewriteLogicformContext, OperatorValidatePlanContext, OperatorSqlCapabilities, OperatorSqlContext, ResultProperty, ResultPropertyTemporalMetadata, } from './types';
 export declare const builtinOperators: readonly import("./types").OperatorDefinition[];

package/dist/operators/registry.d.ts

@@ -2,7 +2,7 @@ import type { OperatorDefinition, OperatorPeriodEvaluationContext } from './type
 export declare class OperatorRegistry {
     #private;
     constructor(definitions?: readonly OperatorDefinition[]);
-    register(definition: OperatorDefinition): this;
+    register(input: OperatorDefinition): this;
     get(name: string): OperatorDefinition;
     requiresPerPeriodEvaluation(name: string, context: OperatorPeriodEvaluationContext): boolean;
     has(name: string): boolean;

package/dist/operators/resolve.d.ts

@@ -0,0 +1,3 @@
+import type { OperatorDefinition } from './types';
+/** Resolve an operator definition loaded from JSON or another untyped source. */
+export declare const resolveOperator: (input: unknown) => OperatorDefinition;

package/dist/operators/types.d.ts

@@ -2,6 +2,7 @@ import type { PrimalType, ResolvedSemanticProperty, ResolvedSemanticSchema, Time
 import type { LogicformType, PredItemType } from '../logicform-types';
 import type { DataRow } from '../physical/index';
 import type { Expression } from '../planner/index';
+import type { LocaleTranslate } from '../i18n/index';
 export interface OperatorSqlCapabilities {
     /** Produce a dialect-specific aggregate function around an expression. */
     aggregateFunction(name: string, expression?: string): string;
@@ -13,8 +14,10 @@ export interface OperatorSqlCapabilities {
     dateShift(expression: string, granularity: TimeGranularity, offset: number): string;
     /** Render a period boundary directly when the dialect has a concise native form. */
     datePeriodBoundary?(expression: string, granularity: TimeGranularity, boundary: 'start' | 'end'): string;
+    /** Render a NULL-ignoring scalar extremum using a dialect-native expression. */
+    scalarExtremum?(operator: 'least' | 'greatest', expressions: readonly string[]): string;
     /** Bind a literal as a SQL parameter. */
-    value(value: unknown): string;
+    value(value: unknown, type?: string): string;
     /** Compile a field-local LogicForm condition against an expression. */
     condition(expression: string, condition: unknown): string;
 }
@@ -51,7 +54,7 @@ export interface ResultProperty {
     readonly temporal?: ResultPropertyTemporalMetadata;
 }
 export interface ResultPropertyTemporalMetadata {
-    readonly kind: 'period-boundary' | 'period-shift' | 'date-bucket' | 'lifecycle';
+    readonly kind: 'period-boundary' | 'period-shift' | 'date-bucket' | 'validity' | 'lifecycle';
     readonly boundary?: 'start' | 'end';
     readonly sourceProperty?: string;
     readonly requestedRange?: {
@@ -100,8 +103,10 @@ export interface OperatorDefaultNameContext {
     readonly inputNames: readonly string[];
     /** Operator-specific LogicForm arguments. */
     readonly args: Readonly<Record<string, unknown>>;
-    /** Requested locale. Each operator owns its own localized default names. */
+    /** Requested locale for generated names. */
     readonly locale: string;
+    /** Translate a stable message key using the requested locale. */
+    readonly t?: LocaleTranslate;
 }
 export interface OperatorPlanInputContext {
     /** Canonical property or relation reference supplied as this operator's direct pred. */
@@ -158,6 +163,10 @@ export interface OperatorComponentContext {
     readonly pred: PredItemType;
     /** Final output alias assigned by the planner. */
     readonly outputName: string;
+    /** Requested locale for child component names. */
+    readonly locale: string;
+    /** Translate a stable message key using the requested locale. */
+    readonly t: LocaleTranslate;
     readonly schema: ResolvedSemanticSchema;
     /** Resolve Schemas referenced by object relation paths used by this component. */
     readonly resolveSchema: (schemaId: string) => ResolvedSemanticSchema;
@@ -179,27 +188,27 @@ export interface OperatorQueryComponent {
     readonly groupKeyShifts?: readonly OperatorGroupKeyShift[];
 }
 export interface OperatorComponentQuery {
+    /** Final result-column name for this child component. */
     readonly name: string;
     readonly logicform: LogicformType;
     readonly prepare?: boolean;
     readonly mapResult?: (rows: readonly DataRow[]) => DataRow[];
     readonly groupKeyShifts?: readonly OperatorGroupKeyShift[];
-    /** Group output names used to join this component back to the first component. */
+    /**
+     * 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[];
 }
 export interface OperatorComponentCalculation {
     readonly components: readonly OperatorComponentQuery[];
     /** Provider-independent formula referring to component names. */
     readonly expression: string;
-    readonly outputName?: string;
-    readonly exposeComponents?: boolean;
 }
 export interface OperatorJavaScriptCalculation {
     readonly kind: 'js';
     readonly components: readonly OperatorComponentQuery[];
-    readonly outputName: string;
     readonly mergeRow: (values: DataRow) => unknown;
-    readonly exposeComponents?: boolean;
 }
 export type OperatorExecutionComponent = OperatorQueryComponent | OperatorComponentCalculation | OperatorJavaScriptCalculation;
 /**

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

@@ -12,8 +12,14 @@ export interface ClickHouseClientLike {
     close(): Promise<void>;
 }
 export interface ClickHouseProviderOptions {
+    /** Full HTTP endpoint. Takes precedence over host and port. */
     readonly url?: string;
+    /** Host-style connection fields accepted by the shared datasource contract. */
+    readonly host?: string;
+    readonly port?: number;
     readonly username?: string;
+    /** Alias used by the shared datasource contract. username takes precedence. */
+    readonly user?: string;
     readonly password?: string;
     readonly database?: string;
     readonly client?: ClickHouseClientLike;
@@ -29,6 +35,8 @@ export declare class ClickHouseProvider implements CoreComputeProvider {
     displayQuery(sql: string, parameters: readonly unknown[]): string;
     dateBucket(expression: string, level: string): string;
     dateShift(expression: string, granularity: string, offset: number): 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;

package/dist/physical/provider.d.ts

@@ -14,6 +14,10 @@ export interface SqlRenderCapabilities {
     dateBucket(expression: string, level: string): 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. */
+    castValue?(expression: string, type: string): string;
+    /** Render a NULL-ignoring scalar extremum without a correlated subquery. */
+    scalarExtremum?(operator: 'least' | 'greatest', expressions: readonly string[]): string;
     aggregateFunction(name: string, expression?: string): string;
     stringify(expression: string): string;
     concat(expressions: readonly string[]): string;

package/dist/planner/index.d.ts

@@ -1,7 +1,7 @@
 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, PaginationPlan, ProjectionPlan, QueryLineage, RowIdentityPlan, } from './types';
+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 { isLogicalOrdinalQuery } from './types';
 export * from './semantics/index';

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

@@ -0,0 +1,11 @@
+export interface AnnualPeriod {
+    readonly label: string;
+    readonly start: string;
+    readonly end: string;
+}
+export interface AnnualPeriodErrorContext {
+    readonly codePrefix: 'VALIDITY' | 'OBSERVATION';
+    readonly label: string;
+}
+/** Expand one bounded time condition into natural-year boundaries. */
+export declare const resolveAnnualPeriods: (condition: unknown, context: AnnualPeriodErrorContext) => readonly AnnualPeriod[];

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

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

package/dist/planner/semantics/lifecycle/classification.d.ts

@@ -1,7 +1,5 @@
-import type { ResolvedSemanticProperty, ResolvedSemanticSchema } from '../../../semantic-types/index';
-export interface LifecycleProperties {
-    readonly timestamp: ResolvedSemanticProperty;
-    readonly start: ResolvedSemanticProperty;
-    readonly end: ResolvedSemanticProperty;
-}
-export declare const resolveLifecycleProperties: (schema: Pick<ResolvedSemanticSchema, "type" | "properties">) => LifecycleProperties | undefined;
+import type { ValidityProperties } from '../validity/classification';
+/** Compatibility alias. Lifecycle is the single-row validity case. */
+export type LifecycleProperties = ValidityProperties;
+/** Compatibility alias for resolveValidityProperties. */
+export declare const resolveLifecycleProperties: (schema: Pick<import("../../..").ResolvedSemanticSchema, "type" | "properties" | "temporalSemantics">) => ValidityProperties | undefined;

package/dist/planner/semantics/lifecycle/query-policy.d.ts

@@ -1,3 +1,2 @@
-import type { QueryType } from '../../../logicform-types';
-import type { LifecycleProperties } from './classification';
-export declare const applyLifecycleQuery: (query: QueryType | undefined, properties: LifecycleProperties) => QueryType | undefined;
+/** Compatibility alias for applyValidityQuery. */
+export { applyValidityQuery as applyLifecycleQuery } from '../validity/query-policy';

package/dist/planner/semantics/lifecycle/rule.d.ts

@@ -1,2 +1,2 @@
-import type { PlannerSemanticRule } from '../registry';
-export declare const lifecycleSemanticRule: PlannerSemanticRule;
+/** Compatibility alias for validitySemanticRule. */
+export declare const lifecycleSemanticRule: import("..").PlannerSemanticRule;

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

@@ -1,4 +1,6 @@
 export { isObservationProperty, observationProperties, } from './classification';
 export { resolveObservationOperatorPolicy, type ObservationOperatorPolicy, } from './operator-policy';
 export type { ObservationOperator, ObservationTemporalMetadata, } from './types';
+export { removeObservationTimeCondition, resolveObservationPeriodSpec, } from './periods';
+export type { ObservationPeriodMetric, ObservationPeriodSpec, } from './periods';
 export { observationSemanticRule } from './rule';

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

@@ -0,0 +1,19 @@
+import type { LogicformType, PredItemType, QueryType } from '../../../logicform-types';
+import type { ResolvedSemanticProperty, ResolvedSemanticSchema } from '../../../semantic-types/index';
+export interface ObservationPeriodMetric {
+    readonly pred: PredItemType;
+    readonly effectivePred: PredItemType;
+}
+export interface ObservationPeriodSpec {
+    readonly group: PredItemType;
+    readonly timestamp: ResolvedSemanticProperty;
+    readonly boundary: 'start' | 'end';
+    readonly metrics: readonly ObservationPeriodMetric[];
+    readonly periods: readonly {
+        readonly label: string;
+        readonly asOf: string;
+    }[];
+}
+export declare const removeObservationTimeCondition: (query: QueryType | undefined, timestamp: ResolvedSemanticProperty) => QueryType | undefined;
+/** Plan grouped snapshot metrics as one lookup of the latest observation per period. */
+export declare const resolveObservationPeriodSpec: (logicform: LogicformType, schema: ResolvedSemanticSchema) => ObservationPeriodSpec | undefined;

package/dist/planner/semantics/validity/classification.d.ts

@@ -0,0 +1,14 @@
+import type { ResolvedSemanticProperty, ResolvedSemanticSchema } from '../../../semantic-types/index';
+/** Property roles that define an entity whose rows are valid over a time interval. */
+export interface ValidityProperties {
+    readonly id: ResolvedSemanticProperty;
+    readonly timestamp: ResolvedSemanticProperty;
+    readonly start: ResolvedSemanticProperty;
+    readonly end: ResolvedSemanticProperty;
+}
+/**
+ * Valid-time semantics are structural: an entity with one stable ID and one
+ * start/end interval is a valid-time entity. The ID may repeat physically;
+ * non-overlapping intervals select the row version that is valid at a point.
+ */
+export declare const resolveValidityProperties: (schema: Pick<ResolvedSemanticSchema, "type" | "properties" | "temporalSemantics">) => ValidityProperties | undefined;

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

@@ -0,0 +1,6 @@
+export { resolveValidityProperties } from './classification';
+export type { ValidityProperties } from './classification';
+export { applyValidityQuery } from './query-policy';
+export { hasValidityTimeGroup, removeValidityTimeCondition, resolveValidityPeriodSpec, } from './periods';
+export type { ValidityPeriod, ValidityPeriodSpec } from './periods';
+export { validitySemanticRule } from './rule';

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

@@ -0,0 +1,16 @@
+import type { LogicformType, PredItemType, QueryType } from '../../../logicform-types';
+import type { TimeGranularity } from '../../../semantic-types/index';
+import type { ValidityProperties } from './classification';
+export interface ValidityPeriod {
+    readonly label: string;
+    readonly asOf: string;
+}
+export interface ValidityPeriodSpec {
+    readonly group: PredItemType;
+    readonly granularity: TimeGranularity;
+    readonly periods: readonly ValidityPeriod[];
+}
+export declare const hasValidityTimeGroup: (logicform: LogicformType, properties: ValidityProperties) => boolean;
+export declare const removeValidityTimeCondition: (query: QueryType | undefined, properties: ValidityProperties) => QueryType | undefined;
+/** Resolve a bounded virtual-time grouping into explicit period-end instants. */
+export declare const resolveValidityPeriodSpec: (logicform: LogicformType, properties: ValidityProperties) => ValidityPeriodSpec | undefined;

package/dist/planner/semantics/validity/query-policy.d.ts

@@ -0,0 +1,4 @@
+import type { QueryType } from '../../../logicform-types';
+import type { ValidityProperties } from './classification';
+/** Rewrite a public time-axis condition to the half-open validity interval [start, end). */
+export declare const applyValidityQuery: (query: QueryType | undefined, properties: ValidityProperties) => QueryType | undefined;

package/dist/planner/semantics/validity/rule.d.ts

@@ -0,0 +1,2 @@
+import type { PlannerSemanticRule } from '../registry';
+export declare const validitySemanticRule: PlannerSemanticRule;

package/dist/planner/types.d.ts

@@ -120,6 +120,9 @@ export interface JoinPlan {
     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 sourceArrayExpansionPath?: string;
 }
 export interface ArrayExpansionPlan {
@@ -144,6 +147,30 @@ 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 {
+    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;
+    }[];
+}
 export type RowIdentityPlan = {
     readonly kind: 'group';
     readonly names: readonly string[];
@@ -176,6 +203,10 @@ export interface LogicalPlan {
     readonly fieldReferences?: Readonly<Record<string, FieldReferencePlan>>;
     readonly joins?: readonly JoinPlan[];
     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;
     readonly projections: readonly ProjectionPlan[];
     readonly columnProperties?: readonly ResultProperty[];
     readonly groupBy: readonly ProjectionPlan[];

package/dist/schema/dependent-projection.d.ts

@@ -0,0 +1,8 @@
+import type { PredItemType } from '../logicform-types';
+import type { ResolvedSemanticSchema } from '../semantic-types/index';
+/**
+ * Returns true when a scalar projection is functionally dependent on one of
+ * the supplied group keys. Same-Schema hierarchy uses `up`; scalar object
+ * relations use the relation key itself.
+ */
+export declare const isDependentProjection: (pred: PredItemType, groupby: readonly PredItemType[], schema: ResolvedSemanticSchema, resolveSchema?: (schemaId: string) => ResolvedSemanticSchema) => boolean;