semanticdb-v2 2.0.0-alpha.1

package/dist/planner/semantics/registry.d.ts

@@ -0,0 +1,32 @@
+import type { PredItemType } from '../../logicform-types';
+import type { LogicformType, QueryType } from '../../logicform-types';
+import type { ResolvedSemanticProperty, ResolvedSemanticSchema } from '../../semantic-types/index';
+import type { OperatorDefinition, ResultProperty } from '../../operators/index';
+export interface PlannerSemanticRuleContext {
+    readonly pred: PredItemType;
+    readonly schema: ResolvedSemanticSchema;
+    readonly sourceProperty?: ResolvedSemanticProperty;
+    readonly outputProperty: ResultProperty;
+    readonly operator?: OperatorDefinition;
+}
+export interface PlannerSemanticQueryContext {
+    readonly logicform: LogicformType;
+    readonly schema: ResolvedSemanticSchema;
+    readonly query?: QueryType;
+}
+export interface PlannerSemanticResolution {
+    readonly outputProperty?: ResultProperty;
+}
+export interface PlannerSemanticRule {
+    readonly name: string;
+    readonly resolveProjection?: (context: PlannerSemanticRuleContext) => PlannerSemanticResolution | undefined;
+    readonly resolveQuery?: (context: PlannerSemanticQueryContext) => QueryType | undefined;
+}
+export declare class PlannerSemanticRegistry {
+    #private;
+    constructor(rules?: readonly PlannerSemanticRule[]);
+    register(rule: PlannerSemanticRule): this;
+    resolveProjection(context: PlannerSemanticRuleContext): ResultProperty;
+    resolveQuery(context: PlannerSemanticQueryContext): QueryType | undefined;
+    rules(): readonly PlannerSemanticRule[];
+}

package/dist/planner/semantics/registry.js

