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

package/README.md

@@ -22,12 +22,13 @@ providers across executions; call `await Logicform.close()` during application s
 
 ```ts
 import { Logicform } from 'semanticdb-v2';
+import type { SchemaMappingDefinition } from 'semanticdb-v2';
 
-const schemaMappings = [
+const schemaMappings: SchemaMappingDefinition[] = [
   {
     schemaId: 'sales',
     connectionId: 'analytics',
-    source: 'analytics.sales_detail',
+    source: { kind: 'table', table: 'analytics.sales_detail' },
     mappings: [],
     freshness: { mode: 'ttl', ttlSeconds: 300 },
   },
@@ -68,6 +69,10 @@ A successful response always includes `total`, the number of result rows before
 `limit`/`page` pagination. For grouped LogicForms this is the number of groups after `having` and
 `limitBy`. Paginated physical queries include a separate `sqls` entry with `type: 'total'` for the
 count query; unpaginated and executor-merged results derive the value without another SQL query.
+For entity sampling, `total` counts distinct eligible entities before sampling. See
+[Entity sampling](docs/entity-sampling.md) for boolean `sample`, top-level `limit`, and sorting rules.
+See [Demo data perturbation](docs/random-data.md) for `randomData`, which applies random multipliers
+to final numeric output values while preserving group keys and identities.
 
 The v2 LogicForm contract requires `version` on executable LogicForms, including LogicForm objects
 used as subqueries, and accepts semantic versions greater than or equal to `2.0`. At the public
@@ -280,7 +285,7 @@ commands that have already reached the database.
 
 ### Permissions
 
-Pass table, row, and column permissions together through `ExecuteOptions.permissions`:
+Pass table, row, column, and custom metric permissions through `ExecuteOptions.permissions`:
 
 ```ts
 import type { Permissions } from 'semanticdb-v2';
@@ -326,6 +331,15 @@ filters, grouping, operator inputs, and relation paths. A row policy may still u
 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 metrics have a separate Schema catalog (`metrics: ['均价']`) and user policy
+(`metricPermissions: { whitelist: ['均价'] }`). Omission preserves unrestricted metric access;
+`[]` denies all custom metrics and `'*'` permits the current Schema's catalog. Metric names never
+belong in `columnPermissions`. Compound metrics require permission for their internal custom
+metrics and underlying properties; generated child queries retain table and row checks.
+Permissions are validated only for Schemas reached by the execution.
+See [the interface and YiAsk migration example](docs/metric-permissions.md) for dependency
+contracts, compatibility behavior, and complete configuration examples.
+
 ### Component operators
 
 Composite metrics are regular `OperatorDefinition` values with `kind: 'component'`. Their
