semanticdb-v2 2.0.0-alpha.2 → 2.0.0-alpha.3

package/README.md

@@ -8,16 +8,16 @@ SemanticDB creates the matching provider and owns its connection lifecycle.
 
 ```ts
 import { Logicform } from 'semanticdb-v2';
-import { SchemaMappingRegistry } from 'semanticdb-v2';
 
-const schemaMappings = new SchemaMappingRegistry([
+const schemaMappings = [
   {
     schemaId: 'sales',
     connectionId: 'analytics',
     source: 'analytics.sales_detail',
+    mappings: [],
     freshness: { mode: 'ttl', ttlSeconds: 300 },
   },
-]);
+];
 
 const response = await Logicform.execute(
   {
@@ -49,7 +49,7 @@ const response = await Logicform.execute(
 );
 ```
 
-Every executable LogicForm, including LogicForms used as subqueries, must declare `version`. This
+Every executable LogicForm, including LogicForm objects used as subqueries, must declare `version`. This
 SDK accepts semantic versions greater than or equal to `2.0`; missing, malformed, or older versions
 fail with `UNSUPPORTED_LOGICFORM_VERSION` before Schema resolution or database access. A relation
 query shaped as `{ schema, query }` is part of its parent LogicForm and inherits the parent's version.
@@ -69,7 +69,7 @@ operators.register({
 });
 ```
 
-The same locale applies to `preds`, `groupby`, nested expressions, custom-function components,
+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
 through each operator's `defaultName()`; period operators distinguish同比、环比 and other offsets.
@@ -78,7 +78,8 @@ An explicitly authored `name` is preserved unchanged.
 `entity_id` identifies one entity by `hierarchy.property` on hierarchy Schemas and by the unique
 `type: 'ID'` property on other Schemas. Normalization adds that identity filter unless the query
 already contains one, in which case the explicit query wins. The legacy value `placeholder` is
-preserved as entity context but never becomes a SQL filter. This also applies to relation queries
+preserved as entity context but never becomes a SQL filter. String IDs and safe-integer IDs are
+accepted and retain their original type. This also applies to relation queries
 shaped as `{ schema, query, entity_id }`. `representation` is presentation metadata for frontend
 consumers and does not change normalization, planning, or execution. See
 [Hierarchy plugin](docs/hierarchy-plugin.md) for Schema configuration, `$hierarchyLevel`, legacy
@@ -117,7 +118,7 @@ interface ExecutedSql {
 ```
 
 `semantic-resolution` identifies supporting SQL used to resolve semantic input or output, such as
-latest-data-date lookup and object entity population. `computation` identifies SQL that calculates
+time-watermark resolution and object entity population. `computation` identifies SQL that calculates
 the requested LogicForm result. `sqls` includes every physical SQL involved in the execution; an
 entry remains visible when its result is served by the query cache.
 
