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

package/dist/{planner/semantics → plugins}/validity/index.d.ts

@@ -1,6 +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/{planner/semantics → plugins}/validity/periods.d.ts

@@ -1,5 +1,5 @@
-import type { LogicformType, PredItemType, QueryType } from '../../../logicform-types';
-import type { TimeGranularity } from '../../../semantic-types/index';
+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;
@@ -12,5 +12,4 @@ export interface ValidityPeriodSpec {
 }
 export declare const hasValidityTimeGroup: (logicform: LogicformType, properties: ValidityProperties) => boolean;
 export declare const removeValidityTimeCondition: (query: QueryType | undefined, properties: ValidityProperties) => QueryType | undefined;
-/** Resolve a bounded virtual-time grouping into explicit period-end instants. */
 export declare const resolveValidityPeriodSpec: (logicform: LogicformType, properties: ValidityProperties) => ValidityPeriodSpec | undefined;

package/dist/{planner/semantics → plugins}/validity/query-policy.d.ts

@@ -1,4 +1,3 @@
-import type { QueryType } from '../../../logicform-types';
+import type { QueryType } from '../../logicform-types';
 import type { ValidityProperties } from './classification';
-/** Rewrite a public time-axis condition to the half-open validity interval [start, end). */
 export declare const applyValidityQuery: (query: QueryType | undefined, properties: ValidityProperties) => QueryType | undefined;

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

@@ -1,2 +1,2 @@
-import type { PlannerSemanticRule } from '../registry';
+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-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,6 +1,7 @@
 export { SchemaMappingRegistry } from './registry';
 export { parseDailyExpireAt } from './freshness';
-export type { SchemaMappingDefinition, SchemaMappingItem, 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,11 @@
+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;
+    findSource(schemaId: string, source: string, connectionId?: string): SchemaMappingDefinition | undefined;
 }

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

@@ -1,4 +1,10 @@
 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;
@@ -24,9 +30,34 @@ export interface SchemaMappingPredDefinition {
 }
 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. */
@@ -38,6 +69,8 @@ export interface SchemaMappingDefinition {
     readonly source: string;
     /** Optional trusted query compiled as a derived-table source instead of reading source directly. */
     readonly sourceSql?: string;
+    /** 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. */
@@ -45,3 +78,13 @@ export interface SchemaMappingDefinition {
     /** 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

@@ -1,10 +1,13 @@
+import type { SemanticDBPlugin } from '../plugins/index';
 import type { PredItemType } from '../logicform-types';
-import type { SchemaMappingDefinition } from './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;
@@ -16,7 +19,8 @@ export interface YiAskSchemaMappingRecord {
     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) => SchemaMappingDefinition;
+export declare const fromYiAskSchemaMapping: (record: YiAskSchemaMappingRecord, plugins?: readonly SemanticDBPlugin[]) => SchemaMappingDefinition;

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, PropertyHierarchyDefinition, PropertySqlDefinition, PrimalType, ResolvedSemanticProperty, ResolvedSemanticSchema, LegacySemanticSchemaMetadata, ResolvedSemanticSchemaMetadata, SemanticSchemaMetadata, SemanticTypeNormalizeContext, SemanticPeriodEvaluationContext, SemanticTypeResultContext, SemanticTypeResultProperty, SemanticPropertyDraft, SemanticSchemaDraft, SemanticTypeDefinition, TimeGranularity, TemporalSemantics, TimeWatermarkPolicy, } 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;

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

@@ -1,4 +1,4 @@
 import type { SemanticDBPlugin } from '../plugins/index';
 import type { SemanticTypeRegistry } from './registry';
 import type { ResolvedSemanticSchema, SemanticSchemaDraft } from './types';
-export declare const resolveSchema: (schema: SemanticSchemaDraft, registry: SemanticTypeRegistry, externalPlugins?: readonly SemanticDBPlugin[]) => ResolvedSemanticSchema;
+export declare const resolveSchema: (inputSchema: SemanticSchemaDraft, registry: SemanticTypeRegistry, externalPlugins?: readonly SemanticDBPlugin[]) => ResolvedSemanticSchema;

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

@@ -3,7 +3,6 @@ import type { LogicformType, PredItemType } from '../logicform-types';
 /** Canonical primitive types use `entity`; `object` remains a legacy input alias. */
 export type PrimalType = 'string' | 'number' | 'boolean' | 'date' | 'entity' | 'object';
 export type TimeGranularity = 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
-export type TemporalSemantics = 'normal' | 'snapshot';
 export type TimeWatermarkPolicy = {
     readonly type: 'database_latest';
 } | {
@@ -37,15 +36,10 @@ export interface SemanticPropertyDraft extends Omit<PropertyTypeDraft, '_id' | '
     readonly primal_type?: PrimalType;
     readonly isArray?: boolean;
     readonly granularity?: TimeGranularity;
-    /** Default hierarchy level when this Property references a hierarchy Entity. */
-    readonly level?: string;
     /** Derived during schema resolution from whether the property has udf.sql. */
     readonly is_dynamic?: boolean;
     readonly udf?: PropertySqlDefinition;
     readonly comparable?: ComparableCategoryDefinition;
-    readonly timeWatermark?: TimeWatermarkPolicy;
-    /** Same-Schema drill relationship. `up` identifies the single-valued parent Property. */
-    readonly hierarchy?: PropertyHierarchyDefinition;
 }
 export interface ResolvedSemanticProperty extends Omit<SemanticPropertyDraft, 'id' | 'primal_type' | 'isArray' | 'is_dynamic'> {
     readonly id: string;
@@ -57,19 +51,11 @@ export interface SemanticSchemaDraft extends Omit<SchemaTypeDraft, '_id' | 'id'
     readonly [key: string]: unknown;
     readonly id: string;
     readonly properties: readonly SemanticPropertyDraft[];
-    readonly temporalSemantics?: TemporalSemantics;
-    readonly timeWatermark?: TimeWatermarkPolicy;
-    /** Property that stores the parent node id for recursive tree queries. */
-    readonly parentProperty?: string;
 }
 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 properties: readonly ResolvedSemanticProperty[];
-    readonly temporalSemantics?: TemporalSemantics;
-    readonly timeWatermark?: TimeWatermarkPolicy;
-    /** Canonical logical name of the parent Property used by recursive tree queries. */
-    readonly parentProperty?: string;
 }
 export interface SemanticTypeNormalizeContext {
     readonly schema: ResolvedSemanticSchema;

package/dist/semantic-types/validate-resolved-schema.d.ts

@@ -1,6 +1,3 @@
-import type { ResolvedSemanticProperty, TemporalSemantics } from './types';
+import type { ResolvedSemanticProperty } from './types';
 /** Validates invariants that require the complete set of resolved Properties. */
-export declare const validateResolvedSchema: (properties: readonly ResolvedSemanticProperty[], options?: {
-    readonly temporalSemantics?: TemporalSemantics;
-    readonly schemaId?: string;
-}) => void;
+export declare const validateResolvedSchema: (properties: readonly ResolvedSemanticProperty[]) => void;