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

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;

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

@@ -0,0 +1,3 @@
+import type { SemanticTypeDefinition } from '../../semantic-types/index';
+export declare const startDateSemanticType: SemanticTypeDefinition;
+export declare const endDateSemanticType: SemanticTypeDefinition;

package/dist/schema/dependent-projection.d.ts

@@ -0,0 +1,8 @@
+import type { PredItemType } from '../logicform-types';
+import type { ResolvedSemanticSchema } from '../semantic-types/index';
+/**
+ * Returns true when a scalar projection is functionally dependent on one of
+ * the supplied group keys. Same-Schema hierarchy uses `up`; scalar object
+ * relations use the relation key itself.
+ */
+export declare const isDependentProjection: (pred: PredItemType, groupby: readonly PredItemType[], schema: ResolvedSemanticSchema, resolveSchema?: (schemaId: string) => ResolvedSemanticSchema) => boolean;

package/dist/schema/entity-identity.d.ts

@@ -1,5 +1,5 @@
 import type { SemanticDBPlugin } from '../plugins/index';
 import type { ResolvedSemanticProperty, ResolvedSemanticSchema } from '../semantic-types/index';
-export declare const isConcreteEntityId: (value: unknown) => value is string;
+export declare const isConcreteEntityId: (value: unknown) => value is string | number;
 export declare const resolveEntityIdProperty: (schema: ResolvedSemanticSchema) => ResolvedSemanticProperty;
 export declare const resolveEntityFilterProperty: (schema: ResolvedSemanticSchema, plugins?: readonly SemanticDBPlugin[]) => ResolvedSemanticProperty;

package/dist/schema/index.d.ts

@@ -1,4 +1,5 @@
 export { buildFieldMap, getProperty, getSchema, } from './schema-registry';
 export { resolvePropertyPath } from './resolve-property-path';
+export { isDependentProjection } from './dependent-projection';
 export { isConcreteEntityId, resolveEntityFilterProperty, resolveEntityIdProperty, } from './entity-identity';
 export type { ResolvedPropertyPath, ResolvedRelationSegment, ResolvedSchemaLookup, } from './resolve-property-path';

package/dist/schema-mappings/freshness.d.ts

@@ -4,4 +4,4 @@ export declare const parseDailyExpireAt: (value: string) => {
     readonly minute: number;
     readonly second: number;
 } | undefined;
-export declare const validateSourceFreshness: (definition: SchemaMappingDefinition) => void;
+export declare const validateSourceFreshness: (definition: Pick<SchemaMappingDefinition, "freshness">) => void;

package/dist/schema-mappings/granularity.d.ts

@@ -0,0 +1,5 @@
+import type { SemanticDBPlugin } from '../plugins/types';
+import type { TimeGranularity } from '../semantic-types/index';
+import type { SchemaMappingGranularity } from './types';
+export declare const isMappingTimeGranularity: (value: unknown) => value is TimeGranularity;
+export declare const isSchemaMappingGranularity: (value: unknown, plugins?: readonly SemanticDBPlugin[]) => value is SchemaMappingGranularity;

package/dist/schema-mappings/index.d.ts

@@ -1,4 +1,7 @@
 export { SchemaMappingRegistry } from './registry';
 export { parseDailyExpireAt } from './freshness';
-export type { SchemaMappingDefinition, SourceFreshnessPolicy } from './types';
+export { isMappingTimeGranularity, isSchemaMappingGranularity, } from './granularity';
+export type { SchemaMappingDefinition, SchemaMappingEnrichmentDefinition, SchemaMappingEnrichmentKey, SchemaMappingItem, SchemaMappingGranularity, SchemaMappingGranularityExtensions, SchemaMappingPointTemporalDefinition, SchemaMappingSelection, RejectedSchemaMapping, SourceFreshnessPolicy, } from './types';
 export type { SchemaMappingPredDefinition, SchemaMappingPredMatch, } from './types';
+export { fromYiAskSchemaMapping } from './yiask';
+export type { YiAskSchemaMappingItem, YiAskSchemaMappingRecord } from './yiask';

package/dist/schema-mappings/registry.d.ts