@@ -167,20 +168,20 @@ await Logicform.execute(logicform, {
 
 When `permissions` is omitted, execution remains unrestricted. When it is present, its Schema keys
 are the table allowlist. `rowPermissions` is always combined with the caller query using `AND`,
-including internal latest-data-date queries, related-table joins, and object population queries.
+including internal time-watermark queries, related-table joins, and object population queries.
 `columnPermissions.whitelist` accepts property names or IDs and restricts caller projections,
 filters, grouping, operator inputs, and relation paths. A row policy may still use a non-whitelisted
 column as an internal filter. If an ID is not whitelisted, SemanticDB generates the executor-owned
 result-row `_id` instead of exposing the physical ID as that identity.
 
-### Custom composite metrics
+### Component operators
 
-Pass legacy-compatible `genComponents`, `mergeComponents`, and `genMergeSQL` definitions through
-`ExecuteOptions.customFunctions`. JavaScript merge supports async callbacks; SQL merge compiles
-components into CTEs. `Logicform.genComponents()` expands the same definitions into an indicator
-tree without accessing a database. Cross-Schema components independently pass table, row, and
-column permissions. See [Custom composite metrics](docs/custom-functions.md) for the complete
-contract, merge-mode selection, and trusted function-string behavior.
+Composite metrics are regular `OperatorDefinition` values with `kind: 'component'`. Their
+`createComponent` hook can return query components merged through a CTE or JavaScript. Register
+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.
+
+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`,
 `doris`, `starrocks`, `clickhouse`, `snowflake`, `oracle`, or `postgresql`, then add that driver's
@@ -188,6 +189,10 @@ native connection fields directly on the item. Each Schema Mapping selects an it
 `connectionId`. SemanticDB lazily creates and reuses the matching internal provider. Call
 `await Logicform.close()` during application shutdown to close every connection pool and session.
 
+MySQL-compatible providers default to 30 connections, at most 10 idle connections, a 60-second
+idle timeout, and TCP keepalive. Native `mysql2` pool options on the connection item override these
+defaults.
+
 ### PostgreSQL connection
 
 PostgreSQL uses the official `pg` pool and PostgreSQL-native `$1`, `$2` parameters:
@@ -308,7 +313,7 @@ comments, or parameter placeholders. Property UDFs do not support the legacy `fu
 
 ### Query cache
 
-All compiled provider queries, including the internal latest-data-date query, can share one
+All compiled provider queries, including the internal time-watermark query, can share one
 caller-owned query cache. Redis is published from `semanticdb-v2/cache/redis`; cache identity
 includes namespace, provider, SQL, and parameters. Physical expiration belongs to each Schema
 mapping's `freshness` policy. See [Query cache and Redis](docs/query-cache.md).
@@ -444,7 +449,7 @@ npm run debug
 - `$and` and `$or`, HAVING, sorting, row-count and percentage pagination, and per-group `limitBy`
 - Query-level and output-column lineage
 - Multi-level scalar and array object relation paths, array groupby, and batched entity population
-- Nested `from` LogicForms compiled as parameterized derived tables
+- Nested `from` LogicForm objects compiled as parameterized derived tables
 
 Exports and metadata persistence are intentionally deferred. Directly selected array-object
 properties are populated without expanding the root result rows.

package/dist/cache/redis-query-cache.js

@@ -1 +1 @@
-import{createClient as y}from"redis";import{queryCacheIdentityHash as d,sourceCacheIndexHash as f}from"./identity.js";import{deserializeQueryRows as w,serializeQueryRows as x}from"./serialization.js";const m=Number.MAX_SAFE_INTEGER;class u{#e;#t;#s;constructor(e,t={}){this.#e=e,this.#t=t.keyPrefix??"semanticdb:cache",this.#s=t.ownsClient??!1}#r(e){return`${this.#t}:query:${d(e)}`}#i(e,t){return`${this.#t}:source:${f(e,t)}`}async get(e){const t=await this.#e.get(this.#r(e));if(t!==null)return w(t)}async set(e,t,i){const s=this.#r(e),a=x(t),c=i.expiresAt?.getTime(),l=c??m,n=this.#e.multi();c===void 0?n.set(s,a):n.set(s,a,{PXAT:c});for(const h of new Set(i.sources)){const o=this.#i(e.namespace,h);n.zRemRangeByScore(o,0,Date.now()),n.zAdd(o,{score:l,value:s})}await n.exec()}async invalidateSource(e,t){const i=this.#i(e,t),s=await this.#e.zRange(i,0,-1);s.length>0&&await this.#e.del(s),await this.#e.del(i)}async close(){this.#s&&await this.#e.close()}}const C=async(r={})=>{const e=y(r.url?{url:r.url}:{});return e.on("error",()=>{}),await e.connect(),new u(e,{...r.keyPrefix?{keyPrefix:r.keyPrefix}:{},ownsClient:!0})};export{u as RedisQueryCache,C as createRedisQueryCache};
+import{createClient as b}from"redis";import{createHash as g}from"node:crypto";const a=e=>e===void 0?{type:"undefined"}:typeof e=="bigint"?{type:"bigint",value:e.toString()}:typeof e=="number"&&!Number.isFinite(e)?{type:"number",value:String(e)}:e instanceof Date?{type:"date",value:e.toISOString()}:Array.isArray(e)?e.map(a):e&&typeof e=="object"?Object.fromEntries(Object.entries(e).sort(([t],[r])=>t.localeCompare(r)).map(([t,r])=>[t,a(r)])):e,d=e=>g("sha256").update(JSON.stringify(a(e))).digest("hex"),A=e=>d({namespace:e.namespace,provider:e.provider,sql:e.sql,parameters:e.parameters}),S=(e,t)=>d({namespace:e,source:t}),o=e=>e===void 0?{type:"undefined"}:typeof e=="bigint"?{type:"bigint",value:e.toString()}:typeof e=="number"&&!Number.isFinite(e)?{type:"number",value:String(e)}:e instanceof Date?{type:"date",value:e.toISOString()}:Array.isArray(e)?{type:"array",value:e.map(o)}:e&&typeof e=="object"?{type:"object",value:Object.entries(e).map(([t,r])=>[t,o(r)])}:e,y=e=>{if(e===null||typeof e!="object")return e;switch(e.type){case"undefined":return;case"bigint":return BigInt(e.value);case"number":return Number(e.value);case"date":return new Date(e.value);case"array":return e.value.map(y);case"object":return Object.fromEntries(e.value.map(([t,r])=>[t,y(r)]))}},w=e=>JSON.stringify(o(e)),x=e=>{const t=y(JSON.parse(e));if(!(!Array.isArray(t)||t.some(r=>!r||typeof r!="object"||Array.isArray(r))))return t},l=Number.MAX_SAFE_INTEGER;class p{#e;#t;#r;constructor(t,r={}){this.#e=t,this.#t=r.keyPrefix??"semanticdb:cache",this.#r=r.ownsClient??!1}#n(t){return`${this.#t}:query:${A(t)}`}#i(t,r){return`${this.#t}:source:${S(t,r)}`}async get(t){const r=await this.#e.get(this.#n(t));if(r!==null)return x(r)}async set(t,r,i){const n=this.#n(t),f=w(r),c=i.expiresAt?.getTime(),m=c??l,s=this.#e.multi();c===void 0?s.set(n,f):s.set(n,f,{PXAT:c});for(const h of new Set(i.sources)){const u=this.#i(t.namespace,h);s.zRemRangeByScore(u,0,Date.now()),s.zAdd(u,{score:m,value:n})}await s.exec()}async invalidateSource(t,r){const i=this.#i(t,r),n=await this.#e.zRange(i,0,-1);n.length>0&&await this.#e.del(n),await this.#e.del(i)}async close(){this.#r&&await this.#e.close()}}const j=async(e={})=>{const t=b(e.url?{url:e.url}:{});return t.on("error",()=>{}),await t.connect(),new p(t,{...e.keyPrefix?{keyPrefix:e.keyPrefix}:{},ownsClient:!0})};export{p as RedisQueryCache,j as createRedisQueryCache};

package/dist/compatibility/index.d.ts

@@ -1,2 +1,2 @@
-export { assertNoLegacyLogicformFields, normalizeLegacyLogicform, splitLegacySchemas, } from './logicform';
+export { assertNoLegacyLogicformFields, normalizeLegacyLogicform, } from './logicform';
 export { normalizeSchemas } from '../executor/compatibility';

package/dist/compatibility/logicform.d.ts

@@ -1,13 +1,7 @@
 import type { LogicformType } from '../logicform-types';
 type SchemaRegistry = Readonly<Record<string, unknown>>;
 /** Converts a legacy LogicForm tree into the v2 wire shape without mutating input. */
-export declare const normalizeLegacyLogicform: (logicform: unknown) => LogicformType;
-/**
- * Converts the legacy `pred.schema` fan-out into v2 composition. The planner
- * intentionally rejects cross-schema PredItems, so this has to happen before
- * the v2 normalizer sees the tree.
- */
-export declare const splitLegacySchemas: (logicform: LogicformType, schemas?: SchemaRegistry) => LogicformType;
+export declare const normalizeLegacyLogicform: (logicform: unknown, schemas?: SchemaRegistry) => LogicformType;
 /** Rejects legacy wire fields when a caller explicitly declares a v2 LogicForm. */
 export declare const assertNoLegacyLogicformFields: (logicform: unknown) => void;
 export {};

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

@@ -1,4 +1,4 @@
-import type { OperatorCteCalculation, OperatorGroupKeyShift } from '../operators/index';
+import type { OperatorComponentCalculation, OperatorGroupKeyShift } from '../operators/index';
 import type { CoreComputeProvider } from '../physical/index';
 import type { LogicalPlan } from '../planner/index';
 import type { CompiledQuery } from './types';
@@ -9,4 +9,19 @@ export interface PreparedCteComponent {
     readonly groupKeyShifts?: readonly OperatorGroupKeyShift[];
     readonly joinKeys?: readonly string[];
 }
-export declare const compileCteCalculation: (calculation: OperatorCteCalculation, components: readonly PreparedCteComponent[], outputPlan: LogicalPlan, provider: CoreComputeProvider, operators: OperatorRegistry) => CompiledQuery;
+/** A compiled top-level execution unit that can be joined into one SQL query. */
+export interface PreparedCteQuery {
+    readonly plan: LogicalPlan;
+    readonly compiled: CompiledQuery;
+    /** Result projection names exposed by this execution unit (excluding groups). */
+    readonly outputs: readonly string[];
+}
+/**
+ * Combine independent SQL execution units into one statement.
+ *
+ * Component operators are compiled independently because their input ranges can
+ * differ (for example, current and previous periods). Keeping each unit as a
+ * 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;

package/dist/compiler/index.d.ts

@@ -1,4 +1,5 @@
 export { compilePlan } from './compile-plan';
-export { compileCteCalculation } from './compile-cte';
+export { compileCteCalculation, compileCteQueries } from './compile-cte';
+export type { PreparedCteQuery } from './compile-cte';
 export { shortenSQL } from './shorten-sql';
 export type { CompiledQuery } from './types';

package/dist/executor/types.d.ts

@@ -2,12 +2,11 @@ import type { 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';
-import type { SchemaMappingRegistry } from '../schema-mappings/index';
-import type { ResolvedSemanticSchema, SemanticSchemaDraft, SemanticTypeRegistry } from '../semantic-types/index';
-import type { LogicformType } from '../logicform-types';
+import type { SchemaMappingDefinition, SchemaMappingRegistry } from '../schema-mappings/index';
+import type { ResolvedSemanticSchema, SemanticSchemaDraft, SemanticTypeRegistry, TimeWatermarkPolicy } from '../semantic-types/index';
+import type { LogicformType, PublicLogicformType } from '../logicform-types';
 import type { QueryCacheExecutionOptions } from '../cache/index';
 import type { Permissions } from '../permissions/index';
-import type { CustomFunctions } from '../custom-functions/index';
 import type { SemanticDBPlugin } from '../plugins/index';
 export type ExecuteProgressEvent = {
     readonly stage: 'started';
@@ -56,7 +55,6 @@ export type ExecuteProgressEvent = {
 export type ProgressCallback = (event: ExecuteProgressEvent) => void | Promise<void>;
 interface ExecuteBaseOptions {
     readonly schemas: Readonly<Record<string, SemanticSchemaDraft>>;
-    readonly schemaMappings: SchemaMappingRegistry;
     readonly semanticTypes?: SemanticTypeRegistry;
     readonly operators?: OperatorRegistry;
     /** Caller-owned capability plugins appended to the built-in plugin set for this execution. */
@@ -65,22 +63,23 @@ interface ExecuteBaseOptions {
     readonly locale?: string;
     /** 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;
 }
 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[];
 }
 /** Internal execution seam used by executor tests after a provider has been resolved. */
 export interface InternalExecuteOptions extends ExecuteBaseOptions {
     readonly provider: CoreComputeProvider;
+    readonly schemaMappings: SchemaMappingRegistry;
     /** Selected connection for public execution; omitted only by internal provider tests. */
     readonly connectionId?: string;
 }
@@ -88,7 +87,7 @@ export interface ExecuteSuccessResult {
     readonly result: DataRow[];
     /** 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'];
@@ -98,7 +97,7 @@ export interface ExecuteFailureResult {
     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;
@@ -111,7 +110,7 @@ export interface ExecutedSql {
     /** Human-readable, localized explanation of why this SQL is executed. */
     readonly explain: string;
     /** Normalized LogicForm represented by this SQL statement. */
-    readonly logicform: LogicformType;
+    readonly logicform: PublicLogicformType;
     /** Parameterized SQL used for provider execution and cache identity. */
     readonly sql: string;
     readonly parameters: SqlParameters;

package/dist/index.d.ts

@@ -1,26 +1,24 @@
 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 { 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, } from './semantic-types/index';
+export type { PrimalType, 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, 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 { OperatorDefinition, OperatorDefaultNameContext, OperatorComponentContext, OperatorComponentCalculation, OperatorComponentQuery, OperatorExecutionComponent, OperatorPlanInputContext, OperatorPlannedInput, OperatorGroupKeyShift, OperatorJavaScriptCalculation, OperatorQueryComponent, OperatorEvaluateContext, OperatorOutputPropertyContext, OperatorSqlCapabilities, OperatorSqlContext, ResultProperty, ResultPropertyTemporalMetadata, } from './operators/index';
+export type { SchemaMappingDefinition, SchemaMappingItem, SchemaMappingPredDefinition, SchemaMappingPredMatch, SourceFreshnessPolicy, YiAskSchemaMappingItem, YiAskSchemaMappingRecord, } 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 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

@@ -34,6 +34,8 @@ export interface CalendarDateValue {
 export type PeriodShiftTime = RelativeDateValue | AbsoluteDateValue;
 /** A date value before semantic-type normalization. */
 export type DateValue = string | RelativeDateValue | AbsoluteDateValue | CalendarDateValue;
+/** 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' | '$recursive' | '$and' | '$or';
 export interface RecursiveQueryType {
     readonly schema?: string;
@@ -50,7 +52,7 @@ 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;
 export type QueryValueTypeWithCompareOperator = Partial<{
@@ -80,16 +82,14 @@ export type QueryType = Record<string, QueryValueType | QueryValueTypeWithCompar
 };
 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';
@@ -102,10 +102,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 +115,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[];
-};

package/dist/normalizer/core.d.ts

@@ -10,10 +10,10 @@ export interface NormalizeLogicformOptions {
     readonly locale?: string;
     readonly now?: Date;
     readonly resolveSchema?: (schemaId: string) => ResolvedSemanticSchema;
-    readonly requestLatestDataDate?: (schema: ResolvedSemanticSchema, property: ResolvedSemanticProperty) => Promise<Date | undefined>;
+    readonly requestTimeWatermark?: (schema: ResolvedSemanticSchema, property: ResolvedSemanticProperty, requestedUpperBound: Date) => Promise<Date | undefined>;
     readonly resolveFromSchema?: (normalizedFrom: LogicformType, outerSchema: ResolvedSemanticSchema) => ResolvedSemanticSchema;
     readonly canProjectProperty?: (schema: ResolvedSemanticSchema, property: ResolvedSemanticProperty) => boolean;
     /** Internal recursion hook installed by normalizeLogicform. */
     readonly normalizeNestedLogicform?: (logicform: LogicformType) => Promise<LogicformType>;
 }
-export declare const resolveLogicformSchema: (logicform: LogicformType, currentSchema: ResolvedSemanticSchema, options: NormalizeLogicformOptions) => ResolvedSemanticSchema;
+export declare const resolveFormSchema: (logicform: LogicformType, currentSchema: ResolvedSemanticSchema, options: NormalizeLogicformOptions) => ResolvedSemanticSchema;

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

@@ -0,0 +1,5 @@
+import type { LogicformType } from '../logicform-types';
+import type { ResolvedSemanticSchema } from '../semantic-types/index';
+import type { NormalizeLogicformOptions } from './core';
+/** 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/constant.d.ts

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

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

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

package/dist/operators/builtins/scalar-extremum.d.ts

@@ -0,0 +1,3 @@
+import type { OperatorDefinition } from '../types';
+export declare const leastOperator: OperatorDefinition;
+export declare const greatestOperator: OperatorDefinition;

package/dist/operators/index.d.ts

@@ -2,6 +2,6 @@ import type { SemanticDBPlugin } from '../plugins/index';
 import { OperatorRegistry } from './registry';
 export { OperatorRegistry } from './registry';
 export { bindTrustedSqlExpression } from './sql-expression';
-export type { OperatorDefinition, OperatorDefaultNameContext, OperatorComponentContext, OperatorCteCalculation, OperatorCteComponent, OperatorCteSqlContext, OperatorExecutionComponent, OperatorGroupKeyShift, OperatorJavaScriptCalculation, OperatorQueryComponent, OperatorEvaluateContext, OperatorOutputPropertyContext, OperatorObservationPolicy, OperatorObservationPolicyContext, OperatorNormalizePredContext, OperatorPlanExpressionContext, OperatorPeriodEvaluationContext, OperatorPlanInputContext, OperatorPlannedInput, OperatorRewriteLogicformContext, OperatorValidatePlanContext, OperatorSqlCapabilities, OperatorSqlContext, ResultProperty, ResultPropertyTemporalMetadata, } from './types';
+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[];
 export declare const createOperatorRegistry: (plugins?: readonly SemanticDBPlugin[]) => OperatorRegistry;

package/dist/operators/types.d.ts

@@ -10,6 +10,9 @@ export interface OperatorSqlCapabilities {
     concat(expressions: readonly string[]): string;
     substring(expression: string, start: number, length: number): string;
     dateBucket(expression: string, granularity: TimeGranularity): string;
+    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;
     /** Bind a literal as a SQL parameter. */
     value(value: unknown): string;
     /** Compile a field-local LogicForm condition against an expression. */
@@ -20,7 +23,7 @@ export interface OperatorSqlContext {
     readonly sql: OperatorSqlCapabilities;
     /** SQL for the nested input expression, when this operator has one. */
     readonly expression?: string;
-    /** SQL expressions produced by a multi-input operator's structural components. */
+    /** SQL expressions produced by a multi-input pred. */
     readonly expressions?: readonly string[];
     /** Quoted physical column for a leaf-property operator. */
     readonly column?: string;
@@ -76,8 +79,8 @@ export interface OperatorOutputPropertyContext {
     readonly property?: ResolvedSemanticProperty;
     /** Semantic metadata produced by a nested expression. */
     readonly inputProperty?: ResultProperty;
-    /** Semantic metadata produced by structural components. */
-    readonly componentProperties?: readonly ResultProperty[];
+    /** Semantic metadata produced by a multi-input pred. */
+    readonly inputProperties?: readonly ResultProperty[];
     /** Operator-specific LogicForm arguments. */
     readonly args: Readonly<Record<string, unknown>>;
 }
@@ -89,12 +92,12 @@ export interface OperatorPeriodEvaluationContext {
     readonly inputProperty?: ResolvedSemanticProperty;
 }
 export interface OperatorDefaultNameContext {
-    /** Name produced by the direct pred, structural components, or localized row label. */
+    /** Name produced by the direct pred inputs or localized row label. */
     readonly operandName: string;
     /** Name of a direct or nested pred input. */
     readonly inputName?: string;
-    /** Names of structural component inputs. */
-    readonly componentNames: readonly string[];
+    /** Names of multi-input pred values. */
+    readonly inputNames: readonly string[];
     /** Operator-specific LogicForm arguments. */
     readonly args: Readonly<Record<string, unknown>>;
     /** Requested locale. Each operator owns its own localized default names. */
@@ -121,7 +124,7 @@ export interface OperatorPlanExpressionContext {
     readonly pred: PredItemType;
     readonly input?: Expression;
     readonly inputProperty?: ResultProperty;
-    readonly components: readonly Expression[];
+    readonly inputs: readonly Expression[];
     readonly args: Readonly<Record<string, unknown>>;
     readonly resolveKey: (reference: string) => Expression;
     readonly getOperator: (name: string) => OperatorDefinition;
@@ -143,6 +146,8 @@ export interface OperatorValidatePlanContext {
 export interface OperatorRewriteLogicformContext {
     readonly logicform: LogicformType;
     readonly schema: ResolvedSemanticSchema;
+    /** Resolve operator metadata while rewriting nested expressions. */
+    readonly getOperator?: (name: string) => OperatorDefinition;
 }
 export interface OperatorComponentContext {
     /** Fully normalized LogicForm containing this top-level operator projection. */
@@ -173,31 +178,30 @@ export interface OperatorQueryComponent {
     /** SQL-side transformations that align this component's group keys with the base component. */
     readonly groupKeyShifts?: readonly OperatorGroupKeyShift[];
 }
-export interface OperatorCteSqlContext {
-    readonly values: Readonly<Record<string, string>>;
-    readonly quoteIdentifier: (identifier: string) => string;
-}
-export interface OperatorCteComponent {
+export interface OperatorComponentQuery {
     readonly name: string;
-    readonly component: OperatorQueryComponent;
+    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. */
     readonly joinKeys?: readonly string[];
 }
-export interface OperatorCteCalculation {
-    readonly kind: 'cte';
-    readonly components: readonly OperatorCteComponent[];
+export interface OperatorComponentCalculation {
+    readonly components: readonly OperatorComponentQuery[];
+    /** Provider-independent formula referring to component names. */
+    readonly expression: string;
     readonly outputName?: string;
-    readonly toSQL: (context: OperatorCteSqlContext) => string;
     readonly exposeComponents?: boolean;
 }
 export interface OperatorJavaScriptCalculation {
     readonly kind: 'js';
-    readonly components: readonly OperatorCteComponent[];
+    readonly components: readonly OperatorComponentQuery[];
     readonly outputName: string;
     readonly mergeRow: (values: DataRow) => unknown;
     readonly exposeComponents?: boolean;
 }
-export type OperatorExecutionComponent = OperatorQueryComponent | OperatorCteCalculation | OperatorJavaScriptCalculation;
+export type OperatorExecutionComponent = OperatorQueryComponent | OperatorComponentCalculation | OperatorJavaScriptCalculation;
 /**
  * Extension contract for one LogicForm operator.
  *
@@ -207,7 +211,7 @@ export type OperatorExecutionComponent = OperatorQueryComponent | OperatorCteCal
  * `getOutputProperty` to describe the resulting one-column logical schema.
  */
 interface OperatorDefinitionBase {
-    /** Public registry key, normally using the `$name` convention. */
+    /** Public registry key. Built-in operators commonly use a `$` prefix, but it is not required. */
     readonly name: string;
     /** Produce the normalized output name when the PredItem does not declare one. */
     readonly defaultName: (context: OperatorDefaultNameContext) => string;
@@ -227,7 +231,7 @@ interface OperatorDefinitionBase {
     readonly observationPolicy?: (context: OperatorObservationPolicyContext) => OperatorObservationPolicy | undefined;
     /** Validate this operator against the completed group key set. */
     readonly validatePlan?: (context: OperatorValidatePlanContext) => void;
-    /** Expand high-level operator semantics into ordinary nested LogicForms before planning. */
+    /** Expand high-level operator semantics into ordinary nested LogicForm objects before planning. */
     readonly rewriteLogicform?: (context: OperatorRewriteLogicformContext) => LogicformType | undefined;
     /** Whether this operator requires one evaluation per time bucket. */
     readonly requiresPerPeriodEvaluation?: (context: OperatorPeriodEvaluationContext) => boolean;

package/dist/physical/mysql-protocol-provider.d.ts

@@ -20,6 +20,7 @@ export declare abstract class MySQLProtocolProvider implements CoreComputeProvid
     displayQuery(sql: string, parameters: SqlParameters): string;
     dateBucket(expression: string, level: string): string;
     dateShift(expression: string, granularity: string, offset: number): string;
+    datePeriodBoundary(expression: string, granularity: string, boundary: 'start' | 'end'): string;
     aggregateFunction(name: string, expression?: string): string;
     stringify(expression: string): string;
     concat(expressions: readonly string[]): string;

package/dist/physical/provider.d.ts

@@ -13,6 +13,7 @@ export interface SqlRenderCapabilities {
     paginate(sql: string, pageSize: number, offset: number): string;
     dateBucket(expression: string, level: string): string;
     dateShift(expression: string, granularity: string, offset: number): string;
+    datePeriodBoundary?(expression: string, granularity: string, boundary: 'start' | 'end'): string;
     aggregateFunction(name: string, expression?: string): string;
     stringify(expression: string): string;
     concat(expressions: readonly string[]): string;

package/dist/planner/semantics/observation/operator-policy.d.ts

@@ -1,6 +1,6 @@
 import type { PredItemType } from '../../../logicform-types';
 import type { OperatorDefinition } from '../../../operators/index';
-declare const periodBoundaryOperator = "$periodBoundary";
+declare const periodBoundaryOperator = "$periodValue";
 export interface ObservationOperatorPolicy {
     readonly operator: typeof periodBoundaryOperator;
     readonly boundary: 'start' | 'end';

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

@@ -1,3 +1,3 @@
 import type { ResultPropertyTemporalMetadata } from '../../../operators/index';
 export type ObservationTemporalMetadata = ResultPropertyTemporalMetadata;
-export type ObservationOperator = '$periodBoundary';
+export type ObservationOperator = '$periodValue';

package/dist/planner/types.d.ts

@@ -1,4 +1,5 @@
 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';
 export interface FieldReferencePlan {
@@ -66,7 +67,7 @@ export type Expression = {
     readonly qualifier?: string;
     readonly schemaId?: string;
     readonly input?: Expression;
-    readonly components?: readonly Expression[];
+    readonly inputs?: readonly Expression[];
     readonly args: Readonly<Record<string, unknown>>;
     readonly query?: Readonly<Record<string, unknown>>;
 } | {
@@ -165,9 +166,11 @@ export interface LogicalPlan {
     /** Physical mapping selected by the Planner for this logical Schema. */
     readonly mappingId?: string;
     /** Child relations combined by their compatible group identity. */
-    readonly composition?: readonly LogicalPlan[];
+    readonly subplans?: readonly LogicalPlan[];
     /** Optional query plan compiled as the derived-table source of this plan. */
     readonly sourcePlan?: LogicalPlan;
+    /** Normalized LogicForm corresponding to sourcePlan when generated rewrites need execution. */
+    readonly sourceLogicform?: LogicformType;
     readonly sourceAlias?: string;
     readonly fields: Readonly<Record<string, string>>;
     readonly fieldReferences?: Readonly<Record<string, FieldReferencePlan>>;

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

@@ -1,11 +1,12 @@
 export interface HierarchyLevelDefinition {
     readonly name: string;
-    readonly synonyms?: readonly string[];
+    readonly syno?: readonly string[];
     readonly codeLength: number;
 }
 export interface HierarchyDefinition {
     /** Property that physically stores the complete hierarchy code. */
-    readonly property: string;
+    /** Property storing the complete hierarchy code. Defaults to the Schema's only ID Property. */
+    readonly property?: string;
     /** Compact codes stop at their level; zero-padded codes fill remaining segments with zeroes. */
     readonly storage?: 'compact' | 'zero-padded';
     readonly levels: readonly HierarchyLevelDefinition[];