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

package/dist/planner/types.d.ts

@@ -1,6 +1,8 @@
 import type { CoreComputeProvider } from '../physical/index';
+import type { LogicformType } from '../logicform-types';
 import type { ResultProperty } from '../operators/index';
 import type { ComparableCategoryDefinition, TimeGranularity } from '../semantic-types/index';
+import type { QueryOperatorDefinition } from '../plugins/index';
 export interface FieldReferencePlan {
     readonly schemaId: string;
     readonly property: string;
@@ -10,31 +12,44 @@ export interface FieldReferencePlan {
     readonly qualifier: string;
     readonly sql?: string;
     readonly timestampColumn?: string;
+    /** Source alias that supplies $TS when it differs from the Property's Schema. */
+    readonly timestampQualifier?: string;
     readonly isArray?: boolean;
+    /** Accept native text arrays and JSON/scalar representations of string arrays. */
+    readonly normalizeStringArray?: boolean;
     readonly comparable?: ComparableCategoryDefinition;
 }
 export interface LogicalQuerySubquery {
     readonly kind: 'logicform-subquery';
     readonly plan: LogicalPlan;
 }
-export interface LogicalRecursiveQuery {
-    readonly kind: 'recursive-query';
-    readonly schemaId: string;
-    readonly source: string;
-    readonly sourceSql?: string;
-    readonly idColumn: string;
-    readonly parentColumn: string;
-    readonly roots: readonly unknown[];
-    readonly includeSelf: boolean;
+export interface LogicalQueryOperator {
+    readonly kind: 'query-operator';
+    readonly operator: string;
+    readonly value: unknown;
+    readonly sources?: readonly {
+        readonly schemaId: string;
+        readonly source: string;
+        readonly connectionId?: string;
+    }[];
+    /** Capability selected during planning; omitted only by manually constructed plans. */
+    readonly definition?: QueryOperatorDefinition;
 }
 export interface LogicalOrdinalQuery {
     readonly kind: 'ordinal-query';
     readonly comparable: ComparableCategoryDefinition;
     readonly condition: unknown;
 }
+export interface LogicalExpressionQuery {
+    readonly kind: 'expression-query';
+    readonly expression: Expression;
+    readonly condition: unknown;
+    readonly properties: readonly string[];
+}
 export declare const isLogicalQuerySubquery: (value: unknown) => value is LogicalQuerySubquery;
-export declare const isLogicalRecursiveQuery: (value: unknown) => value is LogicalRecursiveQuery;
+export declare const isLogicalQueryOperator: (value: unknown) => value is LogicalQueryOperator;
 export declare const isLogicalOrdinalQuery: (value: unknown) => value is LogicalOrdinalQuery;
+export declare const isLogicalExpressionQuery: (value: unknown) => value is LogicalExpressionQuery;
 export type Expression = {
     readonly kind: 'array-element';
     readonly schemaId: string;
@@ -55,6 +70,7 @@ export type Expression = {
     readonly sql: string;
     readonly qualifier?: string;
     readonly timestampColumn?: string;
+    readonly timestampQualifier?: string;
 } | {
     readonly kind: 'operator';
     readonly operator: string;
@@ -63,7 +79,7 @@ export type Expression = {
     readonly qualifier?: string;
     readonly schemaId?: string;
     readonly input?: Expression;
-    readonly components?: readonly Expression[];
+    readonly inputs?: readonly Expression[];
     readonly args: Readonly<Record<string, unknown>>;
     readonly query?: Readonly<Record<string, unknown>>;
 } | {
@@ -107,17 +123,47 @@ export interface JoinPlan {
     readonly sourceColumn: string;
     readonly sourceSql?: string;
     readonly sourceTimestampColumn?: string;
-    readonly sourceTimestampGranularity?: TimeGranularity;
     readonly targetSchemaId: string;
+    /** Physical connection selected for the target Schema mapping. */
+    readonly targetConnectionId?: string;
     readonly targetSource: string;
     readonly targetSourceSql?: string;
+    /** Two projection layers for the target Schema Mapping and its UDFs. */
+    readonly targetMappingSourcePlan?: LogicalPlan;
     readonly targetAlias: string;
     readonly targetColumn: string;
     readonly targetSql?: string;
     readonly targetTimestampColumn?: string;
-    readonly targetTimestampGranularity?: TimeGranularity;
+    readonly temporalCondition?: TemporalJoinConditionPlan;
     readonly sourceArrayExpansionPath?: string;
 }
+export type TemporalJoinConditionPlan = {
+    readonly kind: 'date-bucket-equal';
+    readonly sourceColumn: string;
+    readonly targetColumn: string;
+    readonly sourceGranularity: TimeGranularity;
+    readonly targetGranularity: TimeGranularity;
+} | {
+    readonly kind: 'point-in-interval';
+    readonly pointSide: 'source' | 'target';
+    readonly pointColumn: string;
+    readonly intervalSide: 'source' | 'target';
+    readonly startColumn: string;
+    readonly endColumn: string;
+};
+export interface EnrichmentJoinPlan {
+    readonly kind: 'enrichment-left';
+    readonly id: string;
+    readonly source: string;
+    readonly sourceSql?: string;
+    readonly alias: string;
+    readonly baseAlias: string;
+    readonly keys: readonly {
+        readonly baseColumn: string;
+        readonly targetColumn: string;
+    }[];
+    readonly temporalCondition?: TemporalJoinConditionPlan;
+}
 export interface ArrayExpansionPlan {
     readonly path: string;
     readonly sourceAlias: string;
@@ -125,6 +171,8 @@ export interface ArrayExpansionPlan {
     readonly sourceSql?: string;
     readonly sourceTimestampColumn?: string;
     readonly alias: string;
+    readonly normalizeStringArray?: boolean;
+    readonly elementType?: 'string';
 }
 export type PaginationPlan = {
     readonly kind: 'rows';
@@ -140,9 +188,30 @@ export interface GroupLimitPlan {
     readonly partitionBy: readonly string[];
     readonly orderBy: readonly OrderPlan[];
 }
+export interface PeriodSourcePlan {
+    readonly alias: string;
+    readonly labelColumn: string;
+    readonly asOfColumn: string;
+    readonly sourceAlias: string;
+    readonly periods: readonly {
+        readonly label: string;
+        readonly asOf: string;
+    }[];
+    readonly match: {
+        readonly kind: 'interval';
+        readonly startColumn: string;
+        readonly endColumn: string;
+    } | {
+        readonly kind: 'latest';
+        readonly lookupAlias: string;
+        readonly timestampColumn: string;
+    };
+}
 export type RowIdentityPlan = {
     readonly kind: 'group';
     readonly names: readonly string[];
+    readonly separator: string;
+    readonly nullLabel: string;
 } | {
     readonly kind: 'property';
     readonly column: string;
@@ -155,19 +224,37 @@ export type RowIdentityPlan = {
 export interface LogicalPlan {
     readonly schemaId: string;
     readonly source: string;
+    /** Physical connection selected for this plan's source mapping. */
+    readonly connectionId?: string;
     /** Trusted derived-table SQL supplied by the selected physical mapping. */
     readonly sourceSql?: string;
+    /** Two projection layers for the physical Mapping and Schema UDFs. */
+    readonly mappingSourcePlan?: LogicalPlan;
     /** Physical mapping selected by the Planner for this logical Schema. */
     readonly mappingId?: string;
     /** Child relations combined by their compatible group identity. */
-    readonly composition?: readonly LogicalPlan[];
+    readonly subplans?: readonly LogicalPlan[];
+    /** Vertically combine disjoint aggregate shards by summing matching output groups. */
+    readonly sumPartition?: true;
+    /** Enumerated group values corresponding to subplans, combined vertically. */
+    readonly splitGroup?: {
+        readonly name: string;
+        readonly values: readonly string[];
+        readonly groupNames: readonly string[];
+    };
     /** Optional query plan compiled as the derived-table source of this plan. */
     readonly sourcePlan?: LogicalPlan;
+    /** Normalized LogicForm corresponding to sourcePlan when generated rewrites need execution. */
+    readonly sourceLogicform?: LogicformType;
     readonly sourceAlias?: string;
     readonly fields: Readonly<Record<string, string>>;
     readonly fieldReferences?: Readonly<Record<string, FieldReferencePlan>>;
     readonly joins?: readonly JoinPlan[];
+    /** Physical extensions of this mapping, added only when a mapped property uses them. */
+    readonly enrichmentJoins?: readonly EnrichmentJoinPlan[];
     readonly arrayExpansions?: readonly ArrayExpansionPlan[];
+    /** Generated period rows matched to a source by a plugin-selected generic strategy. */
+    readonly periodSource?: PeriodSourcePlan;
     readonly projections: readonly ProjectionPlan[];
     readonly columnProperties?: readonly ResultProperty[];
     readonly groupBy: readonly ProjectionPlan[];
@@ -196,6 +283,11 @@ export interface QueryLineage {
         readonly schemaName: string;
         readonly physicalTable: string;
         readonly provider: CoreComputeProvider['kind'];
+        readonly connectionId?: string;
+        readonly connections?: readonly {
+            readonly connectionId: string;
+            readonly provider: CoreComputeProvider['kind'];
+        }[];
     };
     readonly outputs: readonly LineageOutput[];
     readonly filters: readonly LineageColumnSource[];

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

@@ -1,3 +1,3 @@
 import type { SemanticDBPlugin } from '../types';
-export type { HierarchyDefinition, HierarchyLevelDefinition, ResolvedHierarchyDefinition, } from './types';
+export type { HierarchyDefinition, HierarchyLevelDefinition, ResolvedHierarchyDefinition, SchemaMappingHierarchyGranularity, } from './types';
 export declare const hierarchyPlugin: SemanticDBPlugin;

package/dist/plugins/hierarchy/mapping-granularity.d.ts

@@ -0,0 +1,4 @@
+import type { MappingGranularityPlugin } from '../types';
+import type { SchemaMappingHierarchyGranularity } from './types';
+export declare const isMappingHierarchyGranularity: (value: unknown) => value is SchemaMappingHierarchyGranularity;
+export declare const hierarchyMappingGranularity: MappingGranularityPlugin;

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

@@ -1,11 +1,22 @@
+export interface SchemaMappingHierarchyGranularity {
+    readonly kind: 'hierarchy';
+    /** Physical level name or synonym declared by the referenced hierarchy Schema. */
+    readonly level: string;
+}
+declare module '../../schema-mappings/types' {
+    interface SchemaMappingGranularityExtensions {
+        readonly hierarchy: SchemaMappingHierarchyGranularity;
+    }
+}
 export interface HierarchyLevelDefinition {
     readonly name: string;
-    readonly synonyms?: readonly string[];
+    readonly syno?: readonly string[];
     readonly codeLength: number;
 }
 export interface HierarchyDefinition {
     /** Property that physically stores the complete hierarchy code. */
-    readonly property: string;
+    /** Property storing the complete hierarchy code. Defaults to the Schema's only ID Property. */
+    readonly property?: string;
     /** Compact codes stop at their level; zero-padded codes fill remaining segments with zeroes. */
     readonly storage?: 'compact' | 'zero-padded';
     readonly levels: readonly HierarchyLevelDefinition[];
@@ -16,6 +27,13 @@ export interface ResolvedHierarchyDefinition extends Omit<HierarchyDefinition, '
     readonly storage: 'compact' | 'zero-padded';
 }
 declare module '../../semantic-types/types' {
+    interface SemanticPropertyDraft {
+        /** Default hierarchy level for an Entity relation. */
+        readonly level?: string;
+    }
+    interface ResolvedSemanticProperty {
+        readonly level?: string;
+    }
     interface SemanticSchemaMetadata {
         readonly hierarchy?: HierarchyDefinition;
     }

package/dist/plugins/index.d.ts

@@ -1,5 +1,14 @@
 import type { SemanticDBPlugin } from './types';
-export type { LegacySchemaPluginContext, SchemaMetadataPlugin, SemanticDBPlugin } from './types';
+import type { LogicformType } from '../logicform-types';
+import type { ResolvedSemanticSchema } from '../semantic-types/index';
+export type { LegacySchemaPluginContext, MappingGranularityContext, MappingGranularityPlugin, QueryOperatorAuthorizeContext, QueryOperatorCompileContext, QueryOperatorDefinition, QueryOperatorNormalizeContext, QueryOperatorPhysicalSource, QueryOperatorPlanContext, QueryOperatorPlanResult, PropertyMetadataPlugin, SchemaMetadataPlugin, SemanticDBPlugin, OutputHandlerContext, OutputHandlerDefinition, IntervalSemanticProperties, IntervalSemanticsDefinition, PlannerPeriodDefinition, PlannerPeriodEvaluation, RelationSemanticsDefinition, RelationTemporalPlan, TimeWatermarkLogicformContext, SchemaMappingPlugin, } from './types';
+export type { SchemaMappingHierarchyGranularity } from './hierarchy/index';
+export type { RecursiveQueryType } from './recursive/index';
 /** Built-in capabilities are composed here; feature implementations live in their own folders. */
 export declare const builtinPlugins: readonly SemanticDBPlugin[];
 export declare const resolvePlugins: (plugins?: readonly SemanticDBPlugin[]) => readonly SemanticDBPlugin[];
+export declare const findQueryOperator: (name: string, plugins?: readonly SemanticDBPlugin[]) => import("./types").QueryOperatorDefinition | undefined;
+export declare const findOutputHandler: (type: string, plugins?: readonly SemanticDBPlugin[]) => import("./types").OutputHandlerDefinition | undefined;
+export declare const resolveIntervalSemanticProperties: (schema: ResolvedSemanticSchema, plugins?: readonly SemanticDBPlugin[]) => import("./types").IntervalSemanticProperties | undefined;
+export declare const resolveRelationTemporalPlan: (sourceSchema: ResolvedSemanticSchema, targetSchema: ResolvedSemanticSchema, plugins?: readonly SemanticDBPlugin[]) => import("./types").RelationTemporalPlan | undefined;
+export declare const resolvePlannerPeriodEvaluation: (logicform: LogicformType, schema: ResolvedSemanticSchema, plugins?: readonly SemanticDBPlugin[]) => import("./types").PlannerPeriodEvaluation | undefined;

package/dist/{planner/semantics → plugins}/observation/classification.d.ts

@@ -1,3 +1,3 @@
-import type { ResolvedSemanticProperty, ResolvedSemanticSchema } from '../../../semantic-types/index';
+import type { ResolvedSemanticProperty, ResolvedSemanticSchema } from '../../semantic-types/index';
 export declare const isObservationProperty: (property: ResolvedSemanticProperty | undefined, schema?: Pick<ResolvedSemanticSchema, "temporalSemantics">) => boolean;
 export declare const observationProperties: (schema: Pick<ResolvedSemanticSchema, "properties" | "temporalSemantics">) => readonly ResolvedSemanticProperty[];

package/dist/plugins/observation/index.d.ts

@@ -0,0 +1,17 @@
+import type { SemanticDBPlugin } from '../types';
+type SchemaTemporalSemantics = 'normal' | 'snapshot';
+export { isObservationProperty, observationProperties } from './classification';
+export { resolveObservationOperatorPolicy, type ObservationOperatorPolicy, } from './operator-policy';
+export { removeObservationTimeCondition, resolveObservationPeriodSpec, } from './periods';
+export type { ObservationPeriodMetric, ObservationPeriodSpec } from './periods';
+export { observationSemanticRule } from './rule';
+export type { ObservationOperator, ObservationTemporalMetadata } from './types';
+declare module '../../semantic-types/types' {
+    interface SemanticSchemaMetadata {
+        readonly temporalSemantics?: SchemaTemporalSemantics;
+    }
+    interface ResolvedSemanticSchemaMetadata {
+        readonly temporalSemantics?: SchemaTemporalSemantics;
+    }
+}
+export declare const observationPlugin: SemanticDBPlugin;

package/dist/{planner/semantics → plugins}/observation/operator-policy.d.ts

@@ -1,11 +1,10 @@
-import type { PredItemType } from '../../../logicform-types';
-import type { OperatorDefinition } from '../../../operators/index';
-declare const periodBoundaryOperator = "$periodBoundary";
+import type { PredItemType } from '../../logicform-types';
+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;
 }
-/** Resolves the point-selection policy without changing the caller LogicForm. */
-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/plugins/observation/periods.d.ts

@@ -0,0 +1,18 @@
+import type { LogicformType, PredItemType, QueryType } from '../../logicform-types';
+import type { ResolvedSemanticProperty, ResolvedSemanticSchema } from '../../semantic-types/index';
+export interface ObservationPeriodMetric {
+    readonly pred: PredItemType;
+    readonly effectivePred: PredItemType;
+}
+export interface ObservationPeriodSpec {
+    readonly group: PredItemType;
+    readonly timestamp: ResolvedSemanticProperty;
+    readonly boundary: 'start' | 'end';
+    readonly metrics: readonly ObservationPeriodMetric[];
+    readonly periods: readonly {
+        readonly label: string;
+        readonly asOf: string;
+    }[];
+}
+export declare const removeObservationTimeCondition: (query: QueryType | undefined, timestamp: ResolvedSemanticProperty) => QueryType | undefined;
+export declare const resolveObservationPeriodSpec: (logicform: LogicformType, schema: ResolvedSemanticSchema) => ObservationPeriodSpec | undefined;

package/dist/{planner/semantics → plugins}/observation/rule.d.ts

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

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

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

package/dist/plugins/property-hierarchy/index.d.ts

@@ -0,0 +1,11 @@
+import type { PropertyHierarchyDefinition } from '../../semantic-types/index';
+import type { SemanticDBPlugin } from '../types';
+type PropertyHierarchyMetadata = PropertyHierarchyDefinition;
+declare module '../../semantic-types/types' {
+    interface SemanticPropertyDraft {
+        /** Same-Schema drill relationship. `up` identifies the single-valued parent Property. */
+        readonly hierarchy?: PropertyHierarchyMetadata;
+    }
+}
+export declare const propertyHierarchyPlugin: SemanticDBPlugin;
+export {};

package/dist/plugins/recursive/index.d.ts

@@ -0,0 +1,26 @@
+import type { SemanticDBPlugin } from '../types';
+import type { QueryValueType } from '../../logicform-types';
+export interface RecursiveQueryType {
+    readonly schema?: string;
+    readonly root?: QueryValueType;
+    readonly roots?: QueryValueType[];
+    readonly includeSelf?: boolean;
+    readonly idProperty?: string;
+    readonly parentProperty?: string;
+}
+declare module '../../logicform-types' {
+    interface QueryOperatorExtensions {
+        readonly $recursive?: QueryValueType | RecursiveQueryType;
+    }
+}
+declare module '../../semantic-types/types' {
+    interface SemanticSchemaMetadata {
+        /** Property that stores a tree node's parent id. */
+        readonly parentProperty?: string;
+    }
+    interface ResolvedSemanticSchemaMetadata {
+        /** Canonical logical name of the Property that stores a tree node's parent id. */
+        readonly parentProperty?: string;
+    }
+}
+export declare const recursivePlugin: SemanticDBPlugin;

package/dist/plugins/temporal/index.d.ts

@@ -0,0 +1,13 @@
+import type { SemanticDBPlugin } from '../types';
+declare module '../../semantic-types/types' {
+    interface SemanticPropertyDraft {
+        readonly timeWatermark?: TimeWatermarkPolicy;
+    }
+    interface SemanticSchemaMetadata {
+        readonly timeWatermark?: TimeWatermarkPolicy;
+    }
+    interface ResolvedSemanticSchemaMetadata {
+        readonly timeWatermark?: TimeWatermarkPolicy;
+    }
+}
+export declare const temporalPlugin: SemanticDBPlugin;

package/dist/plugins/types.d.ts

@@ -1,20 +1,184 @@
 import type { OperatorDefinition } from '../operators/types';
-import type { ResolvedSemanticProperty, ResolvedSemanticSchema, SemanticSchemaDraft } from '../semantic-types/types';
+import type { LocaleDefinition } from '../i18n/types';
+import type { PlannerSemanticRule } from '../planner/semantics/registry';
+import type { CoreComputeProvider, DataRow } from '../physical/provider';
+import type { LogicformType, PredItemType, QueryType } from '../logicform-types';
+import type { SchemaMappingDefinition, SchemaMappingItem } from '../schema-mappings/types';
+import type { ResolvedSemanticProperty, ResolvedSemanticSchema, SemanticSchemaDraft, SemanticTypeDefinition, TimeWatermarkPolicy } from '../semantic-types/types';
 export interface SchemaMetadataPlugin {
     readonly keys: readonly string[];
     readonly resolve: (schema: SemanticSchemaDraft, properties: readonly ResolvedSemanticProperty[]) => Readonly<Record<string, unknown>>;
 }
+export interface PropertyMetadataPlugin {
+    readonly keys: readonly string[];
+    readonly resolve: (property: SemanticSchemaDraft['properties'][number], resolved: ResolvedSemanticProperty, schema: SemanticSchemaDraft) => Readonly<Record<string, unknown>>;
+    readonly resolveAll?: (properties: readonly ResolvedSemanticProperty[], drafts: readonly SemanticSchemaDraft['properties'][number][], schema: SemanticSchemaDraft) => readonly ResolvedSemanticProperty[];
+}
 export interface LegacySchemaPluginContext {
     readonly source: Readonly<Record<string, unknown>>;
     readonly properties: readonly SemanticSchemaDraft['properties'][number][];
 }
+export interface MappingGranularityContext {
+    readonly schema: ResolvedSemanticSchema;
+    readonly mapping: SchemaMappingDefinition;
+    readonly resolveSchema?: (schemaId: string) => ResolvedSemanticSchema;
+}
+export interface MappingGranularityPlugin {
+    /** Object-grain discriminator; one plugin owns each kind. */
+    readonly kind: string;
+    readonly isGranularity: (value: unknown) => boolean;
+    readonly validateItem?: (item: SchemaMappingItem, context: MappingGranularityContext) => string | undefined;
+    /** Reject a grouped source when it cannot preserve a requested dimension or filter. */
+    readonly candidateReason?: (logicform: LogicformType, context: MappingGranularityContext) => string | undefined;
+    /** True only for a computed grouping this plugin can verify in candidateReason. */
+    readonly supportsGroupby?: (group: PredItemType) => boolean;
+}
+export interface SchemaMappingPlugin {
+    readonly validate?: (mapping: SchemaMappingDefinition) => string | undefined;
+    readonly candidateReason?: (logicform: LogicformType, context: MappingGranularityContext) => string | undefined;
+}
+export interface QueryOperatorNormalizeContext {
+    readonly schema: ResolvedSemanticSchema;
+    readonly property: ResolvedSemanticProperty;
+    readonly resolveSchema?: (schemaId: string) => ResolvedSemanticSchema;
+    readonly normalizeValue: (value: unknown, schema: ResolvedSemanticSchema, property: ResolvedSemanticProperty) => Promise<unknown>;
+}
+export interface QueryOperatorPlanContext {
+    readonly schema: ResolvedSemanticSchema;
+    readonly property: ResolvedSemanticProperty;
+    readonly connectionId: string;
+    readonly resolveSchema?: (schemaId: string) => ResolvedSemanticSchema;
+    readonly resolveMapping: (schemaId: string, preferredConnectionId?: string) => SchemaMappingDefinition;
+}
+export interface QueryOperatorCompileContext {
+    readonly field: string;
+    readonly provider: CoreComputeProvider;
+    readonly bind: (value: unknown) => string;
+    readonly renderSource: (source: string, sourceSql?: string) => string;
+}
+export interface QueryOperatorAuthorizeContext {
+    readonly schema: ResolvedSemanticSchema;
+    readonly property: ResolvedSemanticProperty;
+    readonly resolveSchema: (schemaId: string) => ResolvedSemanticSchema;
+    readonly assertSchemaAllowed: (schemaId: string) => void;
+    readonly assertPropertyAllowed: (schema: ResolvedSemanticSchema, property: ResolvedSemanticProperty) => void;
+    readonly hasRowPermissions: (schemaId: string) => boolean;
+}
+export interface QueryOperatorPhysicalSource {
+    readonly schemaId: string;
+    readonly source: string;
+    readonly connectionId?: string;
+}
+export interface QueryOperatorPlanResult {
+    readonly value: unknown;
+    readonly sources?: readonly QueryOperatorPhysicalSource[];
+}
+export interface OutputHandlerContext {
+    readonly rows: readonly DataRow[];
+    readonly logicform: LogicformType;
+    readonly schema: ResolvedSemanticSchema;
+}
+export interface OutputHandlerDefinition {
+    readonly type: string;
+    readonly handle: (context: OutputHandlerContext) => unknown;
+}
+export interface TimeWatermarkLogicformContext {
+    readonly logicform: LogicformType;
+    readonly rootSchema: ResolvedSemanticSchema;
+    readonly rootProperty: ResolvedSemanticProperty;
+    readonly requestedUpperBound: Date;
+    readonly now: Date;
+    readonly defaultPolicy?: TimeWatermarkPolicy;
+    readonly resolveSchema: (schemaId: string) => ResolvedSemanticSchema;
+    readonly inferPropertyPath: (sourceSchema: ResolvedSemanticSchema, sourceProperty: string, targetSchema: ResolvedSemanticSchema) => string | undefined;
+}
+/** Stable interval roles used by generic point-in-interval planning. */
+export interface IntervalSemanticProperties {
+    readonly id: ResolvedSemanticProperty;
+    readonly timestamp: ResolvedSemanticProperty;
+    readonly start: ResolvedSemanticProperty;
+    readonly end: ResolvedSemanticProperty;
+}
+export interface IntervalSemanticsDefinition {
+    readonly resolve: (schema: ResolvedSemanticSchema) => IntervalSemanticProperties | undefined;
+}
+export type RelationTemporalPlan = {
+    readonly kind: 'date-bucket-equal';
+    readonly sourceTimestamp: ResolvedSemanticProperty;
+    readonly targetTimestamp: ResolvedSemanticProperty;
+} | {
+    readonly kind: 'point-in-interval';
+    readonly point: ResolvedSemanticProperty;
+    readonly start: ResolvedSemanticProperty;
+    readonly end: ResolvedSemanticProperty;
+};
+export interface RelationSemanticsDefinition {
+    readonly plan: (context: {
+        readonly sourceSchema: ResolvedSemanticSchema;
+        readonly targetSchema: ResolvedSemanticSchema;
+    }) => RelationTemporalPlan | undefined;
+}
+export interface PlannerPeriodEvaluation {
+    readonly group: PredItemType;
+    readonly property: ResolvedSemanticProperty;
+    readonly periods: readonly {
+        readonly label: string;
+        readonly asOf: string;
+    }[];
+    readonly source: {
+        readonly kind: 'interval';
+        readonly start: ResolvedSemanticProperty;
+        readonly end: ResolvedSemanticProperty;
+    } | {
+        readonly kind: 'latest';
+        readonly timestamp: ResolvedSemanticProperty;
+    };
+    readonly rewriteQuery?: (query: QueryType | undefined) => QueryType | undefined;
+    readonly rewritePred?: (pred: PredItemType) => PredItemType;
+}
+export interface PlannerPeriodDefinition {
+    readonly resolve: (logicform: LogicformType, schema: ResolvedSemanticSchema) => PlannerPeriodEvaluation | undefined;
+}
+/** A field-level query Operator spanning normalization, planning, and SQL compilation. */
+export interface QueryOperatorDefinition {
+    readonly name: string;
+    /** Validate the full field condition before this exclusive Operator is normalized. */
+    readonly validateCondition?: (condition: Readonly<Record<string, unknown>>) => void;
+    readonly normalize: (value: unknown, context: QueryOperatorNormalizeContext) => unknown;
+    readonly authorize?: (value: unknown, context: QueryOperatorAuthorizeContext) => void;
+    readonly plan: (value: unknown, context: QueryOperatorPlanContext) => QueryOperatorPlanResult;
+    readonly compile: (value: unknown, context: QueryOperatorCompileContext) => string;
+}
 export interface SemanticDBPlugin {
     /** Stable name used for diagnostics and duplicate detection. */
     readonly name: string;
     readonly schemaMetadata?: SchemaMetadataPlugin;
+    readonly propertyMetadata?: PropertyMetadataPlugin;
+    /** Prepare canonical v2 Schema metadata before Properties are resolved. */
+    readonly prepareSchema?: (schema: SemanticSchemaDraft) => SemanticSchemaDraft;
+    /** Validate invariants that require the complete resolved Schema. */
+    readonly validateResolvedSchema?: (schema: ResolvedSemanticSchema) => void;
     /** Legacy-only Schema fields removed after normalizeLegacySchema runs. */
     readonly legacySchemaKeys?: readonly string[];
     readonly normalizeLegacySchema?: (context: LegacySchemaPluginContext) => Readonly<Record<string, unknown>>;
     readonly resolveEntityFilterProperty?: (schema: ResolvedSemanticSchema) => ResolvedSemanticProperty | undefined;
     readonly operators?: readonly OperatorDefinition[];
+    readonly semanticTypes?: readonly SemanticTypeDefinition[];
+    /** Planner-level semantic rewrites contributed by this capability. */
+    readonly plannerSemantics?: readonly PlannerSemanticRule[];
+    readonly queryOperators?: readonly QueryOperatorDefinition[];
+    /** Translations owned by this capability. Explicit execution locales override these. */
+    readonly locales?: readonly LocaleDefinition[];
+    readonly outputHandlers?: readonly OutputHandlerDefinition[];
+    /** Build the internal query used to resolve a shared temporal data watermark. */
+    readonly createTimeWatermarkLogicform?: (context: TimeWatermarkLogicformContext) => LogicformType;
+    readonly mappingGranularity?: MappingGranularityPlugin;
+    /** Extend physical mapping validation and candidate selection beyond granularity. */
+    readonly schemaMapping?: SchemaMappingPlugin;
+    /** Recognize a Schema whose rows own half-open validity intervals. */
+    readonly intervalSemantics?: IntervalSemanticsDefinition;
+    /** Add temporal conditions to a logical relation without coupling the core to a model. */
+    readonly relationSemantics?: RelationSemanticsDefinition;
+    /** Turn a bounded time group into a generic generated-period source. */
+    readonly plannerPeriod?: PlannerPeriodDefinition;
 }

package/dist/plugins/validity/classification.d.ts

@@ -0,0 +1,5 @@
+import type { ResolvedSemanticSchema } from '../../semantic-types/index';
+import type { IntervalSemanticProperties } from '../types';
+export type ValidityProperties = IntervalSemanticProperties;
+/** Recognize a stable entity whose physical rows are valid over half-open intervals. */
+export declare const resolveValidityProperties: (schema: ResolvedSemanticSchema) => ValidityProperties | undefined;

package/dist/plugins/validity/index.d.ts

@@ -0,0 +1,15 @@
+import type { SemanticDBPlugin } from '../types';
+declare module '../../operators/types' {
+    interface ResultPropertyTemporalMetadataExtensions {
+        readonly validity: {
+            readonly kind: 'validity';
+        };
+    }
+}
+export { resolveValidityProperties } from './classification';
+export type { ValidityProperties } from './classification';
+export { applyValidityQuery } from './query-policy';
+export { hasValidityTimeGroup, removeValidityTimeCondition, resolveValidityPeriodSpec, } from './periods';
+export type { ValidityPeriod, ValidityPeriodSpec } from './periods';
+export { validitySemanticRule } from './rule';
+export declare const validityPlugin: SemanticDBPlugin;

package/dist/plugins/validity/periods.d.ts

@@ -0,0 +1,15 @@
+import type { LogicformType, PredItemType, QueryType } from '../../logicform-types';
+import type { TimeGranularity } from '../../semantic-types/index';
+import type { ValidityProperties } from './classification';
+export interface ValidityPeriod {
+    readonly label: string;
+    readonly asOf: string;
+}
+export interface ValidityPeriodSpec {
+    readonly group: PredItemType;
+    readonly granularity: TimeGranularity;
+    readonly periods: readonly ValidityPeriod[];
+}
+export declare const hasValidityTimeGroup: (logicform: LogicformType, properties: ValidityProperties) => boolean;
+export declare const removeValidityTimeCondition: (query: QueryType | undefined, properties: ValidityProperties) => QueryType | undefined;
+export declare const resolveValidityPeriodSpec: (logicform: LogicformType, properties: ValidityProperties) => ValidityPeriodSpec | undefined;

package/dist/plugins/validity/query-policy.d.ts

@@ -0,0 +1,3 @@
+import type { QueryType } from '../../logicform-types';
+import type { ValidityProperties } from './classification';
+export declare const applyValidityQuery: (query: QueryType | undefined, properties: ValidityProperties) => QueryType | undefined;

package/dist/plugins/validity/rule.d.ts

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