@@ -1,9 +1,12 @@
+import type { SemanticDBPlugin } from '../plugins/index';
 import type { SchemaMappingDefinition } from './types';
 export declare class SchemaMappingRegistry {
     #private;
-    constructor(definitions?: readonly SchemaMappingDefinition[]);
+    readonly plugins: readonly SemanticDBPlugin[];
+    constructor(definitions?: readonly SchemaMappingDefinition[], plugins?: readonly SemanticDBPlugin[]);
     register(definition: SchemaMappingDefinition): this;
-    get(schemaId: string): SchemaMappingDefinition;
+    get(schemaId: string, connectionId?: string): SchemaMappingDefinition;
     list(schemaId: string): readonly SchemaMappingDefinition[];
-    findSource(schemaId: string, source: string): SchemaMappingDefinition | undefined;
+    definitions(): readonly SchemaMappingDefinition[];
+    findSource(schemaId: string, source: string, connectionId?: string): SchemaMappingDefinition | undefined;
 }

package/dist/schema-mappings/types.d.ts

@@ -1,4 +1,10 @@
-import type { QueryType } from '../logicform-types';
+import type { PredItemType, QueryType } from '../logicform-types';
+import type { TimeGranularity } from '../semantic-types/index';
+/** Plugin-owned physical grains extend this interface through module augmentation. */
+export interface SchemaMappingGranularityExtensions {
+}
+/** Finest physical grain represented by one mapped Property column. */
+export type SchemaMappingGranularity = TimeGranularity | SchemaMappingGranularityExtensions[keyof SchemaMappingGranularityExtensions];
 export type SourceFreshnessPolicy = {
     readonly mode: 'ttl';
     readonly ttlSeconds: number;
@@ -22,6 +28,37 @@ export interface SchemaMappingPredDefinition {
     /** Physical column used as the matched PredItem's operator input. */
     readonly column: string;
 }
+export interface SchemaMappingItem {
+    readonly sourceColumn?: string;
+    /** Enrichment id that owns sourceColumn. Missing means the mapping's base source. */
+    readonly sourceRef?: string;
+    readonly mappingType?: 'property' | 'predItem' | 'ignored';
+    readonly propertyTarget?: readonly string[];
+    readonly predItem?: PredItemType;
+    /** Finest physical grain of a mapped Property. */
+    readonly granularity?: SchemaMappingGranularity;
+}
+export interface SchemaMappingEnrichmentKey {
+    /** Physical column on the mapping's base source. */
+    readonly baseColumn: string;
+    /** Physical entity-id column on the enrichment source. */
+    readonly targetColumn: string;
+}
+export interface SchemaMappingPointTemporalDefinition {
+    readonly kind: 'point';
+    /** Point whose containing base-source interval owns the feature row. */
+    readonly pointColumn: string;
+}
+/** A same-connection physical extension of one logical Schema. */
+export interface SchemaMappingEnrichmentDefinition {
+    readonly id: string;
+    readonly source: string;
+    readonly sourceSql?: string;
+    readonly on: readonly SchemaMappingEnrichmentKey[];
+    readonly temporal?: SchemaMappingPointTemporalDefinition;
+    /** Missing means queries depending on this enrichment are not cached. */
+    readonly freshness?: SourceFreshnessPolicy;
+}
 export interface SchemaMappingDefinition {
     /** Stable identity when a Schema has multiple physical mappings. */
     readonly id?: string;
@@ -32,15 +69,22 @@ export interface SchemaMappingDefinition {
     readonly source: string;
     /** Optional trusted query compiled as a derived-table source instead of reading source directly. */
     readonly sourceSql?: string;
-    /**
-     * Supported logical properties and their physical columns. Missing means all
-     * Schema properties keep their configured physical IDs.
-     */
-    readonly properties?: Readonly<Record<string, string>>;
-    /** PredItem patterns implemented by physical measure columns in this source. */
-    readonly predMappings?: readonly SchemaMappingPredDefinition[];
+    /** Optional physical tables that extend base rows without becoming logical Schema relations. */
+    readonly enrichments?: readonly SchemaMappingEnrichmentDefinition[];
+    /** Unified logical-to-physical mappings for properties and conditional PredItems. */
+    readonly mappings?: readonly SchemaMappingItem[];
     /** Higher values win when multiple candidates cover the same LogicForm. */
     readonly priority?: number;
     /** Missing means queries depending on this physical source are not cached. */
     readonly freshness?: SourceFreshnessPolicy;
 }
+export interface RejectedSchemaMapping {
+    readonly mappingId: string;
+    readonly reason: string;
+}
+/** Planner diagnostics for one physical Schema mapping decision. */
+export interface SchemaMappingSelection {
+    readonly schemaId: string;
+    readonly selectedMappingId: string;
+    readonly rejectedMappings: readonly RejectedSchemaMapping[];
+}

package/dist/schema-mappings/yiask.d.ts

@@ -0,0 +1,26 @@
+import type { SemanticDBPlugin } from '../plugins/index';
+import type { PredItemType } from '../logicform-types';
+import type { SchemaMappingDefinition, SchemaMappingEnrichmentDefinition, SchemaMappingGranularity } from './types';
+export interface YiAskSchemaMappingItem {
+    readonly sourceColumn?: string;
+    readonly sourceRef?: string;
+    readonly mappingType?: 'property' | 'predItem' | 'ignored';
+    readonly propertyTarget?: readonly string[];
+    readonly predItem?: PredItemType;
+    readonly granularity?: SchemaMappingGranularity;
+}
+export interface YiAskSchemaMappingRecord {
+    readonly id: string | number;
+    readonly schemaSid: string;
+    readonly datasourceSid: string;
+    readonly sourceMode?: 'table' | 'demo';
+    readonly tablePath?: string;
+    readonly sourceSql?: string;
+    readonly physicalDatabase?: string;
+    readonly physicalSchema?: string;
+    readonly physicalTable?: string;
+    readonly enrichments?: readonly SchemaMappingEnrichmentDefinition[];
+    readonly mappings: readonly YiAskSchemaMappingItem[];
+    readonly enabled?: boolean;
+}
+export declare const fromYiAskSchemaMapping: (record: YiAskSchemaMappingRecord, plugins?: readonly SemanticDBPlugin[]) => SchemaMappingDefinition;

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

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

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

@@ -1,9 +1,11 @@
+import type { SemanticDBPlugin } from '../plugins/index';
 import { SemanticTypeRegistry } from './registry';
 export { builtinSemanticTypes } from './builtins/index';
 export { SemanticTypeRegistry } from './registry';
 export { resolveSchema } from './resolve-schema';
 export { validateResolvedSchema } from './validate-resolved-schema';
 export { normalizePrimalQuery } from './primal-types/index';
-export type { ComparableCategoryDefinition, PropertySqlDefinition, PrimalType, ResolvedSemanticProperty, ResolvedSemanticSchema, LegacySemanticSchemaMetadata, ResolvedSemanticSchemaMetadata, SemanticSchemaMetadata, SemanticTypeNormalizeContext, SemanticPeriodEvaluationContext, SemanticTypeResultContext, SemanticTypeResultProperty, SemanticPropertyDraft, SemanticSchemaDraft, SemanticTypeDefinition, TimeGranularity, TemporalSemantics, } from './types';
-export type { HierarchyDefinition, HierarchyLevelDefinition, ResolvedHierarchyDefinition, } from '../plugins/hierarchy/index';
-export declare const createSemanticTypeRegistry: () => SemanticTypeRegistry;
+export type { ComparableCategoryDefinition, PropertyHierarchyDefinition, PropertySqlDefinition, PrimalType, ResolvedSemanticProperty, ResolvedSemanticSchema, LegacySemanticSchemaMetadata, ResolvedSemanticSchemaMetadata, SemanticSchemaMetadata, SemanticTypeNormalizeContext, SemanticPeriodEvaluationContext, SemanticTypeResultContext, SemanticTypeResultProperty, SemanticPropertyDraft, SemanticSchemaDraft, SemanticTypeDefinition, TimeGranularity, TimeWatermarkPolicy, } from './types';
+export declare const createSemanticTypeRegistry: (plugins?: readonly SemanticDBPlugin[]) => SemanticTypeRegistry;
+/** Copies a caller-owned Registry and appends plugin types without mutating the input. */
+export declare const addPluginSemanticTypes: (registry: SemanticTypeRegistry, plugins: readonly SemanticDBPlugin[]) => SemanticTypeRegistry;

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

@@ -5,6 +5,8 @@ export declare class SemanticTypeRegistry {
     constructor(definitions?: readonly SemanticTypeDefinition[]);
     register(definition: SemanticTypeDefinition): this;
     get(name: string): SemanticTypeDefinition;
+    has(name: string): boolean;
+    definitions(): readonly SemanticTypeDefinition[];
     requiresPerPeriodEvaluation(context: {
         readonly logicform: LogicformType;
         readonly pred: PredItemType;