semanticdb-v2 2.0.0-alpha.7 → 2.0.0-alpha.9

package/README.md

@@ -583,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
@@ -598,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/execute-query.d.ts

@@ -2,7 +2,8 @@ import type { CompiledQuery } from '../compiler/index';
 import type { DataRow } from '../physical/index';
 import type { LogicalPlan } from '../planner/index';
 import type { SchemaMappingDefinition, SchemaMappingRegistry } from '../schema-mappings/index';
-import type { InternalExecuteOptions } from './types';
+import type { InternalExecuteOptions, SqlExecutionSource } from './types';
+export type SqlExecutionSourceReporter = (source: SqlExecutionSource) => void;
 export interface PhysicalQuerySource {
     readonly schemaId: string;
     readonly source: string;
@@ -13,6 +14,6 @@ export interface PhysicalQuerySource {
 export declare const resolvePhysicalSourceMapping: (source: PhysicalQuerySource, mappings: SchemaMappingRegistry) => SchemaMappingDefinition | undefined;
 export declare const collectPlanSources: (plan: LogicalPlan) => readonly PhysicalQuerySource[];
 export declare const mergePhysicalSources: (groups: readonly (readonly PhysicalQuerySource[])[]) => readonly PhysicalQuerySource[];
-export declare const executeCompiledQuery: (compiled: CompiledQuery, sources: readonly PhysicalQuerySource[], options: Pick<InternalExecuteOptions, "cache" | "provider" | "schemaMappings" | "signal" | "connectionId">) => Promise<DataRow[]>;
+export declare const executeCompiledQuery: (compiled: CompiledQuery, sources: readonly PhysicalQuerySource[], options: Pick<InternalExecuteOptions, "cache" | "provider" | "schemaMappings" | "signal" | "connectionId">, reportExecutionSource?: SqlExecutionSourceReporter) => Promise<DataRow[]>;
 /** Apply final SQL shaping after all plans, views, and derived sources are compiled. */
 export declare const shortenCompiledQuery: (compiled: CompiledQuery) => CompiledQuery;

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

@@ -4,6 +4,7 @@ import type { OperatorRegistry } from '../operators/index';
 import type { CoreComputeProvider, DataRow } from '../physical/index';
 import type { LogicalPlan } from '../planner/index';
 import type { SchemaMappingRegistry } from '../schema-mappings/index';
+import type { SqlExecutionSourceReporter } from './execute-query';
 import type { InternalExecuteOptions } from './types';
 export declare const coordinatorConnectionId = "__semanticdb_coordinator__";
 export interface FederatedCompiledQuery {
@@ -21,7 +22,7 @@ interface FederatedExecutionOptions {
     readonly cache?: InternalExecuteOptions['cache'];
     readonly signal?: AbortSignal;
     readonly maxMaterializedRows: number;
-    readonly onCompiled: (query: FederatedCompiledQuery) => void;
+    readonly onCompiled: (query: FederatedCompiledQuery) => SqlExecutionSourceReporter;
 }
 export interface FederatedExecutionResult {
     readonly rows: DataRow[];

package/dist/executor/fetch-entities.d.ts

@@ -9,6 +9,7 @@ import type { Permissions } from '../permissions/index';
 import type { ResolvedSemanticSchema, SemanticTypeRegistry } from '../semantic-types/index';
 import type { EntityFetchRequest } from './result-hydrator/index';
 import type { SemanticDBPlugin } from '../plugins/index';
+import type { SqlExecutionSourceReporter } from './execute-query';
 import type { LocaleRegistry } from '../i18n/index';
 interface FetchEntityOptions {
     readonly version: string;
@@ -25,7 +26,7 @@ interface FetchEntityOptions {
     readonly preferredConnectionId?: string;
     readonly cache?: QueryCacheExecutionOptions;
     readonly signal?: AbortSignal;
-    readonly onCompiled?: (compiled: CompiledQuery, logicform: LogicformType, provider: CoreComputeProvider, connectionId?: string) => void;
+    readonly onCompiled?: (compiled: CompiledQuery, logicform: LogicformType, provider: CoreComputeProvider, connectionId?: string) => SqlExecutionSourceReporter | undefined;
 }
 export declare const fetchEntities: (request: EntityFetchRequest, options: FetchEntityOptions) => Promise<DataRow[]>;
 export {};

package/dist/executor/index.d.ts

@@ -1,3 +1,3 @@
 export { execute } from './execute';
 export { closeConnections } from './connection-registry';
-export type { ExecuteOptions, ExecuteFailureResult, ExecuteProgressEvent, ExecuteResult, ExecuteSuccessResult, ExecutedSql, ExecutedSqlType, PartialExecuteResult, ProgressCallback, } from './types';
+export type { ExecuteOptions, ExecuteFailureResult, ExecuteProgressEvent, ExecuteResult, ExecuteSuccessResult, ExecutedSql, ExecutedSqlType, SqlExecutionSource, PartialExecuteResult, ProgressCallback, } from './types';

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;
 }
@@ -136,6 +140,7 @@ export interface ExecuteFailureResult {
 }
 export type ExecuteResult = ExecuteSuccessResult | ExecuteFailureResult;
 export type ExecutedSqlType = 'computation' | 'semantic-resolution' | 'total';
+export type SqlExecutionSource = 'cache' | 'database';
 export interface ExecutedSql {
     /** Why this SQL participates in the LogicForm execution. */
     readonly type: ExecutedSqlType;
@@ -151,6 +156,8 @@ export interface ExecutedSql {
     readonly parameters: SqlParameters;
     /** Dialect-formatted diagnostic SQL. SemanticDB never executes this string. */
     readonly displaySql: string;
+    /** Actual row source. Absent only before execution, such as in the compiled progress event. */
+    readonly executionSource?: SqlExecutionSource;
 }
 export type PartialExecuteResult = Partial<ExecuteSuccessResult>;
 export {};

package/dist/index.d.ts

@@ -9,19 +9,17 @@ 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 { DBConnector, ProviderRegistry } from './physical/index';
 export type { DBConnectorOptions, RunSQLOptions, GetTableListOptions, DescribeTableOptions, DescribeTableRequest, DatabaseColumn, TableDescription, DatabaseTable, SQLResult, TableListRequest, } 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 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 type { ExecuteOptions, ExecuteFailureResult, ExecuteProgressEvent, ExecuteResult, ExecuteSuccessResult, ExecutedSql, ExecutedSqlType, PartialExecuteResult, ProgressCallback, } from './executor/index';
+export { QueryCacheManager } from './cache/index';
+export type { InvalidateQueryCacheSourceOptions, QueryCacheConfiguration, } from './cache/index';
+export type { ExecuteOptions, ExecuteFailureResult, ExecuteProgressEvent, ExecuteResult, ExecuteSuccessResult, ExecutedSql, ExecutedSqlType, SqlExecutionSource, PartialExecuteResult, ProgressCallback, } from './executor/index';
 export type { ColumnPermissions, Permissions, SchemaPermissions, } from './permissions/index';
 export type { CreateLogicalPlanOptions, LogicalPlan, QueryLineage, } from './planner/index';
 export { PlannerSemanticRegistry, createPlannerSemanticRegistry, } 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/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,32 +151,32 @@ 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 {
-    /** Fully normalized LogicForm containing this top-level operator projection. */
+export interface OperatorComponentContext extends OperatorHookContext {
+    /** Normalized input LogicForm; having, sort, limit, limitBy, and page stay on the merged result. */
     readonly logicform: LogicformType;
-    /** Caller-authored normalized LogicForm before executor row policies were added. */
+    /** Caller-authored normalized input before executor row policies, with result operations removed. */
     readonly sourceLogicform?: LogicformType;
     /** The operator projection for which the component is being built. */
     readonly pred: PredItemType;
@@ -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/planner/semantics/registry.d.ts

@@ -1,13 +1,14 @@
 import type { PredItemType } from '../../logicform-types';
 import type { LogicformType, QueryType } from '../../logicform-types';
 import type { ResolvedSemanticProperty, ResolvedSemanticSchema } from '../../semantic-types/index';
-import type { OperatorDefinition, ResultProperty } from '../../operators/index';
+import type { OperatorDefinition, OperatorExecutionContext, ResultProperty } from '../../operators/index';
 export interface PlannerSemanticRuleContext {
     readonly pred: PredItemType;
     readonly schema: ResolvedSemanticSchema;
     readonly sourceProperty?: ResolvedSemanticProperty;
     readonly outputProperty: ResultProperty;
     readonly operator?: OperatorDefinition;
+    readonly executionContext?: OperatorExecutionContext;
 }
 export interface PlannerSemanticQueryContext {
     readonly logicform: LogicformType;

package/dist/plugins/observation/operator-policy.d.ts

@@ -1,10 +1,10 @@
 import type { PredItemType } from '../../logicform-types';
-import type { OperatorDefinition } from '../../operators/index';
+import type { OperatorDefinition, OperatorExecutionContext } from '../../operators/index';
 declare const periodBoundaryOperator = "$periodValue";
 export interface ObservationOperatorPolicy {
     readonly operator: typeof periodBoundaryOperator;
     readonly boundary: 'start' | 'end';
     readonly implicit: boolean;
 }
-export declare const resolveObservationOperatorPolicy: (pred: Pick<PredItemType, "operator" | "args">, operator?: OperatorDefinition) => ObservationOperatorPolicy;
+export declare const resolveObservationOperatorPolicy: (pred: Pick<PredItemType, "operator" | "args">, operator?: OperatorDefinition, executionContext?: OperatorExecutionContext) => ObservationOperatorPolicy;
 export {};

package/dist/semantic-types/types.d.ts

@@ -50,11 +50,14 @@ export interface ResolvedSemanticProperty extends Omit<SemanticPropertyDraft, 'i
 export interface SemanticSchemaDraft extends Omit<SchemaTypeDraft, '_id' | 'id' | 'sid' | 'properties' | 'db' | 'from' | 'fromSQL' | 'projections' | keyof SemanticSchemaMetadata | keyof LegacySemanticSchemaMetadata>, SemanticSchemaMetadata {
     readonly [key: string]: unknown;
     readonly id: string;
+    /** Marks the single Schema whose complete rows are loaded as calendar execution context. */
+    readonly is_calendar?: boolean;
     readonly properties: readonly SemanticPropertyDraft[];
 }
 export interface ResolvedSemanticSchema extends Omit<SchemaTypeDraft, '_id' | 'id' | 'sid' | 'properties' | 'db' | 'from' | 'fromSQL' | 'projections' | keyof SemanticSchemaMetadata | keyof LegacySemanticSchemaMetadata>, ResolvedSemanticSchemaMetadata {
     readonly [key: string]: unknown;
     readonly id: string;
+    readonly is_calendar?: boolean;
     readonly properties: readonly ResolvedSemanticProperty[];
 }
 export interface SemanticTypeNormalizeContext {