@@ -0,0 +1 @@
+import{SemanticDBError as s}from"../../errors.js";class o{#e=new Map;constructor(e=[]){for(const r of e)this.register(r)}register(e){if(!e.name)throw new s("INVALID_SEMANTIC_RULE","Semantic rule name must not be empty");if(this.#e.has(e.name))throw new s("SEMANTIC_RULE_ALREADY_REGISTERED",`Semantic rule is already registered: ${e.name}`,{rule:e.name});return this.#e.set(e.name,e),this}resolveProjection(e){return[...this.#e.values()].reduce((r,t)=>t.resolveProjection?.({...e,outputProperty:r})?.outputProperty??r,e.outputProperty)}resolveQuery(e){return[...this.#e.values()].reduce((r,t)=>t.resolveQuery?.({...e,...r?{query:r}:{}})??r,e.query)}rules(){return[...this.#e.values()]}}export{o as PlannerSemanticRegistry};

package/dist/planner/types.d.ts

@@ -0,0 +1,202 @@
+import type { CoreComputeProvider } from '../physical/index';
+import type { ResultProperty } from '../operators/index';
+import type { ComparableCategoryDefinition, TimeGranularity } from '../semantic-types/index';
+export interface FieldReferencePlan {
+    readonly schemaId: string;
+    readonly property: string;
+    /** Stable logical Schema Property ID; column may come from a selected Mapping. */
+    readonly propertyId?: string;
+    readonly column: string;
+    readonly qualifier: string;
+    readonly sql?: string;
+    readonly timestampColumn?: string;
+    readonly isArray?: boolean;
+    readonly comparable?: ComparableCategoryDefinition;
+}
+export interface LogicalQuerySubquery {
+    readonly kind: 'logicform-subquery';
+    readonly plan: LogicalPlan;
+}
+export interface LogicalRecursiveQuery {
+    readonly kind: 'recursive-query';
+    readonly schemaId: string;
+    readonly source: string;
+    readonly sourceSql?: string;
+    readonly idColumn: string;
+    readonly parentColumn: string;
+    readonly roots: readonly unknown[];
+    readonly includeSelf: boolean;
+}
+export interface LogicalOrdinalQuery {
+    readonly kind: 'ordinal-query';
+    readonly comparable: ComparableCategoryDefinition;
+    readonly condition: unknown;
+}
+export declare const isLogicalQuerySubquery: (value: unknown) => value is LogicalQuerySubquery;
+export declare const isLogicalRecursiveQuery: (value: unknown) => value is LogicalRecursiveQuery;
+export declare const isLogicalOrdinalQuery: (value: unknown) => value is LogicalOrdinalQuery;
+export type Expression = {
+    readonly kind: 'array-element';
+    readonly schemaId: string;
+    readonly property: string;
+    readonly expansionPath: string;
+} | {
+    readonly kind: 'column';
+    readonly schemaId?: string;
+    readonly property: string;
+    readonly propertyId?: string;
+    readonly column: string;
+    readonly qualifier?: string;
+} | {
+    readonly kind: 'property-sql';
+    readonly schemaId: string;
+    readonly property: string;
+    readonly propertyId: string;
+    readonly sql: string;
+    readonly qualifier?: string;
+    readonly timestampColumn?: string;
+} | {
+    readonly kind: 'operator';
+    readonly operator: string;
+    readonly property?: string;
+    readonly column?: string;
+    readonly qualifier?: string;
+    readonly schemaId?: string;
+    readonly input?: Expression;
+    readonly components?: readonly Expression[];
+    readonly args: Readonly<Record<string, unknown>>;
+    readonly query?: Readonly<Record<string, unknown>>;
+} | {
+    readonly kind: 'window';
+    readonly function: 'rank' | 'rowNumber';
+    readonly input: Expression;
+    readonly partitionBy: readonly Expression[];
+    readonly direction: 'ASC' | 'DESC';
+} | {
+    readonly kind: 'cumulative';
+    readonly function: 'sum' | 'min' | 'max';
+    readonly input: Expression;
+    readonly partitionBy: readonly Expression[];
+    readonly orderBy: readonly {
+        readonly expression: Expression;
+        readonly direction: 'ASC' | 'DESC';
+    }[];
+} | {
+    readonly kind: 'ordinal-encode';
+    readonly input: Expression;
+    readonly comparable: ComparableCategoryDefinition;
+} | {
+    readonly kind: 'ordinal-decode';
+    readonly input: Expression;
+    readonly comparable: ComparableCategoryDefinition;
+};
+export interface ProjectionPlan {
+    readonly name: string;
+    readonly expression: Expression;
+}
+export interface OrderPlan {
+    readonly name: string;
+    readonly direction: 'ASC' | 'DESC';
+    readonly comparable?: ComparableCategoryDefinition;
+    readonly expression?: Expression;
+}
+export interface JoinPlan {
+    readonly kind: 'left';
+    readonly path: string;
+    readonly sourceAlias: string;
+    readonly sourceColumn: string;
+    readonly sourceSql?: string;
+    readonly sourceTimestampColumn?: string;
+    readonly sourceTimestampGranularity?: TimeGranularity;
+    readonly targetSchemaId: string;
+    readonly targetSource: string;
+    readonly targetSourceSql?: string;
+    readonly targetAlias: string;
+    readonly targetColumn: string;
+    readonly targetSql?: string;
+    readonly targetTimestampColumn?: string;
+    readonly targetTimestampGranularity?: TimeGranularity;
+    readonly sourceArrayExpansionPath?: string;
+}
+export interface ArrayExpansionPlan {
+    readonly path: string;
+    readonly sourceAlias: string;
+    readonly sourceColumn: string;
+    readonly sourceSql?: string;
+    readonly sourceTimestampColumn?: string;
+    readonly alias: string;
+}
+export type PaginationPlan = {
+    readonly kind: 'rows';
+    readonly page: number;
+    readonly pageSize: number;
+} | {
+    readonly kind: 'ratio';
+    readonly page: number;
+    readonly ratio: number;
+};
+export interface GroupLimitPlan {
+    readonly count: number;
+    readonly partitionBy: readonly string[];
+    readonly orderBy: readonly OrderPlan[];
+}
+export type RowIdentityPlan = {
+    readonly kind: 'group';
+    readonly names: readonly string[];
+} | {
+    readonly kind: 'property';
+    readonly column: string;
+    readonly internalName: string;
+} | {
+    readonly kind: 'generated';
+} | {
+    readonly kind: 'singleton';
+};
+export interface LogicalPlan {
+    readonly schemaId: string;
+    readonly source: string;
+    /** Trusted derived-table SQL supplied by the selected physical mapping. */
+    readonly sourceSql?: string;
+    /** Physical mapping selected by the Planner for this logical Schema. */
+    readonly mappingId?: string;
+    /** Child relations combined by their compatible group identity. */
+    readonly composition?: readonly LogicalPlan[];
+    /** Optional query plan compiled as the derived-table source of this plan. */
+    readonly sourcePlan?: LogicalPlan;
+    readonly sourceAlias?: string;
+    readonly fields: Readonly<Record<string, string>>;
+    readonly fieldReferences?: Readonly<Record<string, FieldReferencePlan>>;
+    readonly joins?: readonly JoinPlan[];
+    readonly arrayExpansions?: readonly ArrayExpansionPlan[];
+    readonly projections: readonly ProjectionPlan[];
+    readonly columnProperties?: readonly ResultProperty[];
+    readonly groupBy: readonly ProjectionPlan[];
+    readonly query?: Readonly<Record<string, unknown>>;
+    readonly having?: Readonly<Record<string, unknown>>;
+    readonly orderBy: readonly OrderPlan[];
+    readonly pagination?: PaginationPlan;
+    readonly groupLimit?: GroupLimitPlan;
+    /** Strategy used by the executor to add the system-owned `_id` to each result row. */
+    readonly rowIdentity: RowIdentityPlan;
+}
+export interface LineageColumnSource {
+    readonly schemaId: string;
+    readonly propertyId: string;
+    readonly propertyName: string;
+    readonly physicalColumn: string;
+}
+export interface LineageOutput {
+    readonly name: string;
+    readonly sources: readonly LineageColumnSource[];
+    readonly transformations: readonly string[];
+}
+export interface QueryLineage {
+    readonly source: {
+        readonly schemaId: string;
+        readonly schemaName: string;
+        readonly physicalTable: string;
+        readonly provider: CoreComputeProvider['kind'];
+    };
+    readonly outputs: readonly LineageOutput[];
+    readonly filters: readonly LineageColumnSource[];
+}

package/dist/planner/types.js

@@ -0,0 +1 @@
+const o=r=>typeof r=="object"&&r!==null&&!Array.isArray(r)&&r.kind==="logicform-subquery"&&typeof r.plan=="object"&&r.plan!==null,i=r=>typeof r=="object"&&r!==null&&!Array.isArray(r)&&r.kind==="recursive-query",y=r=>typeof r=="object"&&r!==null&&!Array.isArray(r)&&r.kind==="ordinal-query";export{y as isLogicalOrdinalQuery,o as isLogicalQuerySubquery,i as isLogicalRecursiveQuery};

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

@@ -0,0 +1,2 @@
+import type { LegacySchemaPluginContext } from '../types';
+export declare const normalizeLegacyHierarchy: ({ source, properties, }: LegacySchemaPluginContext) => Readonly<Record<string, unknown>>;

package/dist/plugins/hierarchy/compatibility.js

@@ -0,0 +1 @@
+import{SemanticDBError as h}from"../../errors.js";const s=({source:o,properties:y})=>{const t=o.hierarchy;if(!Array.isArray(t))return t===void 0?{}:{hierarchy:t};let n=o.hierarchy_property;if(typeof n!="string"||n.length===0){const r=y.filter(({type:c})=>c==="ID");if(r.length!==1)throw new h("LEGACY_HIERARCHY_ID_PROPERTY_REQUIRED","Legacy Schema hierarchy without hierarchy_property must contain exactly one ID property",{idPropertyCount:r.length});const e=r[0];n=e?.id??e?.name}const i=t.map(r=>{if(typeof r!="object"||r===null||Array.isArray(r))return;const e=r;if(!(typeof e.name!="string"||!Number.isInteger(e.code_length)))return{name:e.name,...Array.isArray(e.syno)?{synonyms:e.syno}:{},codeLength:e.code_length}});if(i.some(r=>r===void 0))return{};const a=t[0];return{hierarchy:{property:n,storage:a?.use_full_length===!0?"zero-padded":"compact",levels:i}}};export{s as normalizeLegacyHierarchy};

package/dist/plugins/hierarchy/entity-identity.d.ts

@@ -0,0 +1,2 @@
+import type { ResolvedSemanticProperty, ResolvedSemanticSchema } from '../../semantic-types/types';
+export declare const resolveHierarchyEntityFilterProperty: (schema: ResolvedSemanticSchema) => ResolvedSemanticProperty | undefined;

package/dist/plugins/hierarchy/entity-identity.js

@@ -0,0 +1 @@
+import{SemanticDBError as o}from"../../errors.js";const i=r=>{if(!r.hierarchy)return;const e=r.properties.find(({name:t})=>t===r.hierarchy?.property);if(!e)throw new o("HIERARCHY_PROPERTY_NOT_FOUND",`Schema hierarchy.property does not exist: ${r.hierarchy.property}`,{schemaId:r.id,property:r.hierarchy.property});return e};export{i as resolveHierarchyEntityFilterProperty};

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

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

package/dist/plugins/hierarchy/index.js

@@ -0,0 +1 @@
+import{normalizeLegacyHierarchy as r}from"./compatibility.js";import{resolveHierarchyEntityFilterProperty as e}from"./entity-identity.js";import{hierarchyLevelOperator as a}from"./operator.js";import{hierarchySchemaMetadata as t}from"./resolve-schema.js";const o=Object.freeze({name:"hierarchy",schemaMetadata:t,legacySchemaKeys:["hierarchy_property"],normalizeLegacySchema:r,resolveEntityFilterProperty:e,operators:[a]});export{o as hierarchyPlugin};

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

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

package/dist/plugins/hierarchy/operator.js

@@ -0,0 +1 @@
+import{SemanticDBError as i}from"../../errors.js";import{resolvePropertyPath as y}from"../../schema/resolve-property-path.js";const d=(n,t,o)=>{const e=y(n,t,o);if(e.property.primal_type!=="object")return{schema:e.schema,reference:e.canonicalName,relation:!1};if(e.property.isArray)throw new i("ARRAY_HIERARCHY_RELATION_UNSUPPORTED",`$hierarchyLevel cannot group an array relation: ${e.canonicalName}`);if(!e.property.ref||!o)throw new i("SCHEMA_RESOLVER_REQUIRED",`$hierarchyLevel requires a Schema resolver for relation ${e.canonicalName}`);return{schema:o(e.property.ref),reference:e.canonicalName,relation:!0}},f={name:"$hierarchyLevel",defaultName:({operandName:n,args:t,locale:o})=>{const e=typeof t.level=="string"?t.level:"";return o.toLowerCase().startsWith("en")?`${n}${e?` ${e}`:""} level`:`${n}${e}\u5C42\u7EA7`},kind:"scalar",planInput({reference:n,args:t,schema:o,resolveSchema:e}){const h=Object.keys(t).filter(a=>a!=="level");if(h.length>0||typeof t.level!="string"||t.level.length===0)throw new i("INVALID_HIERARCHY_LEVEL_ARGS","$hierarchyLevel args must contain exactly one non-empty level string",{unsupportedArgs:h});const r=d(o,n,e),c=r.schema.hierarchy;if(!c)throw new i("SCHEMA_HIERARCHY_REQUIRED",`Schema ${r.schema.id} does not declare hierarchy`,{schemaId:r.schema.id});const l=r.schema.properties.find(({name:a})=>a===c.property);if(!l)throw new i("HIERARCHY_PROPERTY_NOT_FOUND",`Schema hierarchy.property does not exist: ${c.property}`);if(!r.relation&&l.name!==y(o,n,e).property.name)throw new i("HIERARCHY_PROPERTY_REQUIRED",`$hierarchyLevel pred must be an object relation or hierarchy property ${l.name}`);let s=0;const p=c.levels.find(a=>(s+=a.codeLength,a.name===t.level||a.synonyms?.includes(t.level)));if(!p)throw new i("HIERARCHY_LEVEL_NOT_FOUND",`Schema ${r.schema.id} does not declare hierarchy level: ${t.level}`,{schemaId:r.schema.id,level:t.level});const R=c.levels.reduce((a,u)=>a+u.codeLength,0),m=r.schema.properties.filter(({type:a})=>a==="ID");return{reference:r.relation&&m.length===1&&m[0]?.name===l.name?r.reference:r.relation?`${r.reference}_${l.name}`:r.reference,args:{level:p.name,codeLength:s,totalLength:R,storage:c.storage}}},toSQL({expression:n,args:t,sql:o}){if(!n)throw new Error("$hierarchyLevel requires a hierarchy pred");const e=t.codeLength,h=t.totalLength,r=t.storage;if(!Number.isInteger(e)||!Number.isInteger(h)||Number(e)<=0||Number(h)<Number(e)||r!=="compact"&&r!=="zero-padded")throw new i("INVALID_HIERARCHY_LEVEL_PLAN","$hierarchyLevel must be resolved by the planner before SQL compilation");const c=o.substring(n,1,Number(e)),l=Number(h)-Number(e);return r==="zero-padded"&&l>0?o.concat([c,o.value("0".repeat(l))]):c},getOutputProperty({name:n}){return{name:n,type:"string",primal_type:"string",isArray:!1}}};export{f as hierarchyLevelOperator};

package/dist/plugins/hierarchy/resolve-schema.d.ts

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

package/dist/plugins/hierarchy/resolve-schema.js

@@ -0,0 +1 @@
+import{SemanticDBError as r}from"../../errors.js";const H={keys:["hierarchy"],resolve(m,R){if("hierarchy_property"in m)throw new r("LEGACY_HIERARCHY_PROPERTY_NOT_ALLOWED","Schema hierarchy must declare hierarchy.property instead of hierarchy_property");const s=m.hierarchy;if(s===void 0)return{};if(typeof s!="object"||s===null||Array.isArray(s))throw new r("INVALID_HIERARCHY","Schema hierarchy must be an object containing property, levels, and optional storage");const n=s,l=Object.keys(n).filter(o=>o!=="property"&&o!=="storage"&&o!=="levels");if(l.length>0)throw new r("UNSUPPORTED_HIERARCHY_FIELD","Schema hierarchy only supports property, storage, and levels",{unsupportedKeys:l});if(typeof n.property!="string"||n.property.length===0)throw new r("HIERARCHY_PROPERTY_REQUIRED","Schema hierarchy.property must be a non-empty property name or id");const a=R.find(o=>o.name===n.property||o.id===n.property);if(!a)throw new r("HIERARCHY_PROPERTY_NOT_FOUND",`Schema hierarchy.property does not exist: ${n.property}`,{property:n.property});if(a.primal_type!=="string")throw new r("INVALID_HIERARCHY_PROPERTY",`Hierarchy property ${a.name} must have primal_type string`,{property:a.name,primal_type:a.primal_type});const y=n.storage??"compact";if(y!=="compact"&&y!=="zero-padded")throw new r("INVALID_HIERARCHY_STORAGE","Schema hierarchy.storage must be compact or zero-padded");if(!Array.isArray(n.levels)||n.levels.length===0)throw new r("HIERARCHY_LEVELS_REQUIRED","Schema hierarchy.levels must be a non-empty array");const h=new Set,p=new Set,_=n.levels.map((o,i)=>{if(typeof o!="object"||o===null||Array.isArray(o))throw new r("INVALID_HIERARCHY_LEVEL",`Hierarchy level ${i} must be an object`);const e=o,E=Object.keys(e).filter(t=>t!=="name"&&t!=="synonyms"&&t!=="codeLength");if(E.length>0)throw new r("UNSUPPORTED_HIERARCHY_LEVEL_FIELD",`Hierarchy level ${i} only supports name, synonyms, and codeLength`,{unsupportedKeys:E});if(typeof e.name!="string"||e.name.length===0)throw new r("INVALID_HIERARCHY_LEVEL",`Hierarchy level ${i} name must not be empty`);if(h.has(e.name)||p.has(e.name))throw new r("DUPLICATE_HIERARCHY_LEVEL",`Duplicate hierarchy level name: ${e.name}`);if(!Number.isInteger(e.codeLength)||Number(e.codeLength)<=0)throw new r("INVALID_HIERARCHY_CODE_LENGTH",`Hierarchy level ${e.name} codeLength must be a positive integer`);if(e.synonyms!==void 0&&(!Array.isArray(e.synonyms)||e.synonyms.some(t=>typeof t!="string"||t.length===0)))throw new r("INVALID_HIERARCHY_SYNONYMS",`Hierarchy level ${e.name} synonyms must contain only non-empty strings`);const c=e.synonyms??[];for(const t of c){if(t===e.name||h.has(t)||p.has(t))throw new r("DUPLICATE_HIERARCHY_LEVEL",`Duplicate hierarchy level alias: ${t}`);p.add(t)}return h.add(e.name),{name:e.name,...c.length>0?{synonyms:[...c]}:{},codeLength:Number(e.codeLength)}});return{hierarchy:{property:a.name,storage:y,levels:_}}}};export{H as hierarchySchemaMetadata};

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

@@ -0,0 +1,28 @@
+export interface HierarchyLevelDefinition {
+    readonly name: string;
+    readonly synonyms?: readonly string[];
+    readonly codeLength: number;
+}
+export interface HierarchyDefinition {
+    /** Property that physically stores the complete hierarchy code. */
+    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[];
+}
+export interface ResolvedHierarchyDefinition extends Omit<HierarchyDefinition, 'storage'> {
+    /** Canonical logical property name. */
+    readonly property: string;
+    readonly storage: 'compact' | 'zero-padded';
+}
+declare module '../../semantic-types/types' {
+    interface SemanticSchemaMetadata {
+        readonly hierarchy?: HierarchyDefinition;
+    }
+    interface ResolvedSemanticSchemaMetadata {
+        readonly hierarchy?: ResolvedHierarchyDefinition;
+    }
+    interface LegacySemanticSchemaMetadata {
+        readonly hierarchy_property?: unknown;
+    }
+}

package/dist/plugins/index.d.ts

@@ -0,0 +1,5 @@
+import type { SemanticDBPlugin } from './types';
+export type { LegacySchemaPluginContext, SchemaMetadataPlugin, SemanticDBPlugin } from './types';
+/** 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[];

package/dist/plugins/index.js

@@ -0,0 +1 @@
+import{hierarchyPlugin as l}from"./hierarchy/index.js";import{SemanticDBError as n}from"../errors.js";const i=Object.freeze([l]),E=(m=[])=>{const t=[...i,...m],r=new Set,o=new Set,s=new Set;for(const e of t){if(!e.name)throw new n("INVALID_PLUGIN","Plugin name must not be empty");if(r.has(e.name))throw new n("PLUGIN_ALREADY_REGISTERED",`Plugin is already registered: ${e.name}`,{plugin:e.name});r.add(e.name);for(const a of[...e.schemaMetadata?.keys??[],...e.legacySchemaKeys??[]]){if(!a)throw new n("INVALID_PLUGIN_METADATA_KEY","Plugin metadata key must not be empty");if(o.has(a))throw new n("PLUGIN_METADATA_KEY_ALREADY_REGISTERED",`Plugin Schema metadata key is already registered: ${a}`,{key:a,plugin:e.name});o.add(a)}for(const a of e.operators??[]){if(s.has(a.name))throw new n("PLUGIN_OPERATOR_ALREADY_REGISTERED",`Plugin Operator is already registered: ${a.name}`,{operator:a.name,plugin:e.name});s.add(a.name)}}return Object.freeze(t)};export{i as builtinPlugins,E as resolvePlugins};

package/dist/plugins/types.d.ts

@@ -0,0 +1,20 @@
+import type { OperatorDefinition } from '../operators/types';
+import type { ResolvedSemanticProperty, ResolvedSemanticSchema, SemanticSchemaDraft } from '../semantic-types/types';
+export interface SchemaMetadataPlugin {
+    readonly keys: readonly string[];
+    readonly resolve: (schema: SemanticSchemaDraft, properties: readonly ResolvedSemanticProperty[]) => Readonly<Record<string, unknown>>;
+}
+export interface LegacySchemaPluginContext {
+    readonly source: Readonly<Record<string, unknown>>;
+    readonly properties: readonly SemanticSchemaDraft['properties'][number][];
+}
+export interface SemanticDBPlugin {
+    /** Stable name used for diagnostics and duplicate detection. */
+    readonly name: string;
+    readonly schemaMetadata?: SchemaMetadataPlugin;
+    /** 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[];
+}

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

@@ -0,0 +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 resolveEntityIdProperty: (schema: ResolvedSemanticSchema) => ResolvedSemanticProperty;
+export declare const resolveEntityFilterProperty: (schema: ResolvedSemanticSchema, plugins?: readonly SemanticDBPlugin[]) => ResolvedSemanticProperty;

package/dist/schema/entity-identity.js

@@ -0,0 +1 @@
+import{SemanticDBError as i}from"../errors.js";import{resolvePlugins as p}from"../plugins/index.js";const s=t=>typeof t=="string"&&t.length>0&&t!=="placeholder",n=t=>{const r=t.properties.filter(({type:e})=>e==="ID");if(r.length!==1)throw new i("ENTITY_ID_PROPERTY_REQUIRED",`Schema ${t.id} must contain exactly one ID property to use entity_id`,{schemaId:t.id,idPropertyCount:r.length});return r[0]},l=(t,r=[])=>{for(const e of p(r)){const o=e.resolveEntityFilterProperty?.(t);if(o)return o}return n(t)};export{s as isConcreteEntityId,l as resolveEntityFilterProperty,n as resolveEntityIdProperty};

package/dist/schema/index.d.ts

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

package/dist/schema/resolve-property-path.d.ts

@@ -0,0 +1,15 @@
+import type { ResolvedSemanticProperty, ResolvedSemanticSchema } from '../semantic-types/index';
+export type ResolvedSchemaLookup = (schemaId: string) => ResolvedSemanticSchema;
+export interface ResolvedRelationSegment {
+    readonly sourceSchema: ResolvedSemanticSchema;
+    readonly property: ResolvedSemanticProperty;
+    readonly targetSchema: ResolvedSemanticSchema;
+}
+export interface ResolvedPropertyPath {
+    readonly canonicalName: string;
+    readonly canonicalId: string;
+    readonly schema: ResolvedSemanticSchema;
+    readonly property: ResolvedSemanticProperty;
+    readonly relations: readonly ResolvedRelationSegment[];
+}
+export declare const resolvePropertyPath: (rootSchema: ResolvedSemanticSchema, reference: string, resolveSchema?: ResolvedSchemaLookup) => ResolvedPropertyPath;

package/dist/schema/resolve-property-path.js

@@ -0,0 +1 @@
+import{SemanticDBError as o}from"../errors.js";const p=(a,n)=>a.properties.some(i=>i!==n&&i.id===n.name)?n.id:n.name,l=(a,n)=>a.properties.flatMap(i=>[...n.startsWith(`${i.id}_`)?[{property:i,prefix:i.id}]:[],...i.name!==i.id&&n.startsWith(`${i.name}_`)?[{property:i,prefix:i.name}]:[]]).sort((i,s)=>s.prefix.length-i.prefix.length||(s.prefix===s.property.id?1:0)-(i.prefix===i.property.id?1:0)),c=(a,n,i)=>{const s=a.properties.find(t=>t.id===n)??a.properties.find(t=>t.name===n);if(s)return{canonicalName:p(a,s),canonicalId:s.id,schema:a,property:s,relations:[]};for(const{property:t,prefix:d}of l(a,n)){if(t.primal_type!=="object"||!t.ref)continue;if(!i)throw new o("SCHEMA_RESOLVER_REQUIRED",`Resolving property path ${n} requires a Schema resolver`);const e=i(t.ref),r=c(e,n.slice(d.length+1),i);return{canonicalName:`${p(a,t)}_${r.canonicalName}`,canonicalId:`${t.id}_${r.canonicalId}`,schema:r.schema,property:r.property,relations:[{sourceSchema:a,property:t,targetSchema:e},...r.relations]}}throw new o("PROPERTY_NOT_FOUND",`Property path not found in ${a.id}: ${n}`,{schemaId:a.id,property:n})};export{c as resolvePropertyPath};

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

@@ -0,0 +1,4 @@
+import type { ResolvedSemanticProperty, ResolvedSemanticSchema, SemanticSchemaDraft } from '../semantic-types/index';
+export declare const getSchema: (schemaId: string, schemas: Readonly<Record<string, SemanticSchemaDraft>>) => SemanticSchemaDraft;
+export declare const getProperty: (schema: ResolvedSemanticSchema, nameOrId: string) => ResolvedSemanticProperty;
+export declare const buildFieldMap: (schema: ResolvedSemanticSchema) => Readonly<Record<string, string>>;

package/dist/schema/schema-registry.js

@@ -0,0 +1 @@
+import{SemanticDBError as r}from"../errors.js";const o=(t,e)=>{const i=e[t];if(!i)throw new r("SCHEMA_NOT_FOUND",`Schema not found: ${t}`,{schemaId:t});if("_id"in i||"_sid"in i)throw new r("LEGACY_SCHEMA_ID_NOT_ALLOWED","Schema must use id instead of _id; _sid is not supported",{schemaId:t});if("sid"in i)throw new r("SCHEMA_SID_NOT_ALLOWED","Schema must not declare sid",{schemaId:t});if(i.id!==t)throw new r("SCHEMA_ID_MISMATCH",`Schema registry key ${t} does not match schema.id ${i.id}`,{registryKey:t,schemaId:i.id});return i},d=(t,e)=>{const i=t.properties.find(n=>n.id===e)??t.properties.find(n=>n.name===e);if(!i)throw new r("PROPERTY_NOT_FOUND",`Property not found in ${t.id}: ${e}`,{schemaId:t.id,property:e});return i},s=t=>{const e=t.properties.flatMap(i=>[[i.name,i.id],[i.id,i.id]]);return Object.freeze(Object.fromEntries(e))};export{s as buildFieldMap,d as getProperty,o as getSchema};

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

@@ -0,0 +1,7 @@
+import type { SchemaMappingDefinition } from './types';
+export declare const parseDailyExpireAt: (value: string) => {
+    readonly hour: number;
+    readonly minute: number;
+    readonly second: number;
+} | undefined;
+export declare const validateSourceFreshness: (definition: SchemaMappingDefinition) => void;

package/dist/schema-mappings/freshness.js

@@ -0,0 +1 @@
+import{SemanticDBError as n}from"../errors.js";const m=/^(\d{2}):(\d{2})(?::(\d{2}))?$/,o=t=>{const e=m.exec(t);if(!e)return;const r=Number(e[1]),s=Number(e[2]),i=Number(e[3]??0);if(!(r>23||s>59||i>59))return{hour:r,minute:s,second:i}},c=t=>{const e=t.freshness;if(e){if(e.mode==="ttl"){if(!Number.isInteger(e.ttlSeconds)||e.ttlSeconds<=0)throw new n("INVALID_SOURCE_FRESHNESS","TTL freshness requires a positive integer ttlSeconds");return}if(e.mode==="daily"){if(!o(e.expireAt))throw new n("INVALID_SOURCE_FRESHNESS","Daily freshness expireAt must use HH:mm or HH:mm:ss");if(e.timeZone)try{new Intl.DateTimeFormat("en-US",{timeZone:e.timeZone}).format()}catch{throw new n("INVALID_SOURCE_FRESHNESS",`Invalid freshness timeZone: ${e.timeZone}`)}}}};export{o as parseDailyExpireAt,c as validateSourceFreshness};

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

@@ -0,0 +1,4 @@
+export { SchemaMappingRegistry } from './registry';
+export { parseDailyExpireAt } from './freshness';
+export type { SchemaMappingDefinition, SourceFreshnessPolicy } from './types';
+export type { SchemaMappingPredDefinition, SchemaMappingPredMatch, } from './types';

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

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

package/dist/schema-mappings/registry.js

@@ -0,0 +1 @@
+import{SemanticDBError as s}from"../errors.js";import{validateSourceFreshness as m}from"./freshness.js";class o{#e=new Map;constructor(e=[]){for(const r of e)this.register(r)}register(e){if(!e.schemaId)throw new s("INVALID_SCHEMA_MAPPING","Schema mapping schemaId must not be empty");if(!e.source)throw new s("INVALID_SCHEMA_MAPPING","Schema mapping source must not be empty");if(e.sourceSql!==void 0&&e.sourceSql.trim().length===0)throw new s("INVALID_SCHEMA_MAPPING","Schema mapping sourceSql must not be empty");if(e.id!==void 0&&!e.id)throw new s("INVALID_SCHEMA_MAPPING","Schema mapping id must not be empty");if(e.connectionId.trim().length===0)throw new s("INVALID_SCHEMA_MAPPING","Schema mapping connectionId must not be empty");if(e.priority!==void 0&&!Number.isFinite(e.priority))throw new s("INVALID_SCHEMA_MAPPING","Schema mapping priority must be finite");for(const t of e.predMappings??[])if(!t.match.operator||!t.match.pred||!t.column)throw new s("INVALID_SCHEMA_MAPPING","Schema mapping PredItem matches require operator, pred, and column");m(e);const r=this.#e.get(e.schemaId)??[],p=e.id??e.source;if(r.some(t=>(t.id??t.source)===p||t.source===e.source))throw new s("SCHEMA_MAPPING_ALREADY_REGISTERED",`Schema mapping is already registered: ${e.schemaId}:${p}`,{schemaId:e.schemaId,mappingId:p});return this.#e.set(e.schemaId,[...r,e]),this}get(e){const r=this.list(e);if(r.length===1)return r[0];const p=r.filter(t=>t.predMappings===void 0&&t.properties===void 0);if(p.length===1)return p[0];throw new s("SCHEMA_MAPPING_AMBIGUOUS",`Schema ${e} has multiple mappings and requires LogicForm-based selection`,{schemaId:e,mappingIds:r.map(t=>t.id??t.source)})}list(e){const r=this.#e.get(e);if(!r||r.length===0)throw new s("SCHEMA_MAPPING_NOT_FOUND",`Schema mapping is not registered: ${e}`,{schemaId:e});return r}findSource(e,r){return this.#e.get(e)?.find(p=>p.source===r)}}export{o as SchemaMappingRegistry};

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

@@ -0,0 +1,46 @@
+import type { QueryType } from '../logicform-types';
+export type SourceFreshnessPolicy = {
+    readonly mode: 'ttl';
+    readonly ttlSeconds: number;
+} | {
+    readonly mode: 'daily';
+    readonly expireAt: string;
+    readonly timeZone?: string;
+} | {
+    readonly mode: 'manual';
+};
+export interface SchemaMappingPredMatch {
+    /** Defaults to the owning mapping's Schema. */
+    readonly schema?: string;
+    readonly operator: string;
+    readonly pred: string;
+    /** Required conjunctive conditions across the LogicForm and PredItem queries. */
+    readonly query?: QueryType;
+}
+export interface SchemaMappingPredDefinition {
+    readonly match: SchemaMappingPredMatch;
+    /** Physical column used as the matched PredItem's operator input. */
+    readonly column: string;
+}
+export interface SchemaMappingDefinition {
+    /** Stable identity when a Schema has multiple physical mappings. */
+    readonly id?: string;
+    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;
+    /**
+     * 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[];
+    /** 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;
+}

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

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

package/dist/semantic-types/builtins/boolean.js

@@ -0,0 +1 @@
+const o={name:"boolean",primalType:"boolean",hydrateResult(e){return typeof e=="number"?e===1:e}};export{o as booleanSemanticType};

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

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

package/dist/semantic-types/builtins/category.js

@@ -0,0 +1 @@
+const e={name:"category",primalType:"string"};export{e as categorySemanticType};

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

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

package/dist/semantic-types/builtins/currency.js

@@ -0,0 +1 @@
+const e={name:"currency",primalType:"number"};export{e as currencySemanticType};

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

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

package/dist/semantic-types/builtins/date.js

@@ -0,0 +1 @@
+const e={name:"date",primalType:"date"};export{e as dateSemanticType};

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

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

package/dist/semantic-types/builtins/duration.js

@@ -0,0 +1 @@
+const e={name:"duration",primalType:"number"};export{e as durationSemanticType};

package/dist/semantic-types/builtins/end-date.d.ts

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

package/dist/semantic-types/builtins/end-date.js

@@ -0,0 +1 @@
+const e={name:"end_date",primalType:"date"};export{e as endDateSemanticType};

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

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

package/dist/semantic-types/builtins/entity.js

@@ -0,0 +1 @@
+import{hydrateObjectResult as t}from"./object.js";const e={name:"entity",primalType:"object",hydrateResult:t};export{e as entitySemanticType};

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

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

package/dist/semantic-types/builtins/file.js

@@ -0,0 +1 @@
+const e={name:"file",primalType:"string"};export{e as fileSemanticType};

package/dist/semantic-types/builtins/human-name.d.ts

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

package/dist/semantic-types/builtins/human-name.js

@@ -0,0 +1 @@
+const a={name:"humanName",primalType:"string"};export{a as humanNameSemanticType};

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

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

package/dist/semantic-types/builtins/id.js

@@ -0,0 +1 @@
+const e={name:"ID",primalType:"string"};export{e as idSemanticType};

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

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

package/dist/semantic-types/builtins/image.js

@@ -0,0 +1 @@
+const e={name:"image",primalType:"string"};export{e as imageSemanticType};

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

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

package/dist/semantic-types/builtins/index.js

@@ -0,0 +1 @@
+import{booleanSemanticType as m}from"./boolean.js";import{categorySemanticType as e}from"./category.js";import{currencySemanticType as t}from"./currency.js";import{dateSemanticType as r}from"./date.js";import{durationSemanticType as i}from"./duration.js";import{endDateSemanticType as o}from"./end-date.js";import{entitySemanticType as p}from"./entity.js";import{fileSemanticType as a}from"./file.js";import{humanNameSemanticType as n}from"./human-name.js";import{idSemanticType as c}from"./id.js";import{imageSemanticType as y}from"./image.js";import{intSemanticType as f}from"./int.js";import{nameSemanticType as S}from"./name.js";import{numberSemanticType as T}from"./number.js";import{objectSemanticType as b}from"./object.js";import{orderSemanticType as d}from"./order.js";import{percentageSemanticType as s}from"./percentage.js";import{startDateSemanticType as u}from"./start-date.js";import{stringSemanticType as g}from"./string.js";import{timestampSemanticType as l}from"./timestamp.js";const j=Object.freeze([c,g,S,n,e,y,a,T,f,t,s,i,d,m,l,r,u,o,p,b]);export{j as builtinSemanticTypes};

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

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

package/dist/semantic-types/builtins/int.js

@@ -0,0 +1 @@
+const e={name:"int",primalType:"number"};export{e as intSemanticType};

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

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

package/dist/semantic-types/builtins/name.js

@@ -0,0 +1 @@
+const e={name:"name",primalType:"string"};export{e as nameSemanticType};

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

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

package/dist/semantic-types/builtins/number.js

@@ -0,0 +1 @@
+const e={name:"number",primalType:"number"};export{e as numberSemanticType};

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

@@ -0,0 +1,3 @@
+import type { SemanticTypeDefinition } from '../types';
+export declare const hydrateObjectResult: NonNullable<SemanticTypeDefinition['hydrateResult']>;
+export declare const objectSemanticType: SemanticTypeDefinition;