@@ -341,7 +355,14 @@ names shared by both sides unless an exceptional custom operator explicitly supp
 
 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`,
+DuckDB accepts customer `.duckdb` files (`path`, read-only by default) and managed
+shared upload datasets (`directory`). `DBConnector.importFile()` supports `.xlsx`
+and CSV, fixed column definitions, idempotent batches and batch replacement.
+CSV automatically accepts UTF-8/BOM-marked Unicode; specify `gbk` or `gb18030` for
+legacy Chinese files. See [DuckDB and file imports](docs/file-import.md) for PM2
+sharing, configuration, encoding rules and operational limits.
+
+The root entry point accepts a `connections` array of `DatabaseConnection` items. Every item has a unique `id`; set `kind` to `duckdb`, `mysql`,
 `doris`, `starrocks`, `gbase`, `maxcompute`, `clickhouse`, `databricks`, `dameng`, `snowflake`,
 `sqlserver`, `oracle`, or `postgresql`, then add that driver's
 native connection fields directly on the item. Each Schema Mapping selects an item through
@@ -496,6 +517,13 @@ driver's ordinal parameter binding and are not interpolated into executable SQL.
 required: PAT and OAuth fields are mutually exclusive, and authentication is never inferred from
 the presence of credentials.
 
+To check a real connection, fill in the Databricks fields in `.env` (see `.env.example`) and run
+`npm run test:databricks`. Set `DATABRICKS_AUTH_TYPE=databricks-oauth` with
+`DATABRICKS_CLIENT_ID` and `DATABRICKS_CLIENT_SECRET`, or use `access-token` with
+`DATABRICKS_TOKEN`. The command opens a session through `DatabricksProvider`, applies `TZ` with
+`SET TIME ZONE` when present, and prints the current session time zone, catalog, and schema.
+The `.env` file is ignored by Git.
+
 ### Dameng connection
 
 Dameng uses the official `dmdb` pool and the `dameng` connection kind:
@@ -584,6 +612,13 @@ trusted model metadata, must match the active provider dialect, and cannot conta
 comments, or parameter placeholders. Property UDFs do not support the legacy `function` or
 `dependencies` fields; application-side computed values belong outside this query SDK.
 
+### Schema Mapping and data weaving
+
+One logical Schema can use multiple physical sources, conditional measure columns,
+time partitions, and same-connection feature tables. See
+[Schema Mapping and data weaving](docs/data-weaving.md) for the current design and
+links to detailed configuration guides.
+
 ### Query cache
 
 All compiled provider queries, including the internal time-watermark query, can share one
@@ -592,17 +627,6 @@ cache identity includes namespace, connection id, provider, SQL, and parameters.
 expiration belongs to each Schema mapping's `freshness` policy. See
 [Query cache and Redis](docs/query-cache.md).
 
-Schema mappings can also expose same-connection entity feature tables as lazy physical
-enrichments. A mapped feature property adds a `LEFT JOIN` only when referenced, and a point-in-time
-feature can be assigned to the containing valid-time entity row. See
-[Schema Mapping feature enrichments](docs/schema-mapping-enrichments.md).
-
-For aggregate sources, set `granularity` on mapped date or hierarchy Properties.
-Other available dimensions are inferred from their Property mappings, so there is no
-separate Schema Mapping `dimensions` field. The planner selects a source that covers
-the requested properties and physical time or hierarchy grain. See
-[Schema Mapping physical granularity](docs/schema-mapping-granularity.md).
-
 When Redis is shared with other applications, pass an application-specific key prefix in the
 execution JSON. SemanticDB reuses the connection by `cache.id`:
 

package/dist/cache/types.d.ts

@@ -4,6 +4,7 @@ export interface QueryCacheIdentity {
     readonly provider: CoreComputeProvider['kind'];
     /** Distinguishes separate databases using the same provider dialect. */
     readonly connectionId?: string;
+    readonly dataVersion?: string;
     readonly sql: string;
     readonly parameters: SqlParameters;
 }
@@ -39,6 +40,6 @@ export interface QueryCacheConfiguration {
 }
 export interface InvalidateQueryCacheSourceOptions {
     readonly cache: QueryCacheConfiguration;
-    /** Physical Schema Mapping source to invalidate. */
+    /** Source identity returned by sourceIdentity(mapping.source). */
     readonly source: string;
 }

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

@@ -0,0 +1,6 @@
+import type { Expression } from '../planner/index';
+import type { CoreComputeProvider } from '../physical/index';
+/** Render a scoped row-level computation. Inputs have already been resolved by Planner. */
+export declare const compileComputation: (computation: Extract<Expression, {
+    kind: "mapping-computation";
+}>, provider: CoreComputeProvider, renderInput: (expression: Expression) => string, bind: (value: unknown) => string) => string;

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

@@ -0,0 +1,5 @@
+import type { ResolvedMappingSource } from '../schema-mappings/index';
+import type { CoreComputeProvider } from '../physical/index';
+/** The only SQL renderer for a resolved table/query row-set source. */
+export declare const compileSource: (source: unknown, provider: CoreComputeProvider) => string;
+export declare const sourceRequiresAlias: (source: ResolvedMappingSource | undefined) => boolean;

package/dist/executor/component-properties.d.ts

@@ -0,0 +1,22 @@
+import type { LogicformType } from '../logicform-types';
+import type { OperatorQueryComponent } from '../operators/index';
+import type { LogicalPlan } from '../planner/index';
+import type { ResolvedSemanticSchema } from '../semantic-types/index';
+import { type ExecutionUnit } from './components';
+export interface PreparedComponentPlan {
+    readonly logicform: LogicformType;
+    readonly plan: LogicalPlan;
+    readonly schema: ResolvedSemanticSchema;
+}
+/** Prepare metadata from the same normalized queries and hook results used for computation. */
+export declare const createComponentPropertyResolver: (options: {
+    readonly createUnits: (form: LogicformType, plan: LogicalPlan, schema: ResolvedSemanticSchema, source?: LogicformType) => readonly ExecutionUnit[] | undefined;
+    readonly prepareQuery: (component: OperatorQueryComponent) => Promise<PreparedComponentPlan>;
+    readonly replanSource: (form: LogicformType, schema: ResolvedSemanticSchema, sourceForm: LogicformType, sourcePlan: LogicalPlan) => LogicalPlan;
+    readonly resolveSchema: (form: LogicformType) => ResolvedSemanticSchema;
+    readonly prepareUnits: (units: readonly ExecutionUnit[]) => Promise<void>;
+}) => {
+    getUnits: (form: LogicformType, plan: LogicalPlan, schema: ResolvedSemanticSchema, source?: LogicformType) => readonly ExecutionUnit[] | undefined;
+    prepareQuery: (component: OperatorQueryComponent) => Promise<PreparedComponentPlan>;
+    resolvePlan: (form: LogicformType, original: LogicalPlan, schema: ResolvedSemanticSchema, source?: LogicformType) => Promise<LogicalPlan>;
+};

package/dist/executor/components.d.ts

@@ -1,14 +1,18 @@
 import type { LogicformType } from '../logicform-types';
-import type { OperatorComponentCalculation, OperatorJavaScriptCalculation, OperatorQueryComponent, OperatorRegistry } from '../operators/index';
+import type { OperatorComponentCalculation, OperatorComponentInput, OperatorComponentQuery, 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';
 import { type LocaleTranslate } from '../i18n/index';
-export type ExecutionUnit = OperatorQueryComponent | (OperatorComponentCalculation & {
+export type ExecutionUnit = (OperatorQueryComponent & {
+    readonly outputName?: string;
+}) | (OperatorComponentCalculation & {
     readonly outputName: string;
 }) | (OperatorJavaScriptCalculation & {
     readonly outputName: string;
 });
+export declare const isQueryComponent: (input: OperatorComponentInput) => input is OperatorComponentQuery;
 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[];
+export declare const mergeCalculationRows: (results: readonly (readonly DataRow[])[], groupNames: readonly string[], calculation: OperatorJavaScriptCalculation) => DataRow[];
+export declare const mergeExecutionResults: (results: readonly (readonly DataRow[])[], plan: Pick<LogicalPlan, "groupBy" | "having" | "groupLimit" | "orderBy" | "pagination">) => DataRow[];

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

@@ -10,6 +10,7 @@ export interface PhysicalQuerySource {
     readonly connectionId?: string;
     /** Base mapping source that owns an enrichment source. */
     readonly mappingSource?: string;
+    readonly computationId?: string;
 }
 export declare const resolvePhysicalSourceMapping: (source: PhysicalQuerySource, mappings: SchemaMappingRegistry) => SchemaMappingDefinition | undefined;
 export declare const collectPlanSources: (plan: LogicalPlan) => readonly PhysicalQuerySource[];

package/dist/executor/merge-by-id.d.ts

@@ -0,0 +1,3 @@
+import type { DataRow } from '../physical/index';
+/** Merge result arrays by their executor-owned `_id`; later columns override earlier ones. */
+export declare const mergeByID: (results: readonly (readonly Readonly<DataRow>[])[]) => DataRow[];

package/dist/executor/partition.d.ts

@@ -6,6 +6,7 @@ import type { LogicformPartitionShard, ResolvedSemanticSchema } from '../semanti
 /** Intersect range filters so the grain checker sees the effective shard boundary. */
 export declare const partitionQuery: (original: QueryType | undefined, additional: QueryType) => QueryType;
 export declare const validatePartitionShards: (schema: ResolvedSemanticSchema, shards: readonly LogicformPartitionShard[], mappings: SchemaMappingRegistry) => void;
+export declare const isDetailPartition: (logicform: LogicformType) => boolean;
 export interface PartitionedPlans {
     readonly current: LogicalPlan;
     readonly comparison?: LogicalPlan;

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

@@ -0,0 +1,5 @@
+import type { LogicformRandomDataType } from '../logicform-types';
+import type { DataRow } from '../physical/index';
+import type { LogicalPlan } from '../planner/index';
+/** Runs after all calculations/pagination and before semantic result hooks. Never mutates cached rows. */
+export declare const randomizeResultData: (rows: readonly DataRow[], plan: LogicalPlan, randomData: LogicformRandomDataType | undefined) => readonly DataRow[];

package/dist/executor/result-hydrator/entity-fetch-conditions.d.ts

@@ -0,0 +1,4 @@
+import type { LogicformType, QueryType } from '../../logicform-types';
+import type { EntityFetchRequest } from './types';
+/** ID-only display expansion uses the latest version that has already started. */
+export declare const createEntityFetchConditions: (request: EntityFetchRequest, idQuery: QueryType) => Pick<LogicformType, "query" | "sort">;

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

@@ -1,2 +1,3 @@
 export { hydrateResult } from './hydrate-result';
+export { createEntityFetchConditions } from './entity-fetch-conditions';
 export type { EntityFetchRequest, ResultHydratorOptions } from './types';

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

@@ -7,8 +7,15 @@ export interface EntityFetchRequest {
     readonly schema: ResolvedSemanticSchema;
     readonly idProperty: ResolvedSemanticProperty;
     readonly ids: readonly unknown[];
+    /** Fetch candidates ordered by descending start time; retain the first row per ID. */
+    readonly latestVersion?: {
+        readonly startProperty: string;
+        readonly asOf: string;
+    };
 }
 export interface ResultHydratorOptions {
+    readonly expandEntities?: boolean;
+    readonly now?: Date;
     readonly semanticTypes: SemanticTypeRegistry;
     readonly resolveSchema: (schemaId: string) => ResolvedSemanticSchema;
     readonly fetchEntities: (request: EntityFetchRequest) => Promise<readonly DataRow[]>;

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

@@ -0,0 +1,6 @@
+import type { LogicformType } from '../logicform-types';
+import type { OperatorRegistry } from '../operators/index';
+import type { ExecuteOptions, ExecuteResult, ExecuteSuccessResult } from './types';
+/** Runtime operators are handled only as top-level projections. */
+export declare const hasRuntimeProjection: (form: LogicformType, operators: OperatorRegistry) => boolean;
+export declare const executeRuntime: (input: LogicformType, options: ExecuteOptions, operators: OperatorRegistry, executeNested: (form: LogicformType, options: ExecuteOptions) => Promise<ExecuteResult>) => Promise<ExecuteSuccessResult>;

package/dist/executor/sample.d.ts

@@ -0,0 +1,6 @@
+import type { DataRow } from '../physical/index';
+import type { OrderPlan } from '../planner/index';
+export declare const sampleEntityRows: (rows: readonly DataRow[], limit: number, orderBy: readonly OrderPlan[]) => {
+    readonly rows: DataRow[];
+    readonly total: number;
+};

package/dist/executor/types.d.ts

@@ -67,10 +67,16 @@ interface ExecuteBaseOptions {
     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. */
+    /** Table, row, column, and custom metric permissions for this execution. */
     readonly permissions?: Permissions;
     readonly onProgress?: ProgressCallback;
     readonly signal?: AbortSignal;
+    /** Application helpers (for example axios) passed to runtime Operators. SDK helper names are reserved. */
+    readonly runtimeHelpers?: Readonly<Record<string, unknown>>;
+    /** Application configuration passed as the third argument to a runtime Operator's run hook. */
+    readonly runtimeConfig?: Readonly<Record<string, unknown>>;
+    /** Skip entity expansion in this execution; the public result envelope remains unchanged. */
+    readonly result_only?: boolean;
     /** Default time watermark policy; Schema and Property policies override it. */
     readonly timeWatermark?: TimeWatermarkPolicy;
     /** Resource limits for in-process combination of separate physical connections. */
@@ -81,9 +87,9 @@ interface ExecuteBaseOptions {
 }
 export interface ExecuteOptions extends ExecuteBaseOptions {
     /** Physical mappings supplied as JSON definitions. */
-    readonly schemaMappings: readonly SchemaMappingDefinition[];
+    readonly schemaMappings?: readonly SchemaMappingDefinition[];
     /** Database connections addressable by SchemaMappingDefinition.connectionId. */
-    readonly connections: readonly DatabaseConnection[];
+    readonly connections?: readonly DatabaseConnection[];
     /** Provider factories used for built-in or application-defined connection kinds. */
     readonly providerRegistry?: ProviderRegistry;
     /** JSON configuration for an internally owned and reused query-cache connection. */

package/dist/file-import/index.d.ts

@@ -0,0 +1,2 @@
+export { readImportFile } from './read-file';
+export type { CsvEncoding, ImportFile, ReadImportFileOptions, ReadImportFileResult } from './types';

package/dist/file-import/read-file.d.ts

@@ -0,0 +1,2 @@
+import type { ReadImportFileOptions, ReadImportFileResult } from './types';
+export declare const readImportFile: (options: ReadImportFileOptions) => Promise<ReadImportFileResult>;

package/dist/file-import/types.d.ts

@@ -0,0 +1,31 @@
+import type { DataRow } from '../physical/index';
+export type CsvEncoding = 'auto' | 'utf-8' | 'gbk' | 'gb18030' | 'utf-16le' | 'utf-16be';
+export type ImportFile = {
+    readonly path: string;
+    readonly format?: 'csv' | 'xlsx';
+} | {
+    readonly data: Uint8Array;
+    readonly format: 'csv' | 'xlsx';
+};
+export interface ReadImportFileOptions {
+    readonly file: ImportFile;
+    readonly csv?: {
+        readonly encoding?: CsvEncoding;
+        readonly delimiter?: ',' | ';' | '\t' | '|';
+    };
+    readonly excel?: {
+        readonly sheet?: string;
+        readonly headerRow?: number;
+    };
+    /** Defaults to 50 MiB and 100,000 data rows. */
+    readonly maxBytes?: number;
+    readonly maxRows?: number;
+    readonly signal?: AbortSignal;
+}
+export interface ReadImportFileResult {
+    readonly format: 'csv' | 'xlsx';
+    readonly encoding?: Exclude<CsvEncoding, 'auto'>;
+    readonly sheet?: string;
+    readonly columns: readonly string[];
+    readonly rows: readonly DataRow[];
+}

package/dist/index.d.ts

@@ -10,19 +10,22 @@ export { SemanticDBError } from './errors';
 export { builtinSemanticTypes, createSemanticTypeRegistry, resolveSchema, SemanticTypeRegistry, validateResolvedSchema, } from './semantic-types/index';
 export { builtinOperators, createOperatorRegistry, OperatorRegistry, resolveOperator, } from './operators/index';
 export type { LegacySchemaPluginContext, MappingGranularityContext, MappingGranularityPlugin, OutputHandlerContext, OutputHandlerDefinition, IntervalSemanticProperties, IntervalSemanticsDefinition, PlannerPeriodDefinition, PlannerPeriodEvaluation, RelationSemanticsDefinition, RelationTemporalPlan, TimeWatermarkLogicformContext, PropertyMetadataPlugin, QueryOperatorCompileContext, QueryOperatorAuthorizeContext, QueryOperatorDefinition, QueryOperatorNormalizeContext, QueryOperatorPhysicalSource, QueryOperatorPlanContext, QueryOperatorPlanResult, SchemaMetadataPlugin, SchemaMappingPlugin, SemanticDBPlugin, } from './plugins/index';
-export { SchemaMappingRegistry, fromYiAskSchemaMapping, getSupportedDimensions, } from './schema-mappings/index';
-export type { AbsoluteDateValue, CompareOperator, DatePartQueryComparison, DatePartQueryOperand, DateTimeValue, DateValue, EntityIdType, ExpressionItemType, LogicformType, NumericQueryComparison, NumericQueryOperand, PublicLogicformType, PeriodShiftTime, PredItemType, QueryLogicalOperand, QueryExpressionType, RelationQueryType, QueryType, QueryValueType, QueryValueTypeWithCompareOperator, RelativeDateValue, RepresentationType, } from './logicform-types';
+export { SchemaMappingRegistry, sourceIdentity, fromYiAskSchemaMapping, getSupportedDimensions, } from './schema-mappings/index';
+export type { AbsoluteDateValue, CalendarDateQueryValue, CompareOperator, DatePartQueryComparison, DatePartQueryOperand, DateTimeValue, DateValue, EntityIdType, ExpressionItemType, LogicformType, LogicformSampleType, LogicformRandomDataOptions, LogicformRandomDataType, NumericQueryComparison, NumericQueryOperand, PublicLogicformType, PeriodShiftTime, PredItemType, QueryLogicalOperand, QueryExpressionType, RelationQueryType, QueryType, QueryValueType, QueryValueTypeWithCompareOperator, RelativeDateValue, RepresentationType, } from './logicform-types';
 export type { RecursiveQueryType } from './plugins/index';
 export type { PrimalType, PropertyHierarchyDefinition, PropertySqlDefinition, ResolvedSemanticProperty, ResolvedSemanticSchema, SemanticTypeNormalizeContext, SemanticPropertyDraft, SemanticSchemaDraft, SemanticTypeDefinition, SemanticTypeResultContext, SemanticTypeResultProperty, TimeGranularity, TimeWatermarkPolicy, } from './semantic-types/index';
 export type { DataRow, SqlParameters, BuiltinDatabaseConnection, DatabaseConnection, DatabaseConnectionBase, DatabaseConnectionExtensions, ProviderDefinition, ProviderKind, ProviderKindExtensions, } from './physical/index';
 export { DBConnector, ProviderRegistry } from './physical/index';
+export { readImportFile } from './file-import/index';
+export type { CsvEncoding, ImportFile, ReadImportFileOptions, ReadImportFileResult } from './file-import/index';
+export type { DuckDBConnectionOptions, ImportColumn, ImportRowsRequest, ImportRowsResult, ImportFileOptions, ImportFileResult } from './physical/index';
 export type { DBConnectorOptions, RunSQLOptions, GetTableListOptions, DescribeTableOptions, DescribeTableRequest, DatabaseColumn, TableDescription, DatabaseTable, SQLResult, TableListRequest, } from './physical/index';
-export type { OperatorDefinition, OperatorDefaultNameContext, OperatorExecutionContext, OperatorComponentContext, OperatorComponentCalculation, OperatorComponentQuery, OperatorExecutionComponent, OperatorPlanInputContext, OperatorPlannedInput, OperatorGroupKeyShift, OperatorJavaScriptCalculation, OperatorQueryComponent, OperatorEvaluateContext, OperatorOutputPropertyContext, OperatorSqlCapabilities, OperatorSqlContext, ResultProperty, ResultPropertyTemporalMetadata, ResultPropertyTemporalMetadataExtensions, } from './operators/index';
-export type { SchemaMappingDefinition, SchemaMappingEnrichmentDefinition, SchemaMappingEnrichmentKey, SchemaMappingItem, SchemaMappingGranularity, SchemaMappingGranularityExtensions, SchemaMappingPointTemporalDefinition, SchemaMappingPredDefinition, SchemaMappingPredMatch, SchemaMappingSelection, RejectedSchemaMapping, SourceFreshnessPolicy, YiAskSchemaMappingItem, YiAskSchemaMappingRecord, } from './schema-mappings/index';
+export type { OperatorDefinition, OperatorDefaultNameContext, OperatorFormulaTextContext, OperatorExecutionContext, ResolvedTimeRange, OperatorComponentContext, OperatorComponentCalculation, OperatorComponentQuery, OperatorComponentLiteral, OperatorComponentInput, OperatorExecutionComponent, OperatorPlanInputContext, OperatorPlannedInput, OperatorGroupKeyShift, OperatorJavaScriptCalculation, OperatorQueryComponent, OperatorOutputPropertyContext, OperatorRuntimeHelpers, OperatorRuntimeConfig, OperatorRuntimeExecute, OperatorRuntimeRun, OperatorRuntimeValue, OperatorSqlCapabilities, OperatorSqlContext, ResultProperty, ResultPropertyTemporalMetadata, ResultPropertyTemporalMetadataExtensions, } from './operators/index';
+export type { SchemaMappingDefinition, SchemaMappingSource, ResolvedMappingSource, PropertyMappingCalculation, PropertyMappingValue, PropertyMapping, PredItemMapping, IgnoredMapping, ComputationExpression, ComputationInput, SchemaMappingEnrichmentDefinition, SchemaMappingEnrichmentKey, SchemaMappingItem, QueryPathBinding, QueryPathMappingDefinition, SchemaMappingGranularity, SchemaMappingGranularityExtensions, SchemaMappingPointTemporalDefinition, SchemaMappingPredDefinition, SchemaMappingPredMatch, SchemaMappingSelection, RejectedSchemaMapping, SourceFreshnessPolicy, YiAskSchemaMappingItem, YiAskSchemaMappingRecord, } from './schema-mappings/index';
 export { QueryCacheManager } from './cache/index';
 export type { InvalidateQueryCacheSourceOptions, QueryCacheConfiguration, } from './cache/index';
 export type { ExecuteOptions, ExecuteFailureResult, ExecuteProgressEvent, ExecuteResult, ExecuteSuccessResult, ExecutedSql, ExecutedSqlSchemaMapping, ExecutedSqlType, SqlExecutionSource, PartialExecuteResult, ProgressCallback, } from './executor/index';
-export type { ColumnPermissions, Permissions, SchemaPermissions, } from './permissions/index';
+export type { ColumnPermissions, MetricPermissions, Permissions, SchemaPermissions, } from './permissions/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

@@ -3,7 +3,7 @@ export type RepresentationType = 'value' | 'table' | 'pie' | 'bar' | 'column' |
 /** A concrete timestamp accepted by a LogicForm query. */
 export type DateTimeValue = `${number}-${number}-${number} ${number}:${number}:${number}`;
 /** A relative period resolved from the execution clock. */
-export interface RelativeDateValue {
+export interface RelativeDateValue extends AbsoluteDateValue {
     readonly granularity: TimeGranularity;
     readonly offset: number;
 }
@@ -22,7 +22,14 @@ export interface AbsoluteDateValue {
 /** Period reference used by operators such as `$periodShift`. */
 export type PeriodShiftTime = RelativeDateValue | AbsoluteDateValue;
 /** A date value before semantic-type normalization. */
-export type DateValue = string | RelativeDateValue | AbsoluteDateValue;
+export type DateValue = string | RelativeDateValue | AbsoluteDateValue | CalendarDateQueryValue;
+/** Calendar selections; comparison components and finer parts become date-part filters. */
+export type CalendarDateQueryValue = {
+    readonly [Part in Exclude<keyof AbsoluteDateValue, 'period'>]?: DatePartQueryOperand;
+} & {
+    readonly granularity?: TimeGranularity;
+    readonly offset?: number;
+};
 /** Stable entity identity. Numeric IDs must be safe integers. */
 export type EntityIdType = string | number;
 export type CompareOperator = '$eq' | '$gt' | '$gte' | '$lt' | '$lte' | '$ne' | '$in' | '$nin' | '$exists' | '$regex' | '$contains' | '$startsWith' | '$length' | '$and' | '$or' | '$second' | '$minute' | '$hour' | '$weekday' | '$day' | '$week' | '$month' | '$quarter' | '$year' | Extract<keyof QueryOperatorExtensions, string>;
@@ -118,6 +125,16 @@ export interface LogicformOutputType {
     type: LogicformOutputTypeValue;
     filename?: string;
 }
+/** Enable uniform sampling of distinct entity rows; top-level limit controls the count. */
+export type LogicformSampleType = boolean;
+/** Presentation-only numeric perturbation; each output cell gets an independent multiplier. */
+export interface LogicformRandomDataOptions {
+    /** Minimum multiplier (inclusive). Defaults to 0.1. */
+    readonly minFactor?: number;
+    /** Maximum multiplier (exclusive unless equal to minFactor). Defaults to 1.5. */
+    readonly maxFactor?: number;
+}
+export type LogicformRandomDataType = boolean | LogicformRandomDataOptions;
 export interface LogicformType {
     /** LogicForm protocol version. This SDK supports version 2.0 and later. */
     version: string;
@@ -129,6 +146,9 @@ export interface LogicformType {
     propertyResolve?: Readonly<Record<string, Readonly<Record<string, string>>>>;
     groupby?: PredItemType[];
     sort?: Record<string, 1 | -1>;
+    sample?: LogicformSampleType;
+    /** Perturb final scalar numeric values, excluding grouping keys and identities. Top-level only. */
+    randomData?: LogicformRandomDataType;
     having?: QueryType;
     output?: LogicformOutputType;
     limit?: number;

package/dist/normalizer/core.d.ts

@@ -3,7 +3,14 @@ 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';
+import type { ResolvedTimeRange } from '../operators/index';
 export interface NormalizeLogicformOptions {
+    /** Reports only this call's main query, never nested or metric queries. */
+    readonly onTimeRangeResolved?: (range: ResolvedTimeRange | undefined) => void;
+    /** Internal recursion guard: sampling is a top-level result operation. */
+    readonly allowSample?: boolean;
+    /** Internal recursion guard: numeric perturbation applies only to the final result. */
+    readonly allowRandomData?: boolean;
     readonly semanticTypes: SemanticTypeRegistry;
     readonly operators?: OperatorRegistry;
     readonly plugins?: readonly SemanticDBPlugin[];

package/dist/normalizer/index.d.ts

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

package/dist/normalizer/main-time-range.d.ts

@@ -0,0 +1,9 @@
+import type { ResolvedTimeRange } from '../operators/index';
+import type { ResolvedSemanticProperty, ResolvedSemanticSchema, SemanticTypeNormalizeContext } from '../semantic-types/index';
+/** Collect only the root query; metric, relation and nested LF queries never enter here. */
+export declare class MainTimeRangeCollector {
+    #private;
+    invalidate(): void;
+    observe(schema: ResolvedSemanticSchema, property: ResolvedSemanticProperty, queryPath: readonly (string | number)[], customNormalization: boolean): SemanticTypeNormalizeContext['onDateQueryNormalized'];
+    get result(): ResolvedTimeRange | undefined;
+}

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

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

package/dist/normalizer/query.d.ts

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

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

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

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

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

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

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

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

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

package/dist/operators/index.d.ts

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

package/dist/operators/registry.d.ts

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