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

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,8 @@
 export { SchemaMappingRegistry } from './registry';
+export { getSupportedDimensions } from './supported-dimensions';
 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,13 @@
+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;
+    findById(schemaId: string, mappingId: string): SchemaMappingDefinition | undefined;
+    definitions(): readonly SchemaMappingDefinition[];
+    findSource(schemaId: string, source: string, connectionId?: string): SchemaMappingDefinition | undefined;
 }

package/dist/schema-mappings/supported-dimensions.d.ts

@@ -0,0 +1,10 @@
+import type { SchemaTypeDraft } from 'semanticdb-core';
+import type { SemanticSchemaDraft } from '../semantic-types/index';
+import type { SchemaMappingRegistry } from './registry';
+/**
+ * Dimensions declared by at least one physical Mapping for this Schema.
+ * Returns canonical property-name paths. This is a discoverability union:
+ * metric coverage, time grain, and combinations of dimensions still require
+ * planning a concrete LogicForm.
+ */
+export declare const getSupportedDimensions: (schemaId: string, schemas: Readonly<Record<string, SemanticSchemaDraft | SchemaTypeDraft>>, schemaMappings: SchemaMappingRegistry) => readonly string[];

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;
@@ -12,7 +18,8 @@ export type SourceFreshnessPolicy = {
 export interface SchemaMappingPredMatch {
     /** Defaults to the owning mapping's Schema. */
     readonly schema?: string;
-    readonly operator: string;
+    /** Restricts the match to one operator. Missing matches any aggregate operator. */
+    readonly operator?: string;
     readonly pred: string;
     /** Required conjunctive conditions across the LogicForm and PredItem queries. */
     readonly query?: QueryType;
@@ -22,6 +29,40 @@ export interface SchemaMappingPredDefinition {
     /** Physical column used as the matched PredItem's operator input. */
     readonly column: string;
 }
+export interface SchemaMappingItem {
+    readonly sourceColumn?: string;
+    /** Trusted physical SQL expression, evaluated before the Schema Property's udf.sql. */
+    readonly propertySql?: string;
+    /** Enrichment id that owns sourceColumn. Missing means the mapping's base source. */
+    readonly sourceRef?: string;
+    readonly mappingType?: 'property' | 'predItem' | 'ignored';
+    /** Direct targets for a property item; one property path (ID/name segments) for a predItem. */
+    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 +73,24 @@ 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;
+    /** Dimension Properties required by the query but unavailable on this Mapping. */
+    readonly missingDimensions?: readonly 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,27 @@
+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 propertySql?: 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, LogicformPartition, LogicformPartitionContext, LogicformPartitionShard, 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

@@ -1,8 +1,15 @@
 import type { PropertyTypeDraft, SchemaTypeDraft } from 'semanticdb-core';
-import type { LogicformType, PredItemType } from '../logicform-types';
-export type PrimalType = 'string' | 'number' | 'boolean' | 'date' | 'object';
+import type dayjs from 'dayjs';
+import type { LogicformType, PredItemType, QueryType } 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';
+} | {
+    readonly type: 'now_offset';
+    readonly offset: number;
+};
 export interface PropertySqlDefinition {
     readonly sql: string;
 }
@@ -10,6 +17,36 @@ export interface ComparableCategoryDefinition {
     readonly values: readonly string[];
     readonly direction: 1 | -1;
 }
+/** Same-Schema Property drill metadata. `up` is the single-valued side. */
+export interface PropertyHierarchyDefinition {
+    readonly up?: string;
+    readonly down?: string;
+}
+/** One additive query slice. Candidates are tried in order and must cover the slice. */
+export interface LogicformPartitionShard {
+    readonly query: QueryType;
+    readonly mappingCandidates: readonly string[];
+}
+export interface LogicformPartitionContext {
+    readonly dayjs: typeof dayjs;
+    /** Alias for dayjs; this does not provide the Moment.js API. */
+    readonly moment: typeof dayjs;
+    readonly schemas: Readonly<Record<string, ResolvedSemanticSchema>>;
+    readonly schemaMappings: readonly {
+        readonly id?: string;
+        readonly schemaId: string;
+        readonly priority?: number;
+    }[];
+    /** Runs within the same execution context. A pinned mapping bypasses its Schema partition hook. */
+    readonly execute: (logicform: LogicformType, options?: {
+        readonly mappingId?: string;
+    }) => Promise<{
+        readonly result: readonly Readonly<Record<string, unknown>>[];
+    }>;
+}
+export type LogicformPartition = (logicform: LogicformType, context: LogicformPartitionContext) => Promise<{
+    readonly shards: readonly LogicformPartitionShard[];
+}>;
 /** Extension point for plugin-owned Schema draft metadata. */
 export interface SemanticSchemaMetadata {
 }
@@ -19,7 +56,7 @@ export interface ResolvedSemanticSchemaMetadata {
 /** Extension point for legacy plugin metadata removed from the canonical Schema shape. */
 export interface LegacySemanticSchemaMetadata {
 }
-export interface SemanticPropertyDraft extends Omit<PropertyTypeDraft, '_id' | '_sid' | 'id' | 'sid' | 'type' | 'primal_type' | 'isArray' | 'granularity' | 'is_observation' | 'is_snapshot' | 'temporalSemantics' | 'is_dynamic' | 'udf' | 'is_comparable' | 'comparable_order'> {
+export interface SemanticPropertyDraft extends Omit<PropertyTypeDraft, '_id' | '_sid' | 'id' | 'sid' | 'type' | 'primal_type' | 'isArray' | 'granularity' | 'is_observation' | 'is_snapshot' | 'temporalSemantics' | 'is_dynamic' | 'udf' | 'is_comparable' | 'comparable_order' | 'hierarchy'> {
     readonly id?: string;
     readonly type: string;
     readonly primal_type?: PrimalType;
@@ -39,24 +76,23 @@ 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 partition?: LogicformPartition;
     readonly properties: readonly SemanticPropertyDraft[];
-    readonly temporalSemantics?: TemporalSemantics;
-    /** 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 is_calendar?: boolean;
+    readonly partition?: LogicformPartition;
     readonly properties: readonly ResolvedSemanticProperty[];
-    readonly temporalSemantics?: TemporalSemantics;
-    /** Canonical logical name of the parent Property used by recursive tree queries. */
-    readonly parentProperty?: string;
 }
 export interface SemanticTypeNormalizeContext {
     readonly schema: ResolvedSemanticSchema;
     readonly property: ResolvedSemanticProperty;
     readonly now: Date;
-    readonly requestLatestDataDate: () => Promise<Date | undefined>;
+    readonly requestTimeWatermark: (requestedUpperBound: Date) => Promise<Date | undefined>;
 }
 /** Context used when deciding whether a value must be evaluated per time period. */
 export interface SemanticPeriodEvaluationContext {
@@ -81,6 +117,10 @@ export interface SemanticTypeResultContext {
 export interface SemanticTypeDefinition {
     readonly name: string;
     readonly primalType: PrimalType;
+    /** Semantic types with an intrinsic array container, such as tag. */
+    readonly isArray?: true;
+    /** Normalize a complete physical value before per-element result hydration. */
+    readonly normalizeResult?: (value: unknown, context: SemanticTypeResultContext) => unknown;
     readonly validateProperty?: (property: ResolvedSemanticProperty) => void;
     /** Whether this semantic property requires one evaluation per time bucket. */
     readonly requiresPerPeriodEvaluation?: (context: SemanticPeriodEvaluationContext) => boolean;

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;