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

package/dist/planner/select-schema-mapping.d.ts

@@ -1,26 +1,38 @@
 import type { LogicformType } from '../logicform-types';
 import type { SemanticDBPlugin } from '../plugins/index';
-import type { SchemaMappingDefinition, SchemaMappingRegistry, SchemaMappingSelection } from '../schema-mappings/index';
+import type { SchemaMappingDefinition, PropertyMappingCalculation, SchemaMappingRegistry, SchemaMappingSelection } from '../schema-mappings/index';
 import type { ResolvedSemanticSchema } from '../semantic-types/index';
 import { type OperatorRegistry } from '../operators/index';
+import type { PhysicalQueryFilterPlan } from './types';
 export interface PredMappingRewrite {
     readonly predIndex: number;
     readonly column: string;
 }
+export interface GroupPathBinding {
+    readonly canonicalId: string;
+    readonly sourceColumn: string;
+    readonly targetSchemaId: string;
+}
 export interface SelectedSchemaMapping {
     readonly mapping: SchemaMappingDefinition;
     readonly logicform: LogicformType;
     readonly predRewrites: readonly PredMappingRewrite[];
+    readonly physicalQueryFilters: readonly PhysicalQueryFilterPlan[];
+    readonly groupPathBindings: readonly GroupPathBinding[];
     readonly selection: SchemaMappingSelection;
 }
 export interface MappedPropertySource {
     readonly column: string;
     readonly sourceRef?: string;
-    readonly sql?: string;
+    readonly calculation?: PropertyMappingCalculation;
+    readonly propertyId?: string;
 }
-export declare const hasPropertySql: (mapping: SchemaMappingDefinition) => boolean;
 export declare const mappedPropertyColumn: (mapping: SchemaMappingDefinition, schema: ResolvedSemanticSchema, reference: string) => string | undefined;
 export declare const mappedPropertySource: (mapping: SchemaMappingDefinition, schema: ResolvedSemanticSchema, reference: string) => MappedPropertySource | undefined;
