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

package/README.md

@@ -167,6 +167,114 @@ Providers execute only parameterized `sql + parameters`; SemanticDB never execut
 Because `displaySql` contains literal values and may expose sensitive data, use it only in trusted
 debugging and observability channels.
 
+### Native SQL and table discovery
+
+`DBConnector` provides trusted physical database operations independently of LogicForm execution:
+
+```ts
+import { DBConnector, Logicform } from 'semanticdb-v2';
+import type { DatabaseConnection } from 'semanticdb-v2';
+
+const connection = {
+  id: 'analytics',
+  kind: 'mysql',
+  host: 'localhost',
+  user: 'analytics',
+  password: process.env.MYSQL_PASSWORD ?? '',
+  database: 'analytics',
+} satisfies DatabaseConnection;
+
+const tables = await DBConnector.getTableList({ connection });
+// [{ name: 'orders', database: 'analytics', type: 'table' }, ...]
+
+const description = await DBConnector.describeTable({ connection, table: 'orders' });
+// {
+//   columns: [{ name: 'id', type: 'int', comment: 'Order ID', primaryKey: true, exampleValue: 42 }, ...],
+//   tableInfo: { name: 'orders', database: 'analytics', type: 'table', comment: 'Orders' },
+// }
+
+const { rows } = await DBConnector.runSQL({
+  connection,
+  sql: 'SELECT * FROM orders WHERE status = ?',
+  parameters: ['paid'],
+});
+
+const updated = await DBConnector.runSQL({
+  connection,
+  sql: 'UPDATE orders SET status = ? WHERE id = ?',
+  parameters: ['shipped', 42],
+});
+// { rows: [], affectedRows: 1 }
+
+// The exact same object belongs in Logicform.execute's connections array:
+// await Logicform.execute(logicform, { connections: [connection], schemas, schemaMappings });
+
+await Logicform.close(); // DBConnector.close() is the same shutdown operation.
+```
+
+Both APIs share providers and connection pools by connection ID and `providerRegistry`. An ID must
+retain the same configuration until shutdown. Providers and pools are initialized lazily. Either
+`close()` releases **all** SDK-managed connections, including those used by the other API; it does
+not close just the last connector connection.
+
+`runSQL` returns `{ rows: DataRow[], affectedRows?: number }`. Commands without a result set return
+an empty array; affected-row counts are included only when the driver reports them. SQL is passed
+through without automatic LIMIT, dialect translation, Schema mapping, hydration, generated `_id`,
+or query caching. It does **not** enforce `ExecuteOptions.permissions`: use trusted callers and
+appropriately restricted database accounts. Supply values through `parameters` using the native
+provider placeholders: `?` for MySQL-compatible databases, Databricks, Dameng, Snowflake and MaxCompute;
+`$1` for PostgreSQL; `@p0` for SQL Server; `:1` for Oracle; typed `{p0:String}`-style
+placeholders for ClickHouse. ClickHouse uses JSONEachRow output; do not override it with another
+FORMAT. Each call is independent, with Oracle/Dameng command execution automatically committed;
+cross-call transactions and multi-statement/multi-result execution are not supported.
+
+`getTableList` returns `{ name, database?, schema?, type: 'table' | 'view' }[]` for accessible tables
+and views, retaining namespaces to distinguish same-name tables. Optional `database` and `schema`
+override only this metadata lookup, never the cached connection configuration:
+
+- MySQL, Doris, StarRocks, GBase and ClickHouse: `database`; `schema` is rejected.
+- PostgreSQL, Oracle and Dameng: `schema`; cross-database overrides are rejected. Defaults to the
+  current schema (or the configured Dameng schema).
+- SQL Server and Snowflake: `database` and `schema`. SQL Server lists all accessible schemas in
+  the database by default; Snowflake defaults to the current schema.
+- Databricks: `database` means catalog, and `schema` means schema. Defaults come from the connection's
+  `catalog` and `schema` (`connection.database` remains the existing legacy alias for schema).
+- MaxCompute: the existing injected client handles `SHOW TABLES`, returning rows with `table_name`.
+  It may implement `getTableList(request)` for project/schema overrides and view metadata, and
+  `runSQL(request)` for affected-row counts. Otherwise commands must return `[]` through `execute`.
+
+`describeTable({ connection, table, database?, schema?, includeSample? })` inspects one physical
+table or view. `table` is a literal **unqualified** name; provide its namespace separately, using
+the same scope rules as `getTableList`. A dot inside `table` is part of the identifier, not a separator.
+Do not pass a SQL expression or the legacy semantic Schema/`from` object. SQL Server descriptions
+default to the connection's current default schema; pass `schema` explicitly when describing a
+table returned from another schema. Column order follows the database's definition.
+
+The result has `columns: { name, type, comment, primaryKey?, exampleValue? }[]` and
+`tableInfo: { name, database?, schema?, type, comment }`. These are physical names/native types,
+not semantic Properties; no `_id` is added. Comments default to an empty string. Primary-key
+membership includes every column of composite keys; unique-only indexes are not primary keys.
+ClickHouse reports its storage primary key, which does not imply relational uniqueness. If the
+adapter cannot determine primary-key membership (Databricks/Snowflake), `primaryKey` is omitted
+rather than guessed. Example values preserve driver types, including `null`.
+
+Like the legacy API, descriptions read one example row by default. Set `includeSample: false`
+for metadata-only inspection, avoiding a data read. Empty tables and failed sample queries still
+return metadata without example values; metadata failures, tables not found in the selected namespace, and
+cancellation reject. All SQL uses bound metadata values and quoted identifiers, bypassing
+LogicForm permissions and caching just like `runSQL`.
+
+MaxCompute clients may implement `describeTable(request)` to provide project/schema-aware
+metadata. Otherwise the fallback runs `DESC` and expects structured rows with `column_name`,
+`column_type`, optional `column_comment` and `is_primary_key`. Legacy UDBC ASCII `Info` reports
+must be normalized by the client; unparsed reports are rejected rather than producing empty columns.
+
+All operations accept `signal` and the same optional `providerRegistry` as `Logicform.execute`.
+Custom providers opt in through `runSQL(request)`, `getTableList(request)` and `describeTable(request)`; missing capabilities
+fail explicitly without changing the existing provider `execute` contract. Unsupported discovery
+scopes are rejected rather than silently ignored. Cancellation does not guarantee rollback of
+commands that have already reached the database.
+
 ### Permissions
 
 Pass table, row, and column permissions together through `ExecuteOptions.permissions`:
@@ -475,9 +583,10 @@ comments, or parameter placeholders. Property UDFs do not support the legacy `fu
 ### Query cache
 
 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, connection id, provider, SQL, and parameters. Physical expiration belongs to each Schema
-mapping's `freshness` policy. See [Query cache and Redis](docs/query-cache.md).
+internally managed Redis query cache. Pass its JSON connection configuration through `cache`;
+cache identity includes namespace, connection id, provider, SQL, and parameters. Physical
+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
@@ -490,14 +599,21 @@ separate Schema Mapping `dimensions` field. The planner selects a source that co
 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:
+When Redis is shared with other applications, pass an application-specific key prefix in the
+execution JSON. SemanticDB reuses the connection by `cache.id`:
 
 ```ts
-import { createRedisQueryCache } from 'semanticdb-v2/cache/redis';
-
-const cache = await createRedisQueryCache({
-  url: process.env.REDIS_URL,
-  keyPrefix: process.env.REDIS_KEY_PREFIX,
+await Logicform.execute(logicform, {
+  schemas,
+  schemaMappings,
+  connections,
+  cache: {
+    id: 'redis-main',
+    kind: 'redis',
+    url: process.env.REDIS_URL ?? 'redis://localhost:6379/0',
+    keyPrefix: process.env.REDIS_KEY_PREFIX,
+    namespace: 'tenant-a:mysql-sales',
+  },
 });
 ```
 

package/dist/cache/index.d.ts

@@ -1,3 +1,4 @@
 export { nextDailyExpiration, resolveQueryExpiration, } from './expiry';
 export { queryCacheIdentityHash, sourceCacheIndexHash, } from './identity';
-export type { QueryCache, QueryCacheExecutionOptions, QueryCacheIdentity, QueryCacheWriteOptions, } from './types';
+export type { InvalidateQueryCacheSourceOptions, QueryCache, QueryCacheConfiguration, QueryCacheExecutionOptions, QueryCacheIdentity, QueryCacheWriteOptions, } from './types';
+export { QueryCacheManager } from './manager';

package/dist/cache/manager.d.ts

@@ -0,0 +1,5 @@
+import type { InvalidateQueryCacheSourceOptions } from './types';
+/** Operations for internally managed query-cache connections. */
+export declare const QueryCacheManager: Readonly<{
+    invalidateSource: ({ cache, source }: InvalidateQueryCacheSourceOptions) => Promise<void>;
+}>;

package/dist/cache/registry.d.ts

@@ -0,0 +1,14 @@
+import type { QueryCache, QueryCacheConfiguration, QueryCacheExecutionOptions } from './types';
+type QueryCacheConnection = Omit<QueryCacheConfiguration, 'namespace'>;
+type QueryCacheFactory = (connection: QueryCacheConnection) => Promise<QueryCache>;
+/** Internally owns and reuses cache connections by stable configuration id. */
+export declare class QueryCacheRegistry {
+    #private;
+    private readonly create;
+    constructor(create?: QueryCacheFactory);
+    get(configuration: QueryCacheConfiguration): Promise<QueryCacheExecutionOptions>;
+    close(): Promise<void>;
+}
+export declare const resolveQueryCache: (configuration: QueryCacheConfiguration) => Promise<QueryCacheExecutionOptions>;
+export declare const closeQueryCaches: () => Promise<void>;
+export {};

package/dist/cache/types.d.ts

@@ -27,3 +27,18 @@ export interface QueryCacheExecutionOptions {
     /** Isolates tenants and physical data sources that can produce identical SQL. */
     readonly namespace: string;
 }
+/** Redis connection and cache namespace supplied as JSON at the public execution boundary. */
+export interface QueryCacheConfiguration {
+    /** Stable identity used to reuse one internally managed Redis connection. */
+    readonly id: string;
+    readonly kind: 'redis';
+    readonly url: string;
+    readonly keyPrefix?: string;
+    /** Isolates tenants and physical data sources that can produce identical SQL. */
+    readonly namespace: string;
+}
+export interface InvalidateQueryCacheSourceOptions {
+    readonly cache: QueryCacheConfiguration;
+    /** Physical Schema Mapping source to invalidate. */
+    readonly source: string;
+}

package/dist/close.d.ts

@@ -0,0 +1 @@
+export declare const closeSemanticDB: () => Promise<void>;

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

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

package/dist/executor/types.d.ts

@@ -1,11 +1,11 @@
-import type { OperatorDefinition, OperatorRegistry } from '../operators/index';
+import type { OperatorDefinition, OperatorExecutionContext, OperatorRegistry } from '../operators/index';
 import type { CoreComputeProvider, DataRow, ProviderRegistry, SqlParameters } from '../physical/index';
 import type { DatabaseConnection } from '../physical/index';
 import type { LogicalPlan, QueryLineage } from '../planner/index';
 import type { SchemaMappingDefinition, SchemaMappingRegistry, SchemaMappingSelection } from '../schema-mappings/index';
 import type { ResolvedSemanticSchema, SemanticSchemaDraft, SemanticTypeRegistry, TimeWatermarkPolicy } from '../semantic-types/index';
 import type { LogicformType, PublicLogicformType } from '../logicform-types';
-import type { QueryCacheExecutionOptions } from '../cache/index';
+import type { QueryCacheConfiguration, QueryCacheExecutionOptions } from '../cache/index';
 import type { Permissions } from '../permissions/index';
 import type { SemanticDBPlugin } from '../plugins/index';
 import type { LocaleInput, LocaleRegistry } from '../i18n/index';
@@ -69,8 +69,6 @@ interface ExecuteBaseOptions {
     readonly locales?: LocaleInput;
     /** Table, row, and column permissions for this execution. */
     readonly permissions?: Permissions;
-    /** 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. */
@@ -88,12 +86,16 @@ export interface ExecuteOptions extends ExecuteBaseOptions {
     readonly connections: readonly DatabaseConnection[];
     /** Provider factories used for built-in or application-defined connection kinds. */
     readonly providerRegistry?: ProviderRegistry;
+    /** JSON configuration for an internally owned and reused query-cache connection. */
+    readonly cache?: QueryCacheConfiguration;
 }
 /** Internal execution seam used by executor tests after a provider has been resolved. */
 export interface InternalExecuteOptions extends Omit<ExecuteBaseOptions, 'operators'> {
     readonly operators?: OperatorRegistry;
     /** The public execution boundary has already merged built-in, plugin, and explicit Operators. */
     readonly operatorsResolved?: boolean;
+    /** Present for nested executions to reuse or intentionally suppress calendar preloading. */
+    readonly executionContext?: OperatorExecutionContext;
     /** The public execution boundary has already merged plugin SemanticTypes. */
     readonly semanticTypesResolved?: boolean;
     readonly localeRegistry?: LocaleRegistry;
@@ -101,6 +103,8 @@ export interface InternalExecuteOptions extends Omit<ExecuteBaseOptions, 'operat
     /** Resolve providers for additional physical connections in a federated execution. */
     readonly providerForConnection?: (connectionId: string) => CoreComputeProvider;
     readonly schemaMappings: SchemaMappingRegistry;
+    /** Cache connection already resolved at the public execution boundary. */
+    readonly cache?: QueryCacheExecutionOptions;
     /** Selected connection for public execution; omitted only by internal provider tests. */
     readonly connectionId?: string;
 }

package/dist/index.d.ts

@@ -9,17 +9,16 @@ export { builtinSemanticTypes, createSemanticTypeRegistry, resolveSchema, Semant
 export { builtinOperators, createOperatorRegistry, OperatorRegistry, resolveOperator, } from './operators/index';
 export type { LegacySchemaPluginContext, MappingGranularityContext, MappingGranularityPlugin, OutputHandlerContext, OutputHandlerDefinition, IntervalSemanticProperties, IntervalSemanticsDefinition, PlannerPeriodDefinition, PlannerPeriodEvaluation, RelationSemanticsDefinition, RelationTemporalPlan, TimeWatermarkLogicformContext, PropertyMetadataPlugin, QueryOperatorCompileContext, QueryOperatorAuthorizeContext, QueryOperatorDefinition, QueryOperatorNormalizeContext, QueryOperatorPhysicalSource, QueryOperatorPlanContext, QueryOperatorPlanResult, SchemaMetadataPlugin, SchemaMappingPlugin, SemanticDBPlugin, } from './plugins/index';
 export { SchemaMappingRegistry, fromYiAskSchemaMapping, } from './schema-mappings/index';
-export type { AbsoluteDateValue, CompareOperator, DatePartQueryComparison, DatePartQueryOperand, CalendarDateValue, DateTimeValue, DateValue, EntityIdType, ExpressionItemType, LogicformType, NumericQueryComparison, NumericQueryOperand, PublicLogicformType, PeriodShiftTime, PredItemType, QueryLogicalOperand, QueryExpressionType, RelationQueryType, QueryType, QueryValueType, QueryValueTypeWithCompareOperator, RelativeDateValue, RepresentationType, } from './logicform-types';
+export type { AbsoluteDateValue, CompareOperator, DatePartQueryComparison, DatePartQueryOperand, DateTimeValue, DateValue, EntityIdType, ExpressionItemType, LogicformType, NumericQueryComparison, NumericQueryOperand, PublicLogicformType, PeriodShiftTime, PredItemType, QueryLogicalOperand, QueryExpressionType, RelationQueryType, QueryType, QueryValueType, QueryValueTypeWithCompareOperator, RelativeDateValue, RepresentationType, } from './logicform-types';
 export type { RecursiveQueryType } from './plugins/index';
-export { 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, 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 { ProviderRegistry } from './physical/index';
-export type { OperatorDefinition, OperatorDefaultNameContext, OperatorComponentContext, OperatorComponentCalculation, OperatorComponentQuery, OperatorExecutionComponent, OperatorPlanInputContext, OperatorPlannedInput, OperatorGroupKeyShift, OperatorJavaScriptCalculation, OperatorQueryComponent, OperatorEvaluateContext, OperatorOutputPropertyContext, OperatorSqlCapabilities, OperatorSqlContext, ResultProperty, ResultPropertyTemporalMetadata, ResultPropertyTemporalMetadataExtensions, } from './operators/index';
+export { DBConnector, ProviderRegistry } from './physical/index';
+export type { DBConnectorOptions, RunSQLOptions, GetTableListOptions, DescribeTableOptions, DescribeTableRequest, DatabaseColumn, TableDescription, DatabaseTable, SQLResult, TableListRequest, } from './physical/index';
+export type { OperatorDefinition, OperatorDefaultNameContext, OperatorExecutionContext, OperatorComponentContext, OperatorComponentCalculation, OperatorComponentQuery, OperatorExecutionComponent, OperatorPlanInputContext, OperatorPlannedInput, OperatorGroupKeyShift, OperatorJavaScriptCalculation, OperatorQueryComponent, OperatorEvaluateContext, OperatorOutputPropertyContext, OperatorSqlCapabilities, OperatorSqlContext, ResultProperty, ResultPropertyTemporalMetadata, ResultPropertyTemporalMetadataExtensions, } from './operators/index';
 export type { SchemaMappingDefinition, SchemaMappingEnrichmentDefinition, SchemaMappingEnrichmentKey, SchemaMappingItem, SchemaMappingGranularity, SchemaMappingGranularityExtensions, SchemaMappingPointTemporalDefinition, SchemaMappingPredDefinition, SchemaMappingPredMatch, SchemaMappingSelection, RejectedSchemaMapping, SourceFreshnessPolicy, YiAskSchemaMappingItem, YiAskSchemaMappingRecord, } from './schema-mappings/index';
-export type { QueryCache, QueryCacheExecutionOptions, QueryCacheIdentity, QueryCacheWriteOptions, } from './cache/index';
+export { QueryCacheManager } from './cache/index';
+export type { InvalidateQueryCacheSourceOptions, QueryCacheConfiguration, } 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 { CreateLogicalPlanOptions, LogicalPlan, QueryLineage, } from './planner/index';

package/dist/logicform-types.d.ts

@@ -19,21 +19,10 @@ export interface AbsoluteDateValue {
     readonly second?: number;
     readonly period?: 'am' | 'pm';
 }
-/** A business-calendar period resolved to natural days before planning. */
-export interface CalendarDateValue {
-    readonly calendar: string;
-    readonly key?: string;
-    readonly year?: number;
-    readonly quarter?: number;
-    readonly month?: number;
-    readonly week?: number;
-    readonly day?: number;
-    readonly relativeDay?: number | readonly number[];
-}
 /** Period reference used by operators such as `$periodShift`. */
 export type PeriodShiftTime = RelativeDateValue | AbsoluteDateValue;
 /** A date value before semantic-type normalization. */
-export type DateValue = string | RelativeDateValue | AbsoluteDateValue | CalendarDateValue;
+export type DateValue = string | RelativeDateValue | AbsoluteDateValue;
 /** Stable entity identity. Numeric IDs must be safe integers. */
 export type EntityIdType = string | number;
 export type CompareOperator = '$eq' | '$gt' | '$gte' | '$lt' | '$lte' | '$ne' | '$in' | '$nin' | '$exists' | '$regex' | '$contains' | '$startsWith' | '$length' | '$and' | '$or' | '$second' | '$minute' | '$hour' | '$weekday' | '$day' | '$week' | '$month' | '$quarter' | '$year' | Extract<keyof QueryOperatorExtensions, string>;

package/dist/normalizer/core.d.ts

@@ -16,6 +16,15 @@ export interface NormalizeLogicformOptions {
     readonly now?: Date;
     readonly resolveSchema?: (schemaId: string) => ResolvedSemanticSchema;
     readonly requestTimeWatermark?: (schema: ResolvedSemanticSchema, property: ResolvedSemanticProperty, requestedUpperBound: Date) => Promise<Date | undefined>;
+    readonly requestAutoCaseBounds?: (schema: ResolvedSemanticSchema, reference: string, query: LogicformType['query']) => Promise<{
+        readonly min: number;
+        readonly max: number;
+        readonly count: number;
+    } | {
+        readonly empty: true;
+    }>;
+    /** Internal root query used to resolve automatic `$case` boundaries. */
+    readonly autoCaseQuery?: LogicformType['query'];
     readonly resolveFromSchema?: (normalizedFrom: LogicformType, outerSchema: ResolvedSemanticSchema) => ResolvedSemanticSchema;
     readonly canProjectProperty?: (schema: ResolvedSemanticSchema, property: ResolvedSemanticProperty) => boolean;
     /** Internal recursion hook installed by normalizeLogicform. */

package/dist/operators/index.d.ts

@@ -3,6 +3,6 @@ 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, OperatorPeriodBoundaryPolicy, OperatorPeriodBoundaryPolicyContext, OperatorNormalizePredContext, OperatorPlanExpressionContext, OperatorPeriodEvaluationContext, OperatorPlanInputContext, OperatorPlannedInput, OperatorRewriteLogicformContext, OperatorValidatePlanContext, OperatorSqlCapabilities, OperatorSqlContext, ResultProperty, ResultPropertyTemporalMetadata, ResultPropertyTemporalMetadataExtensions, } from './types';
+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 declare const builtinOperators: readonly import("./types").OperatorDefinition[];
 export declare const createOperatorRegistry: (plugins?: readonly SemanticDBPlugin[]) => OperatorRegistry;

package/dist/operators/registry.d.ts

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

package/dist/operators/types.d.ts

@@ -3,6 +3,15 @@ import type { LogicformType, PredItemType } from '../logicform-types';
 import type { DataRow } from '../physical/index';
 import type { Expression, LogicalPlan } from '../planner/index';
 import type { LocaleTranslate } from '../i18n/index';
+/** Immutable data shared by all Operator hooks during one LogicForm execution. */
+export interface OperatorExecutionContext {
+    /** Complete rows from the unique Schema marked with `is_calendar`. */
+    readonly calendar?: readonly Readonly<DataRow>[];
+}
+interface OperatorHookContext {
+    /** Always supplied by the executor; optional for direct unit-level hook invocation. */
+    readonly executionContext?: OperatorExecutionContext;
+}
 export interface OperatorSqlCapabilities {
     /** Produce a dialect-specific aggregate function around an expression. */
     aggregateFunction(name: string, expression?: string): string;
@@ -24,7 +33,7 @@ export interface OperatorSqlCapabilities {
     condition(expression: string, condition: unknown): string;
 }
 /** Context passed to an operator that pushes its computation into SQL. */
-export interface OperatorSqlContext {
+export interface OperatorSqlContext extends OperatorHookContext {
     readonly sql: OperatorSqlCapabilities;
     /** SQL for the nested input expression, when this operator has one. */
     readonly expression?: string;
@@ -36,7 +45,7 @@ export interface OperatorSqlContext {
     readonly args: Readonly<Record<string, unknown>>;
 }
 /** Context passed to an operator evaluated after the provider returns rows. */
-export interface OperatorEvaluateContext {
+export interface OperatorEvaluateContext extends OperatorHookContext {
     /** Value produced by the nested expression, or undefined for a propertyless operator. */
     readonly input: unknown;
     /** Operator-specific LogicForm arguments. */
@@ -82,7 +91,7 @@ export type ResultPropertyTemporalMetadata = {
         readonly date: string;
     }[];
 } | ResultPropertyTemporalMetadataExtensions[keyof ResultPropertyTemporalMetadataExtensions];
-export interface OperatorOutputPropertyContext {
+export interface OperatorOutputPropertyContext extends OperatorHookContext {
     /** Final alias assigned to this operator's single output column. */
     readonly name: string;
     /** Original Schema property when the operator starts from a physical property. */
@@ -95,13 +104,13 @@ export interface OperatorOutputPropertyContext {
     readonly args: Readonly<Record<string, unknown>>;
 }
 /** Context used by operators whose value must be evaluated per time bucket. */
-export interface OperatorPeriodEvaluationContext {
+export interface OperatorPeriodEvaluationContext extends OperatorHookContext {
     readonly logicform: LogicformType;
     readonly pred: PredItemType;
     readonly schema: ResolvedSemanticSchema;
     readonly inputProperty?: ResolvedSemanticProperty;
 }
-export interface OperatorDefaultNameContext {
+export interface OperatorDefaultNameContext extends OperatorHookContext {
     /** Name produced by the direct pred inputs or localized row label. */
     readonly operandName: string;
     /** Name of a direct or nested pred input. */
@@ -115,7 +124,7 @@ export interface OperatorDefaultNameContext {
     /** Translate a stable message key using the requested locale. */
     readonly t?: LocaleTranslate;
 }
-export interface OperatorPlanInputContext {
+export interface OperatorPlanInputContext extends OperatorHookContext {
     /** Canonical property or relation reference supplied as this operator's direct pred. */
     readonly reference: string;
     readonly args: Readonly<Record<string, unknown>>;
@@ -128,11 +137,11 @@ export interface OperatorPlannedInput {
     /** Provider-independent arguments resolved from semantic metadata. */
     readonly args: Readonly<Record<string, unknown>>;
 }
-export interface OperatorNormalizePredContext {
+export interface OperatorNormalizePredContext extends OperatorHookContext {
     readonly pred: PredItemType;
     readonly schema: ResolvedSemanticSchema;
 }
-export interface OperatorPlanExpressionContext {
+export interface OperatorPlanExpressionContext extends OperatorHookContext {
     readonly pred: PredItemType;
     readonly input?: Expression;
     readonly inputProperty?: ResultProperty;
@@ -142,29 +151,29 @@ export interface OperatorPlanExpressionContext {
     readonly getOperator: (name: string) => OperatorDefinition;
     readonly planQuery: (query: Readonly<Record<string, unknown>>) => Readonly<Record<string, unknown>>;
 }
-export interface OperatorPeriodBoundaryPolicyContext {
+export interface OperatorPeriodBoundaryPolicyContext extends OperatorHookContext {
     readonly pred: PredItemType;
 }
 export interface OperatorPeriodBoundaryPolicy {
     readonly boundary: 'start' | 'end';
     readonly implicit: boolean;
 }
-export interface OperatorValidatePlanContext {
+export interface OperatorValidatePlanContext extends OperatorHookContext {
     readonly pred: PredItemType;
     readonly groupByNames: readonly string[];
     readonly resolveGroupName: (reference: string) => string | undefined;
     readonly getOperator: (name: string) => OperatorDefinition;
 }
-export interface OperatorValidateGroupbyContext {
+export interface OperatorValidateGroupbyContext extends OperatorHookContext {
     readonly pred: PredItemType;
 }
-export interface OperatorRewriteLogicformContext {
+export interface OperatorRewriteLogicformContext extends OperatorHookContext {
     readonly logicform: LogicformType;
     readonly schema: ResolvedSemanticSchema;
     /** Resolve operator metadata while rewriting nested expressions. */
     readonly getOperator?: (name: string) => OperatorDefinition;
 }
-export interface OperatorComponentContext {
+export interface OperatorComponentContext extends OperatorHookContext {
     /** Fully normalized LogicForm containing this top-level operator projection. */
     readonly logicform: LogicformType;
     /** Caller-authored normalized LogicForm before executor row policies were added. */
@@ -268,7 +277,7 @@ interface OperatorDefinitionBase {
     /** Validate semantics that apply only when this Operator is used as a group key. */
     readonly validateGroupby?: (context: OperatorValidateGroupbyContext) => void;
     /** The logical planner may fully lower a component, so no executor child query is needed. */
-    readonly skipComponentExecution?: (context: {
+    readonly skipComponentExecution?: (context: OperatorHookContext & {
         readonly plan: LogicalPlan;
     }) => boolean;
     /** Expand high-level operator semantics into ordinary nested LogicForm objects before planning. */

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

@@ -1,4 +1,4 @@
-import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest } from './provider';
+import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest, SQLResult, DatabaseTable, TableListRequest, DescribeTableRequest, TableDescription } from './provider';
 interface ClickHouseResultLike {
     json<T>(): Promise<T>;
 }
@@ -9,6 +9,17 @@ export interface ClickHouseClientLike {
         query_params: Readonly<Record<string, unknown>>;
         abort_signal?: AbortSignal;
     }): Promise<ClickHouseResultLike>;
+    /** Native SDK exec does not append a FORMAT clause to commands. */
+    exec?(options: {
+        query: string;
+        query_params: Readonly<Record<string, unknown>>;
+        clickhouse_settings: {
+            readonly default_format: 'JSONEachRow';
+        };
+        abort_signal?: AbortSignal;
+    }): Promise<{
+        readonly stream: AsyncIterable<string | Buffer>;
+    }>;
     close(): Promise<void>;
 }
 export interface ClickHouseProviderOptions {
@@ -52,6 +63,9 @@ export declare class ClickHouseProvider implements CoreComputeProvider {
         valueExpression: string;
     };
     execute(request: ProviderExecutionRequest): Promise<DataRow[]>;
+    getTableList(request: TableListRequest): Promise<DatabaseTable[]>;
+    describeTable(request: DescribeTableRequest): Promise<TableDescription>;
+    runSQL(request: ProviderExecutionRequest): Promise<SQLResult>;
     close(): Promise<void>;
 }
 export {};

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

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

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

@@ -1,4 +1,4 @@
-import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest } from './provider';
+import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest, SQLResult, DatabaseTable, TableListRequest, DescribeTableRequest, TableDescription } from './provider';
 type DamengBind = string | number | Date | Buffer | null;
 export interface DamengConnectionOptions {
     readonly connectString?: string;
@@ -15,8 +15,10 @@ export interface DamengConnectionOptions {
 export interface DamengConnectionLike {
     execute(sql: string, binds: DamengBind[], options: {
         readonly outFormat: number;
+        readonly autoCommit?: boolean;
     }): Promise<{
         readonly rows?: unknown[];
+        readonly rowsAffected?: number;
     }>;
     close(): Promise<void>;
 }
@@ -56,6 +58,9 @@ export declare class DamengProvider implements CoreComputeProvider {
     stringLength(expression: string): string;
     regex(expression: string, pattern: string, options?: string): string;
     execute(request: ProviderExecutionRequest): Promise<DataRow[]>;
+    runSQL(request: ProviderExecutionRequest): Promise<SQLResult>;
+    getTableList(request: TableListRequest): Promise<DatabaseTable[]>;
+    describeTable(request: DescribeTableRequest): Promise<TableDescription>;
     close(): Promise<void>;
 }
 export {};

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

@@ -1,4 +1,4 @@
-import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest } from './provider';
+import type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest, SQLResult, DatabaseTable, TableListRequest, DescribeTableRequest, TableDescription } from './provider';
 type DatabricksBind = string | number | boolean | bigint | Date | null;
 export interface DatabricksConnectionBase {
     readonly host: string;
@@ -29,6 +29,8 @@ export interface DatabricksOAuthAuth {
 export type DatabricksConnectionOptions = DatabricksConnectionBase & (DatabricksAccessTokenAuth | DatabricksOAuthAuth);
 export interface DatabricksOperationLike {
     fetchAll(): Promise<unknown>;
+    /** The native SDK can finish commands that have no result set to fetch. */
+    finished?(): Promise<void>;
     cancel(): Promise<unknown>;
     close(): Promise<unknown>;
 }
@@ -78,6 +80,9 @@ export declare class DatabricksProvider implements CoreComputeProvider {
         valueExpression: string;
     };
     execute(request: ProviderExecutionRequest): Promise<DataRow[]>;
+    runSQL(request: ProviderExecutionRequest): Promise<SQLResult>;
+    describeTable(request: DescribeTableRequest): Promise<TableDescription>;
+    getTableList(request: TableListRequest): Promise<DatabaseTable[]>;
     close(): Promise<void>;
 }
 export {};

package/dist/physical/db-connector.d.ts

@@ -0,0 +1,23 @@
+import type { DatabaseConnection, ProviderRegistry } from './connection';
+import type { DatabaseTable, SQLResult, SqlParameters, TableListRequest, DescribeTableRequest, TableDescription } from './provider';
+export interface DBConnectorOptions {
+    /** Exactly the same connection object accepted by Logicform.execute.connections. */
+    readonly connection: DatabaseConnection;
+    readonly providerRegistry?: ProviderRegistry;
+    readonly signal?: AbortSignal;
+}
+export interface RunSQLOptions extends DBConnectorOptions {
+    readonly sql: string;
+    readonly parameters?: SqlParameters;
+}
+export interface GetTableListOptions extends DBConnectorOptions, TableListRequest {
+}
+export interface DescribeTableOptions extends DBConnectorOptions, DescribeTableRequest {
+}
+/** Trusted physical operations; no LogicForm permissions, rewriting, or caching. */
+export declare const DBConnector: Readonly<{
+    runSQL: (options: RunSQLOptions) => Promise<SQLResult>;
+    getTableList: (options: GetTableListOptions) => Promise<DatabaseTable[]>;
+    describeTable: (options: DescribeTableOptions) => Promise<TableDescription>;
+    close: () => Promise<void>;
+}>;

package/dist/physical/index.d.ts

@@ -1,5 +1,8 @@
 /** Internal physical adapters selected from the public database connection configuration. */
-export type { CoreComputeProvider, DatePart, DataRow, ProviderExecutionRequest, ProviderKind, ProviderKindExtensions, SqlRenderCapabilities, SqlParameters, } from './provider';
+export type { CoreComputeProvider, DatePart, DataRow, DatabaseTable, SQLResult, TableListRequest, DescribeTableRequest, DatabaseColumn, TableDescription, ProviderExecutionRequest, ProviderKind, ProviderKindExtensions, SqlRenderCapabilities, SqlParameters, } from './provider';
+export { ConnectionRegistry, getConnectionProvider, closeConnections } from './connection-registry';
+export { DBConnector } from './db-connector';
+export type { DBConnectorOptions, RunSQLOptions, GetTableListOptions, DescribeTableOptions } from './db-connector';
 export { builtinProviderDefinitions, createProvider, defaultProviderRegistry, ProviderRegistry, } from './connection';
 export type { BuiltinDatabaseConnection, DatabaseConnection, DatabaseConnectionBase, DatabaseConnectionExtensions, ProviderDefinition, } from './connection';
 export { DuckDBCoordinatorProvider } from './duckdb-coordinator-provider';