+/** A physical column for the complete logical path, without traversing its relations. */
+export declare const mappedPropertyPathSource: (mapping: SchemaMappingDefinition, schema: ResolvedSemanticSchema, reference: string, resolveSchema?: (schemaId: string) => ResolvedSemanticSchema) => MappedPropertySource | undefined;
+/** A related entity's mapped ID column is also the root relation's value. */
+export declare const mappedRelationIdSource: (mapping: SchemaMappingDefinition, schema: ResolvedSemanticSchema, reference: string, resolveSchema?: (schemaId: string) => ResolvedSemanticSchema) => MappedPropertySource | undefined;
 export declare const selectSchemaMapping: (logicform: LogicformType, schema: ResolvedSemanticSchema, mappings: SchemaMappingRegistry, options?: {
     readonly mappingCandidates?: readonly string[];
     readonly preferredConnectionId?: string;

package/dist/planner/types.d.ts

@@ -1,3 +1,4 @@
+import type { ResolvedMappingSource, PropertyMappingCalculation } from '../schema-mappings/index';
 import type { CoreComputeProvider } from '../physical/index';
 import type { LogicformType } from '../logicform-types';
 import type { ResultProperty } from '../operators/index';
@@ -11,6 +12,8 @@ export interface FieldReferencePlan {
     readonly column: string;
     readonly qualifier: string;
     readonly sql?: string;
+    /** Planned row-level value; inlined for single-use filters, otherwise materialized. */
+    readonly computation?: Expression;
     readonly timestampColumn?: string;
     /** Source alias that supplies $TS when it differs from the Property's Schema. */
     readonly timestampQualifier?: string;
@@ -19,10 +22,21 @@ export interface FieldReferencePlan {
     readonly normalizeStringArray?: boolean;
     readonly comparable?: ComparableCategoryDefinition;
 }
+/** Filter against a column of the selected physical source. */
+export interface PhysicalQueryFilterPlan {
+    readonly sourceColumn: string;
+    readonly value: string | number | boolean | LogicformType | LogicalQuerySubquery;
+}
 export interface LogicalQuerySubquery {
     readonly kind: 'logicform-subquery';
     readonly plan: LogicalPlan;
 }
+/** Reference to another projected output in a HAVING comparison. */
+export interface LogicalOutputReference {
+    readonly kind: 'output-reference';
+    readonly name: string;
+}
+export declare const isLogicalOutputReference: (value: unknown) => value is LogicalOutputReference;
 export interface LogicalQueryOperator {
     readonly kind: 'query-operator';
     readonly operator: string;
@@ -51,6 +65,13 @@ export declare const isLogicalQueryOperator: (value: unknown) => value is Logica
 export declare const isLogicalOrdinalQuery: (value: unknown) => value is LogicalOrdinalQuery;
 export declare const isLogicalExpressionQuery: (value: unknown) => value is LogicalExpressionQuery;
 export type Expression = {
+    readonly kind: 'mapping-computation';
+    readonly definition: PropertyMappingCalculation & {
+        readonly id: string;
+    };
+    readonly inputs: Readonly<Record<string, Expression>>;
+    readonly alias: string;
+} | {
     readonly kind: 'array-element';
     readonly schemaId: string;
     readonly property: string;
@@ -126,12 +147,13 @@ export interface JoinPlan {
     readonly targetSchemaId: string;
     /** Physical connection selected for the target Schema mapping. */
     readonly targetConnectionId?: string;
-    readonly targetSource: string;
-    readonly targetSourceSql?: string;
+    readonly targetSource: ResolvedMappingSource;
     /** Two projection layers for the target Schema Mapping and its UDFs. */
     readonly targetMappingSourcePlan?: LogicalPlan;
     readonly targetAlias: string;
     readonly targetColumn: string;
+    readonly sourceExpression?: Expression;
+    readonly targetExpression?: Expression;
     readonly targetSql?: string;
     readonly targetTimestampColumn?: string;
     readonly temporalCondition?: TemporalJoinConditionPlan;
@@ -154,8 +176,7 @@ export type TemporalJoinConditionPlan = {
 export interface EnrichmentJoinPlan {
     readonly kind: 'enrichment-left';
     readonly id: string;
-    readonly source: string;
-    readonly sourceSql?: string;
+    readonly source: ResolvedMappingSource;
     readonly alias: string;
     readonly baseAlias: string;
     readonly keys: readonly {
@@ -223,19 +244,28 @@ export type RowIdentityPlan = {
 };
 export interface LogicalPlan {
     readonly schemaId: string;
-    readonly source: string;
+    readonly source: ResolvedMappingSource | undefined;
     /** 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;
+    /** Only computation sources actually required by this plan. */
+    readonly computationSources?: readonly {
+        readonly id: string;
+        readonly alias: string;
+        readonly source: string;
+        readonly schemaId: string;
+        readonly mappingSource: string;
+        readonly connectionId: string;
+    }[];
     /** Child relations combined by their compatible group identity. */
     readonly subplans?: readonly LogicalPlan[];
     /** Vertically combine disjoint aggregate shards by summing matching output groups. */
     readonly sumPartition?: true;
+    /** Vertically combine disjoint physical detail rows. */
+    readonly rowPartition?: true;
     /** Enumerated group values corresponding to subplans, combined vertically. */
     readonly splitGroup?: {
         readonly name: string;
@@ -259,6 +289,7 @@ export interface LogicalPlan {
     readonly columnProperties?: readonly ResultProperty[];
     readonly groupBy: readonly ProjectionPlan[];
     readonly query?: Readonly<Record<string, unknown>>;
+    readonly physicalQueryFilters?: readonly PhysicalQueryFilterPlan[];
     readonly having?: Readonly<Record<string, unknown>>;
     readonly orderBy: readonly OrderPlan[];
     readonly pagination?: PaginationPlan;
@@ -282,11 +313,11 @@ export interface QueryLineage {
         readonly schemaId: string;
         readonly schemaName: string;
         readonly physicalTable: string;
-        readonly provider: CoreComputeProvider['kind'];
+        readonly provider: CoreComputeProvider['kind'] | 'runtime';
         readonly connectionId?: string;
         readonly connections?: readonly {
             readonly connectionId: string;
-            readonly provider: CoreComputeProvider['kind'];
+            readonly provider: CoreComputeProvider['kind'] | 'runtime';
         }[];
     };
     readonly outputs: readonly LineageOutput[];

package/dist/planner/udf-inputs.d.ts

@@ -0,0 +1,6 @@
+import type { ResolvedSemanticSchema } from '../semantic-types/index';
+/** Give Schema UDFs explicit logical inputs while preserving quoted string contents. */
+export declare const bindUdfInputs: (sql: string, schema: ResolvedSemanticSchema) => {
+    sql: string;
+    references: Readonly<Record<string, string>>;
+};

package/dist/plugins/types.d.ts

@@ -3,7 +3,7 @@ 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 { SchemaMappingDefinition, SchemaMappingItem, SchemaMappingSource, ResolvedMappingSource } from '../schema-mappings/index';
 import type { ResolvedSemanticProperty, ResolvedSemanticSchema, SemanticSchemaDraft, SemanticTypeDefinition, TimeWatermarkPolicy } from '../semantic-types/types';
 export interface SchemaMetadataPlugin {
     readonly keys: readonly string[];
@@ -47,6 +47,8 @@ export interface QueryOperatorPlanContext {
     readonly schema: ResolvedSemanticSchema;
     readonly property: ResolvedSemanticProperty;
     readonly connectionId: string;
+    /** Resolve public source configuration for planning, rendering and dependency tracking. */
+    readonly resolveSource: (source: SchemaMappingSource) => ResolvedMappingSource;
     readonly resolveSchema?: (schemaId: string) => ResolvedSemanticSchema;
     readonly resolveMapping: (schemaId: string, preferredConnectionId?: string) => SchemaMappingDefinition;
 }
@@ -54,7 +56,7 @@ export interface QueryOperatorCompileContext {
     readonly field: string;
     readonly provider: CoreComputeProvider;
     readonly bind: (value: unknown) => string;
-    readonly renderSource: (source: string, sourceSql?: string) => string;
+    readonly renderSource: (source: unknown) => string;
 }
 export interface QueryOperatorAuthorizeContext {
     readonly schema: ResolvedSemanticSchema;

package/dist/schema/index.d.ts

@@ -1,4 +1,5 @@
 export { buildFieldMap, getProperty, getSchema, } from './schema-registry';
+export { isReverseRelation, resolvePropertyValuePath, resolveRelationKeys } from './relation-keys';
 export { resolvePropertyPath } from './resolve-property-path';
 export { isDependentProjection } from './dependent-projection';
 export { isConcreteEntityId, resolveEntityFilterProperty, resolveEntityIdProperty, } from './entity-identity';

package/dist/schema/relation-keys.d.ts

@@ -0,0 +1,11 @@
+import type { ResolvedSemanticProperty } from '../semantic-types/index';
+import type { ResolvedPropertyPath, ResolvedRelationSegment, ResolvedSchemaLookup } from './resolve-property-path';
+/** Virtual scalar one-to-one objects are supplied by the metadata owner. */
+export declare const isReverseRelation: (property: ResolvedSemanticProperty) => boolean;
+/** Join keys are semantic properties; physical mappings are applied by the planner. */
+export declare const resolveRelationKeys: (relation: ResolvedRelationSegment) => {
+    readonly source: ResolvedSemanticProperty;
+    readonly target: ResolvedSemanticProperty;
+};
+/** A reverse entity's value is the related row's ID, never the local entity ID. */
+export declare const resolvePropertyValuePath: (path: ResolvedPropertyPath, lookup?: ResolvedSchemaLookup) => ResolvedPropertyPath;

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

@@ -0,0 +1,3 @@
+import type { SchemaMappingDefinition, PropertyMappingCalculation } from './types';
+export declare const computationInputNames: (definition: PropertyMappingCalculation) => readonly string[];
+export declare const validateMappingValues: (mapping: SchemaMappingDefinition) => void;

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

@@ -2,7 +2,10 @@ export { SchemaMappingRegistry } from './registry';
 export { getSupportedDimensions } from './supported-dimensions';
 export { parseDailyExpireAt } from './freshness';
 export { isMappingTimeGranularity, isSchemaMappingGranularity, } from './granularity';
-export type { SchemaMappingDefinition, SchemaMappingEnrichmentDefinition, SchemaMappingEnrichmentKey, SchemaMappingItem, SchemaMappingGranularity, SchemaMappingGranularityExtensions, SchemaMappingPointTemporalDefinition, SchemaMappingSelection, RejectedSchemaMapping, SourceFreshnessPolicy, } from './types';
+export type { SchemaMappingDefinition, SchemaMappingSource, ResolvedMappingSource, PropertyMappingCalculation, PropertyMappingValue, PropertyMapping, PredItemMapping, IgnoredMapping, ComputationExpression, ComputationInput, SchemaMappingEnrichmentDefinition, SchemaMappingEnrichmentKey, SchemaMappingItem, QueryPathBinding, QueryPathMappingDefinition, SchemaMappingGranularity, SchemaMappingGranularityExtensions, SchemaMappingPointTemporalDefinition, SchemaMappingSelection, RejectedSchemaMapping, SourceFreshnessPolicy, } from './types';
 export type { SchemaMappingPredDefinition, SchemaMappingPredMatch, } from './types';
 export { fromYiAskSchemaMapping } from './yiask';
 export type { YiAskSchemaMappingItem, YiAskSchemaMappingRecord } from './yiask';
+export { computationInputNames } from './computations';
+export { sqlValueParts } from './sql-inputs';
+export { sourceIdentity, sqlIdentity, resolveMappingSource, schemaMappingIdentity, isResolvedMappingSource } from './source';

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

@@ -0,0 +1,11 @@
+import type { ResolvedMappingSource, SchemaMappingDefinition, SchemaMappingSource } from './types';
+/** Opaque SQL contents share an identity scheme without parsing their semantics. */
+export declare const sqlIdentity: (sql: string) => string;
+/** SQL source identity follows its contents rather than a fictitious table name. */
+export declare const resolveMappingSource: (source: SchemaMappingSource) => ResolvedMappingSource;
+export declare const sourceIdentity: (source: SchemaMappingSource) => string;
+export declare const schemaMappingIdentity: (mapping: SchemaMappingDefinition) => string;
+/** Check opaque plugin payloads without reinterpreting public source configuration. */
+export declare const isResolvedMappingSource: (value: unknown) => value is ResolvedMappingSource;
+export declare const validateMappingSource: (source: unknown) => void;
+export declare const rejectObsoleteSourceFields: (container: object) => void;

package/dist/schema-mappings/sql-inputs.d.ts

@@ -0,0 +1,7 @@
+export type SqlValuePart = string | {
+    readonly input: string;
+};
+/** Preserve trusted SQL verbatim, resolving only {{input}} outside literals, identifiers and comments.
+ * SQL syntax, scalar cardinality and allowed operations are the database's responsibility.
+ */
+export declare const sqlValueParts: (sql: string) => readonly SqlValuePart[];

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

@@ -1,5 +1,23 @@
 import type { PredItemType, QueryType } from '../logicform-types';
 import type { TimeGranularity } from '../semantic-types/index';
+/** A table or a trusted SQL query supplying a complete row set. */
+export type SchemaMappingSource = {
+    readonly kind: 'table';
+    readonly table: string;
+} | {
+    readonly kind: 'sql';
+    readonly sql: string;
+};
+/** Validated row-set source passed unchanged through planning and compilation. */
+export type ResolvedMappingSource = {
+    readonly kind: 'table';
+    readonly identity: string;
+    readonly path: readonly string[];
+} | {
+    readonly kind: 'sql';
+    readonly identity: string;
+    readonly sql: string;
+};
 /** Plugin-owned physical grains extend this interface through module augmentation. */
 export interface SchemaMappingGranularityExtensions {
 }
@@ -15,6 +33,54 @@ export type SourceFreshnessPolicy = {
 } | {
     readonly mode: 'manual';
 };
+/** Structured, row-level expressions. Values are bound parameters, never SQL text. */
+export type ComputationExpression = {
+    readonly input: string;
+} | {
+    readonly value: string | number | boolean | null;
+} | {
+    readonly op: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'add' | 'subtract' | 'multiply' | 'divide';
+    readonly left: ComputationExpression;
+    readonly right: ComputationExpression;
+} | {
+    readonly op: 'and' | 'or' | 'coalesce';
+    readonly args: readonly ComputationExpression[];
+} | {
+    readonly op: 'not' | 'isNull' | 'isNotNull';
+    readonly arg: ComputationExpression;
+} | {
+    readonly op: 'case';
+    readonly cases: readonly {
+        readonly when: ComputationExpression;
+        readonly then: ComputationExpression;
+    }[];
+    readonly else: ComputationExpression;
+};
+export type ComputationInput = {
+    readonly property: string;
+    readonly sourceColumn?: never;
+} | {
+    readonly sourceColumn: string;
+    readonly sourceRef?: string;
+    readonly property?: never;
+};
+/** A scalar calculation owned by one Property mapping. */
+export type PropertyMappingCalculation = {
+    readonly inputs: Readonly<Record<string, ComputationInput>>;
+} & ({
+    readonly kind: 'expression';
+    readonly expression: ComputationExpression;
+} | {
+    readonly kind: 'sql';
+    readonly sql: string;
+    /** Cache policy for this opaque SQL expression, including any internal table reads. */
+    readonly freshness?: SourceFreshnessPolicy;
+});
+export type PropertyMappingValue = {
+    readonly kind: 'column';
+    readonly column: string;
+    readonly sourceRef?: string;
+} | PropertyMappingCalculation;
 export interface SchemaMappingPredMatch {
     /** Defaults to the owning mapping's Schema. */
     readonly schema?: string;
@@ -29,19 +95,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. */
+export interface PropertyMapping {
+    readonly mappingType: 'property';
+    /** One logical Property ID, or an ID path for a directly mapped related Property. */
+    readonly propertyId: string;
+    readonly value: PropertyMappingValue;
     readonly granularity?: SchemaMappingGranularity;
 }
+export interface PredItemMapping {
+    readonly mappingType: 'predItem';
+    readonly sourceColumn: string;
+    readonly predItem: PredItemType;
+    /** Optional exact dimension path encoded by the conditional column. */
+    readonly propertyTarget?: readonly string[];
+}
+export interface IgnoredMapping {
+    readonly mappingType: 'ignored';
+    readonly sourceColumn: string;
+}
+export type SchemaMappingItem = PropertyMapping | PredItemMapping | IgnoredMapping;
+export type QueryPathBinding = {
+    readonly sourceColumn: string;
+    readonly mappingType: 'literal';
+    readonly value: string | number | boolean;
+} | {
+    readonly sourceColumn: string;
+    readonly mappingType: 'value';
+    /** Path to the matched entity relation value. */
+    readonly valuePath: readonly string[];
+};
+/** Map an entity relation path in a root query or groupby to physical columns. */
+export interface QueryPathMappingDefinition {
+    readonly path: readonly string[];
+    readonly bindings: readonly QueryPathBinding[];
+}
 export interface SchemaMappingEnrichmentKey {
     /** Physical column on the mapping's base source. */
     readonly baseColumn: string;
@@ -56,8 +143,7 @@ export interface SchemaMappingPointTemporalDefinition {
 /** A same-connection physical extension of one logical Schema. */
 export interface SchemaMappingEnrichmentDefinition {
     readonly id: string;
-    readonly source: string;
-    readonly sourceSql?: string;
+    readonly source: SchemaMappingSource;
     readonly on: readonly SchemaMappingEnrichmentKey[];
     readonly temporal?: SchemaMappingPointTemporalDefinition;
     /** Missing means queries depending on this enrichment are not cached. */
@@ -69,14 +155,14 @@ export interface SchemaMappingDefinition {
     readonly schemaId: string;
     /** Database connection used by this physical mapping. */
     readonly connectionId: string;
-    /** Stable physical source identity used by connection routing, lineage, and cache invalidation. */
-    readonly source: string;
-    /** Optional trusted query compiled as a derived-table source instead of reading source directly. */
-    readonly sourceSql?: string;
+    /** Physical row set supplied by a table or a trusted SQL query. */
+    readonly source: SchemaMappingSource;
     /** 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[];
+    /** Entity paths handled directly by physical source columns for query and groupby. */
+    readonly queryPathMappings?: readonly QueryPathMappingDefinition[];
     /** Higher values win when multiple candidates cover the same LogicForm. */
     readonly priority?: number;
     /** Missing means queries depending on this physical source are not cached. */

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

@@ -1,26 +1,13 @@
 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;
-}
+import type { SchemaMappingDefinition, SchemaMappingSource, SchemaMappingEnrichmentDefinition, SchemaMappingItem, QueryPathMappingDefinition } from './types';
+export type YiAskSchemaMappingItem = SchemaMappingItem;
 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 schemaId: string;
+    readonly connectionId: string;
+    readonly source: SchemaMappingSource;
     readonly enrichments?: readonly SchemaMappingEnrichmentDefinition[];
+    readonly queryPathMappings?: readonly QueryPathMappingDefinition[];
     readonly mappings: readonly YiAskSchemaMappingItem[];
     readonly enabled?: boolean;
 }

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

@@ -56,9 +56,20 @@ 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' | 'hierarchy'> {
+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' | 'componentProperties'> {
     readonly id?: string;
+    /** Readable calculation exposed on result Schema properties. */
+    readonly formulaText?: string | null;
     readonly type: string;
+    /** Relationship cardinality declared by the caller. */
+    readonly ref_cardinality?: 'one-to-one' | 'many-to-one' | 'one-to-many' | 'many-to-many';
+    /** Caller-supplied virtual relation; scalar one-to-one objects are reverse references. */
+    readonly is_virtual?: boolean;
+    /** Optional provenance to disambiguate the original reverse-reference foreign key. */
+    readonly reverse_ref?: {
+        readonly schemaId: string;
+        readonly propertyId: string;
+    };
     readonly primal_type?: PrimalType;
     readonly isArray?: boolean;
     readonly granularity?: TimeGranularity;
@@ -66,16 +77,21 @@ export interface SemanticPropertyDraft extends Omit<PropertyTypeDraft, '_id' | '
     readonly is_dynamic?: boolean;
     readonly udf?: PropertySqlDefinition;
     readonly comparable?: ComparableCategoryDefinition;
+    readonly componentProperties?: readonly SemanticPropertyDraft[];
 }
 export interface ResolvedSemanticProperty extends Omit<SemanticPropertyDraft, 'id' | 'primal_type' | 'isArray' | 'is_dynamic'> {
     readonly id: string;
     readonly primal_type: PrimalType;
     readonly isArray: boolean;
     readonly is_dynamic?: boolean;
+    /** Child metric metadata exposed on computed result Schema properties. */
+    readonly componentProperties?: readonly ResolvedSemanticProperty[];
 }
 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;
+    /** Registered custom aggregate/component/runtime operator names available on this Schema. */
+    readonly metrics?: readonly string[];
     /** Marks the single Schema whose complete rows are loaded as calendar execution context. */
     readonly is_calendar?: boolean;
     readonly partition?: LogicformPartition;
@@ -84,6 +100,8 @@ export interface SemanticSchemaDraft extends Omit<SchemaTypeDraft, '_id' | 'id'
 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;
+    /** Registered custom aggregate/component/runtime operator names available on this Schema. */
+    readonly metrics?: readonly string[];
     readonly is_calendar?: boolean;
     readonly partition?: LogicformPartition;
     readonly properties: readonly ResolvedSemanticProperty[];
@@ -93,6 +111,8 @@ export interface SemanticTypeNormalizeContext {
     readonly property: ResolvedSemanticProperty;
     readonly now: Date;
     readonly requestTimeWatermark: (requestedUpperBound: Date) => Promise<Date | undefined>;
+    /** Observe a complete date condition without changing its normalization semantics. */
+    readonly onDateQueryNormalized?: (requested: unknown, effective: unknown, timeWatermark?: Date) => void;
 }
 /** Context used when deciding whether a value must be evaluated per time period. */
 export interface SemanticPeriodEvaluationContext {