semanticdb-v2 2.0.0-alpha.1

package/dist/physical/connection.d.ts

@@ -0,0 +1,32 @@
+import type { CoreComputeProvider } from './provider';
+import type { ClickHouseProviderOptions } from './clickhouse-provider';
+import type { DorisProviderOptions } from './doris-provider';
+import type { MySQLProviderOptions } from './mysql-provider';
+import type { OracleProviderOptions } from './oracle-provider';
+import type { PostgreSQLProviderOptions } from './postgresql-provider';
+import type { SnowflakeProviderOptions } from './snowflake-provider';
+import type { StarRocksProviderOptions } from './starrocks-provider';
+/** Connection information supplied by an application. Provider instances stay internal. */
+export type DatabaseConnection = ({
+    readonly id: string;
+    readonly kind: 'mysql';
+} & NonNullable<MySQLProviderOptions['connection']>) | ({
+    readonly id: string;
+    readonly kind: 'doris';
+} & NonNullable<DorisProviderOptions['connection']>) | ({
+    readonly id: string;
+    readonly kind: 'starrocks';
+} & NonNullable<StarRocksProviderOptions['connection']>) | ({
+    readonly id: string;
+    readonly kind: 'postgresql';
+} & NonNullable<PostgreSQLProviderOptions['connection']>) | ({
+    readonly id: string;
+    readonly kind: 'clickhouse';
+} & Omit<ClickHouseProviderOptions, 'client'>) | ({
+    readonly id: string;
+    readonly kind: 'snowflake';
+} & NonNullable<SnowflakeProviderOptions['connection']>) | ({
+    readonly id: string;
+    readonly kind: 'oracle';
+} & NonNullable<OracleProviderOptions['connection']>);
+export declare const createProvider: (connection: DatabaseConnection) => CoreComputeProvider;

package/dist/physical/connection.js

@@ -0,0 +1 @@
+import{ClickHouseProvider as n}from"./clickhouse-provider.js";import{DorisProvider as s}from"./doris-provider.js";import{MySQLProvider as t}from"./mysql-provider.js";import{OracleProvider as d}from"./oracle-provider.js";import{PostgreSQLProvider as c}from"./postgresql-provider.js";import{SnowflakeProvider as p}from"./snowflake-provider.js";import{StarRocksProvider as m}from"./starrocks-provider.js";const a=o=>{switch(o.kind){case"mysql":{const{id:i,kind:e,...r}=o;return new t({connection:r})}case"doris":{const{id:i,kind:e,...r}=o;return new s({connection:r})}case"starrocks":{const{id:i,kind:e,...r}=o;return new m({connection:r})}case"postgresql":{const{id:i,kind:e,...r}=o;return new c({connection:r})}case"clickhouse":{const{id:i,kind:e,...r}=o;return new n(r)}case"snowflake":{const{id:i,kind:e,...r}=o;return new p({connection:r})}case"oracle":{const{id:i,kind:e,...r}=o;return new d({connection:r})}}};export{a as createProvider};

package/dist/physical/display-query.d.ts

@@ -0,0 +1,4 @@
+export declare const displayClickHouseQuery: (sql: string, parameters: readonly unknown[]) => string;
+export declare const displayOracleQuery: (sql: string, parameters: readonly unknown[]) => string;
+export declare const displayPostgreSQLQuery: (sql: string, parameters: readonly unknown[]) => string;
+export declare const displayQuestionMarkQuery: (sql: string, parameters: readonly unknown[]) => string;

package/dist/physical/display-query.js

@@ -0,0 +1 @@
+const u=e=>`'${e.replaceAll("'","''")}'`,f=(e,r)=>{if(e==null)return"NULL";if(typeof e=="boolean")return e?"TRUE":"FALSE";if(typeof e=="number")return String(e);if(typeof e=="bigint")return u(e.toString());if(typeof e=="string")return u(e);if(e instanceof Date){const n=r==="clickhouse"?e.toISOString().replace("T"," ").replace("Z",""):e.toISOString();return u(n)}if(Buffer.isBuffer(e)){const n=e.toString("hex");return r==="oracle"?`HEXTORAW('${n}')`:r==="postgresql"?`decode('${n}', 'hex')`:r==="snowflake"?`TO_BINARY('${n}', 'HEX')`:`unhex('${n}')`}throw new TypeError(`Unsupported ${r} display parameter type: ${typeof e}`)},d=(e,r)=>e.replace(/\{p(\d+):[^}]+\}/g,(n,o)=>{const t=Number(o);return t in r?f(r[t],"clickhouse"):n}),l=(e,r)=>e.replace(/:([1-9]\d*)\b/g,(n,o)=>{const t=Number(o)-1;return t in r?f(r[t],"oracle"):n}),g=(e,r)=>{let n="",o;for(let t=0;t<e.length;t+=1){const i=e[t];if(i){if(o){n+=i,i===o&&(e[t+1]===o?(n+=o,t+=1):o=void 0);continue}if(i==="'"||i==='"'){o=i,n+=i;continue}if(i==="$"){const c=/^\$(\d+)/.exec(e.slice(t)),s=c?.[1];if(c&&s){const p=Number(s)-1;if(p in r){n+=f(r[p],"postgresql"),t+=c[0].length-1;continue}}}n+=i}}return n},y=(e,r)=>{let n="",o=0,t;for(let i=0;i<e.length;i+=1){const c=e[i];if(c){if(t){n+=c,c===t&&(e[i+1]===t?(n+=t,i+=1):t=void 0);continue}if(c==="'"||c==='"'||c==="`"){t=c,n+=c;continue}if(c==="?"&&o<r.length){n+=f(r[o],"snowflake"),o+=1;continue}n+=c}}return n};export{d as displayClickHouseQuery,l as displayOracleQuery,g as displayPostgreSQLQuery,y as displayQuestionMarkQuery};

package/dist/physical/doris-provider.d.ts

@@ -0,0 +1,9 @@
+import { MySQLProtocolProvider } from './mysql-protocol-provider';
+import type { MySQLProtocolPoolLike, MySQLProtocolProviderOptions } from './mysql-protocol-provider';
+export type DorisPoolLike = MySQLProtocolPoolLike;
+export type DorisProviderOptions = MySQLProtocolProviderOptions;
+/** Doris adapter using its MySQL-compatible protocol and SQL surface. */
+export declare class DorisProvider extends MySQLProtocolProvider {
+    readonly kind: "doris";
+    constructor(options?: DorisProviderOptions);
+}

package/dist/physical/doris-provider.js

@@ -0,0 +1 @@
+import{MySQLProtocolProvider as o}from"./mysql-protocol-provider.js";class s extends o{kind="doris";constructor(r={}){super(r)}}export{s as DorisProvider};

package/dist/physical/index.d.ts

@@ -0,0 +1,18 @@
+/** Internal physical adapters selected from the public database connection configuration. */
+export type { CoreComputeProvider, DataRow, ProviderExecutionRequest, SqlRenderCapabilities, SqlParameters, } from './provider';
+export { createProvider } from './connection';
+export type { DatabaseConnection } from './connection';
+export { ClickHouseProvider, } from './clickhouse-provider';
+export type { ClickHouseClientLike, ClickHouseProviderOptions, } from './clickhouse-provider';
+export { DorisProvider } from './doris-provider';
+export type { DorisPoolLike, DorisProviderOptions } from './doris-provider';
+export { MySQLProvider } from './mysql-provider';
+export type { MySQLPoolLike, MySQLProviderOptions } from './mysql-provider';
+export { OracleProvider } from './oracle-provider';
+export type { OracleConnectionLike, OracleDriverLike, OraclePoolLike, OracleProviderOptions, } from './oracle-provider';
+export { PostgreSQLProvider } from './postgresql-provider';
+export type { PostgreSQLPoolLike, PostgreSQLProviderOptions, } from './postgresql-provider';
+export { SnowflakeProvider } from './snowflake-provider';
+export type { SnowflakeConnectionLike, SnowflakeProviderOptions, SnowflakeStatementLike, } from './snowflake-provider';
+export { StarRocksProvider } from './starrocks-provider';
+export type { StarRocksPoolLike, StarRocksProviderOptions, } from './starrocks-provider';

package/dist/physical/mysql-compatible-sql.d.ts

@@ -0,0 +1,6 @@
+import type { SqlParameters, SqlRenderCapabilities } from './provider';
+export interface MySQLCompatibleSqlCapabilities extends SqlRenderCapabilities {
+    parameter(index: number, value: unknown): string;
+    displayQuery(sql: string, parameters: SqlParameters): string;
+}
+export declare const mysqlCompatibleSql: MySQLCompatibleSqlCapabilities;

package/dist/physical/mysql-compatible-sql.js

@@ -0,0 +1 @@
+import u from"mysql2";const o={quoteIdentifier(r){return`\`${r.replaceAll("`","``")}\``},tableAlias(r,t){return`${r} AS ${this.quoteIdentifier(t)}`},paginate(r,t,e){return`${r} LIMIT ${t}${e>0?` OFFSET ${e}`:""}`},parameter(r,t){return"?"},displayQuery(r,t){return u.format(r,[...t])},dateBucket(r,t){const e={hour:"%Y-%m-%d %H:00:00",day:"%Y-%m-%d",month:"%Y-%m-01",year:"%Y-01-01"};if(t==="week")return`DATE_SUB(DATE(${r}), INTERVAL WEEKDAY(${r}) DAY)`;if(t==="quarter")return`MAKEDATE(YEAR(${r}), 1) + INTERVAL (QUARTER(${r}) - 1) QUARTER`;const n=e[t];if(!n)throw new Error(`Unsupported MySQL-compatible date level: ${t}`);return`DATE_FORMAT(${r}, '${n}')`},dateShift(r,t,e){if(!new Set(["second","minute","hour","day","week","month","quarter","year"]).has(t)||!Number.isInteger(e))throw new Error(`Unsupported MySQL-compatible date shift: ${t}/${e}`);return`DATE_ADD(${r}, INTERVAL ${e} ${t.toUpperCase()})`},aggregateFunction(r,t="*"){if(!/^[A-Za-z][A-Za-z0-9_]*$/.test(r))throw new Error(`Unsupported MySQL-compatible aggregate function: ${r}`);return`${r.toUpperCase()}(${t})`},concat(r){return`CONCAT(${r.join(", ")})`},substring(r,t,e){return`SUBSTRING(${r}, ${t}, ${e})`},regex(r,t,e){if(e&&e!=="i")throw new Error(`Unsupported MySQL-compatible regex options: ${e}`);return e==="i"?`LOWER(${r}) REGEXP LOWER(${t})`:`${r} REGEXP ${t}`},arrayContains(r,t){return`JSON_OVERLAPS(${r}, JSON_ARRAY(${t}))`},expandArray(r,t,e){const n=this.quoteIdentifier(t),$=this.quoteIdentifier(e);return{joinSql:`CROSS JOIN JSON_TABLE(CASE WHEN JSON_TYPE(${r}) = 'ARRAY' THEN ${r} ELSE JSON_ARRAY() END, '$[*]' COLUMNS (${$} JSON PATH '$')) AS ${n}`,valueExpression:`${n}.${$}`}}};export{o as mysqlCompatibleSql};

package/dist/physical/mysql-protocol-provider.d.ts

@@ -0,0 +1,34 @@
+import type { PoolOptions } from 'mysql2/promise';
+import type { CoreComputeProvider, DataRow, ProviderExecutionRequest, SqlParameters } from './provider';
+export interface MySQLProtocolPoolLike {
+    execute(sql: string, values: readonly unknown[]): Promise<readonly [unknown, unknown]>;
+    end(): Promise<void>;
+}
+export interface MySQLProtocolProviderOptions {
+    readonly connection?: PoolOptions;
+    readonly pool?: MySQLProtocolPoolLike;
+}
+export declare abstract class MySQLProtocolProvider implements CoreComputeProvider {
+    readonly supportsRecursiveCte = true;
+    abstract readonly kind: 'doris' | 'mysql' | 'starrocks';
+    private readonly pool;
+    protected constructor(options?: MySQLProtocolProviderOptions);
+    quoteIdentifier(identifier: string): string;
+    tableAlias(expression: string, alias: string): string;
+    paginate(sql: string, pageSize: number, offset: number): string;
+    parameter(index: number, value: unknown): string;
+    displayQuery(sql: string, parameters: SqlParameters): string;
+    dateBucket(expression: string, level: string): string;
+    dateShift(expression: string, granularity: string, offset: number): string;
+    aggregateFunction(name: string, expression?: string): string;
+    concat(expressions: readonly string[]): string;
+    substring(expression: string, start: number, length: number): string;
+    regex(expression: string, pattern: string, options?: string): string;
+    arrayContains(arrayExpression: string, valueExpression: string): string;
+    expandArray(arrayExpression: string, alias: string, column: string): {
+        readonly joinSql: string;
+        readonly valueExpression: string;
+    };
+    execute(request: ProviderExecutionRequest): Promise<DataRow[]>;
+    close(): Promise<void>;
+}

package/dist/physical/mysql-protocol-provider.js

@@ -0,0 +1 @@
+import{createPool as o}from"mysql2/promise";import{mysqlCompatibleSql as t}from"./mysql-compatible-sql.js";class i{supportsRecursiveCte=!0;pool;constructor(r={}){this.pool=r.pool??o(r.connection??{})}quoteIdentifier(r){return t.quoteIdentifier(r)}tableAlias(r,e){return t.tableAlias(r,e)}paginate(r,e,a){return t.paginate(r,e,a)}parameter(r,e){return t.parameter(r,e)}displayQuery(r,e){return t.displayQuery(r,e)}dateBucket(r,e){return t.dateBucket(r,e)}dateShift(r,e,a){return t.dateShift(r,e,a)}aggregateFunction(r,e){return t.aggregateFunction(r,e)}concat(r){return t.concat(r)}substring(r,e,a){return t.substring(r,e,a)}regex(r,e,a){return t.regex(r,e,a)}arrayContains(r,e){const a=t.arrayContains?.bind(t);if(!a)throw new Error("MySQL-compatible array conditions are unavailable");return a(r,e)}expandArray(r,e,a){const n=t.expandArray?.bind(t);if(!n)throw new Error("MySQL-compatible array expansion is unavailable");return n(r,e,a)}async execute(r){r.signal?.throwIfAborted();const[e]=await this.pool.execute(r.sql,r.parameters);if(!Array.isArray(e))throw new Error(`${this.kind} provider expected an array result`);return e}async close(){await this.pool.end()}}export{i as MySQLProtocolProvider};

package/dist/physical/mysql-provider.d.ts

@@ -0,0 +1,8 @@
+import { MySQLProtocolProvider } from './mysql-protocol-provider';
+import type { MySQLProtocolPoolLike, MySQLProtocolProviderOptions } from './mysql-protocol-provider';
+export type MySQLPoolLike = MySQLProtocolPoolLike;
+export type MySQLProviderOptions = MySQLProtocolProviderOptions;
+export declare class MySQLProvider extends MySQLProtocolProvider {
+    readonly kind: "mysql";
+    constructor(options?: MySQLProviderOptions);
+}

package/dist/physical/mysql-provider.js

@@ -0,0 +1 @@
+import{MySQLProtocolProvider as o}from"./mysql-protocol-provider.js";class e extends o{kind="mysql";constructor(r={}){super(r)}}export{e as MySQLProvider};

package/dist/physical/oracle-provider.d.ts

@@ -0,0 +1,53 @@
+import type { PoolAttributes } from 'oracledb';
+import type { CoreComputeProvider, DataRow, ProviderExecutionRequest } from './provider';
+type OracleBind = string | number | boolean | Date | Buffer | null;
+export interface OracleConnectionLike {
+    execute(sql: string, binds: OracleBind[], options: {
+        readonly outFormat: number;
+    }): Promise<{
+        readonly rows?: unknown[] | undefined;
+    }>;
+    break(): Promise<void>;
+    close(): Promise<void>;
+}
+export interface OraclePoolLike {
+    getConnection(): Promise<OracleConnectionLike>;
+    close(drainTime?: number): Promise<void>;
+}
+export interface OracleDriverLike {
+    createPool(options: PoolAttributes): Promise<OraclePoolLike>;
+}
+export interface OracleProviderOptions {
+    /** Passed to oracledb.createPool(). Thin mode is used unless the caller initialized Thick mode. */
+    readonly connection?: PoolAttributes;
+    /** Injectable pool for applications that own pool creation or for tests. */
+    readonly pool?: OraclePoolLike;
+    /** Injectable driver factory used to test lazy pool creation. */
+    readonly driver?: OracleDriverLike;
+}
+export declare class OracleProvider implements CoreComputeProvider {
+    #private;
+    readonly kind: "oracle";
+    readonly supportsHavingAlias = false;
+    readonly maxInListItems = 1000;
+    constructor(options?: OracleProviderOptions);
+    quoteIdentifier(identifier: string): string;
+    tableAlias(expression: string, alias: string): string;
+    paginate(sql: string, pageSize: number, offset: number): string;
+    parameter(index: number, value: unknown): string;
+    displayQuery(sql: string, parameters: readonly unknown[]): string;
+    dateBucket(expression: string, level: string): string;
+    dateShift(expression: string, granularity: string, offset: number): string;
+    aggregateFunction(name: string, expression?: string): string;
+    concat(expressions: readonly string[]): string;
+    substring(expression: string, start: number, length: number): string;
+    regex(expression: string, pattern: string, options?: string): string;
+    arrayContains(arrayExpression: string, valueExpression: string): string;
+    expandArray(arrayExpression: string, alias: string, column: string): {
+        joinSql: string;
+        valueExpression: string;
+    };
+    execute(request: ProviderExecutionRequest): Promise<DataRow[]>;
+    close(): Promise<void>;
+}
+export {};

package/dist/physical/oracle-provider.js

@@ -0,0 +1 @@
+import c from"oracledb";import{displayOracleQuery as l}from"./display-query.js";const u=o=>{if(o==null)return null;if(typeof o=="bigint")return o.toString();if(typeof o=="string"||typeof o=="number"||typeof o=="boolean"||o instanceof Date||Buffer.isBuffer(o))return o;throw new TypeError(`Unsupported Oracle parameter type: ${typeof o}`)},d=o=>o.reason instanceof Error?o.reason:new DOMException("The operation was aborted","AbortError");class p{kind="oracle";supportsHavingAlias=!1;maxInListItems=1e3;#t;#e;#r;constructor(r={}){this.#t=r.connection??{},this.#e=r.driver??{createPool:t=>c.createPool(t)},this.#r=r.pool?Promise.resolve(r.pool):void 0}quoteIdentifier(r){return`"${r.replaceAll('"','""')}"`}tableAlias(r,t){return`${r} ${this.quoteIdentifier(t)}`}paginate(r,t,e){return e>0?`${r} OFFSET ${e} ROWS FETCH NEXT ${t} ROWS ONLY`:`${r} FETCH FIRST ${t} ROWS ONLY`}parameter(r,t){return`:${r+1}`}displayQuery(r,t){return l(r,t.map(u))}dateBucket(r,t){const e={hour:"HH24",day:void 0,week:"IW",month:"MM",quarter:"Q",year:"YYYY"};if(!(t in e))throw new Error(`Unsupported Oracle date level: ${t}`);const n=e[t];return n?`TRUNC(${r}, '${n}')`:`TRUNC(${r})`}dateShift(r,t,e){if(!Number.isInteger(e))throw new Error(`Unsupported Oracle date shift: ${t}/${e}`);const i={month:1,quarter:3,year:12}[t];if(i)return`ADD_MONTHS(${r}, ${e*i})`;const s={second:{unit:"SECOND",multiplier:1},minute:{unit:"MINUTE",multiplier:1},hour:{unit:"HOUR",multiplier:1},day:{unit:"DAY",multiplier:1},week:{unit:"DAY",multiplier:7}}[t];if(!s)throw new Error(`Unsupported Oracle date shift: ${t}/${e}`);return`(${r} + NUMTODSINTERVAL(${e*s.multiplier}, '${s.unit}'))`}aggregateFunction(r,t="*"){if(!/^[A-Za-z][A-Za-z0-9_]*$/.test(r))throw new Error(`Unsupported Oracle aggregate function: ${r}`);return`${r.toUpperCase()}(${t})`}concat(r){return`(${r.join(" || ")})`}substring(r,t,e){return`SUBSTR(${r}, ${t}, ${e})`}regex(r,t,e){if(e&&e!=="i")throw new Error(`Unsupported Oracle regex options: ${e}`);return`REGEXP_LIKE(${r}, ${t}${e?", 'i'":""})`}arrayContains(r,t){return`JSON_EXISTS(${r}, '$?(@ == $value)' PASSING ${t} AS "value")`}expandArray(r,t,e){const n=this.quoteIdentifier(t),i=this.quoteIdentifier(e);return{joinSql:`CROSS APPLY JSON_TABLE(${r}, '$[*]' COLUMNS (${i} VARCHAR2(4000) PATH '$')) ${n}`,valueExpression:`${n}.${i}`}}async#o(){this.#r??=this.#e.createPool(this.#t);try{return await this.#r}catch(r){throw this.#r=void 0,r}}async execute(r){r.signal?.throwIfAborted();const t=await this.#o();r.signal?.throwIfAborted();const e=await t.getConnection(),n=r.signal,i=()=>{e.break().catch(()=>{})};n?.addEventListener("abort",i,{once:!0});try{const a=await e.execute(r.sql,r.parameters.map(u),{outFormat:c.OUT_FORMAT_OBJECT});if(n?.throwIfAborted(),!Array.isArray(a.rows))throw new Error("Oracle provider expected an array result");return a.rows}catch(a){throw n?.aborted?d(n):a}finally{n?.removeEventListener("abort",i),await e.close()}}async close(){const r=this.#r;if(!r)return;await(await r).close(0),this.#r=void 0}}export{p as OracleProvider};

package/dist/physical/postgresql-provider.d.ts

@@ -0,0 +1,37 @@
+import type { PoolConfig } from 'pg';
+import type { CoreComputeProvider, DataRow, ProviderExecutionRequest } from './provider';
+export interface PostgreSQLPoolLike {
+    query(sql: string, values: unknown[]): Promise<{
+        readonly rows: unknown;
+    }>;
+    end(): Promise<void>;
+}
+export interface PostgreSQLProviderOptions {
+    readonly connection?: PoolConfig;
+    readonly pool?: PostgreSQLPoolLike;
+}
+export declare class PostgreSQLProvider implements CoreComputeProvider {
+    readonly kind: "postgresql";
+    readonly supportsHavingAlias = false;
+    readonly supportsRecursiveCte = true;
+    private readonly pool;
+    constructor(options?: PostgreSQLProviderOptions);
+    quoteIdentifier(identifier: string): string;
+    tableAlias(expression: string, alias: string): string;
+    paginate(sql: string, pageSize: number, offset: number): string;
+    parameter(index: number, value: unknown): string;
+    displayQuery(sql: string, parameters: readonly unknown[]): string;
+    dateBucket(expression: string, level: string): string;
+    dateShift(expression: string, granularity: string, offset: number): string;
+    aggregateFunction(name: string, expression?: string): string;
+    concat(expressions: readonly string[]): string;
+    substring(expression: string, start: number, length: number): string;
+    regex(expression: string, pattern: string, options?: string): string;
+    arrayContains(arrayExpression: string, valueExpression: string): string;
+    expandArray(arrayExpression: string, alias: string, column: string): {
+        joinSql: string;
+        valueExpression: string;
+    };
+    execute(request: ProviderExecutionRequest): Promise<DataRow[]>;
+    close(): Promise<void>;
+}

package/dist/physical/postgresql-provider.js

@@ -0,0 +1 @@
+import{Pool as s}from"pg";import{displayPostgreSQLQuery as a}from"./display-query.js";class i{kind="postgresql";supportsHavingAlias=!1;supportsRecursiveCte=!0;pool;constructor(r={}){this.pool=r.pool??new s(r.connection)}quoteIdentifier(r){return`"${r.replaceAll('"','""')}"`}tableAlias(r,e){return`${r} AS ${this.quoteIdentifier(e)}`}paginate(r,e,t){return`${r} LIMIT ${e}${t>0?` OFFSET ${t}`:""}`}parameter(r,e){return`$${r+1}`}displayQuery(r,e){return a(r,e)}dateBucket(r,e){if(!new Set(["hour","day","week","month","quarter","year"]).has(e))throw new Error(`Unsupported PostgreSQL date level: ${e}`);return`DATE_TRUNC('${e}', ${r})`}dateShift(r,e,t){if(!new Set(["second","minute","hour","day","week","month","quarter","year"]).has(e)||!Number.isInteger(t))throw new Error(`Unsupported PostgreSQL date shift: ${e}/${t}`);return`(${r} + (${t} * INTERVAL '1 ${e}'))`}aggregateFunction(r,e="*"){if(!/^[A-Za-z][A-Za-z0-9_]*$/.test(r))throw new Error(`Unsupported PostgreSQL aggregate function: ${r}`);return`${r.toUpperCase()}(${e})`}concat(r){return`CONCAT(${r.join(", ")})`}substring(r,e,t){return`SUBSTRING(${r} FROM ${e} FOR ${t})`}regex(r,e,t){if(t&&t!=="i")throw new Error(`Unsupported PostgreSQL regex options: ${t}`);return`${r} ${t==="i"?"~*":"~"} ${e}`}arrayContains(r,e){return`${e} = ANY(${r})`}expandArray(r,e,t){const o=this.quoteIdentifier(e),n=this.quoteIdentifier(t);return{joinSql:`CROSS JOIN LATERAL unnest(${r}) AS ${o}(${n})`,valueExpression:`${o}.${n}`}}async execute(r){r.signal?.throwIfAborted();const e=await this.pool.query(r.sql,[...r.parameters]);if(r.signal?.throwIfAborted(),!Array.isArray(e.rows))throw new Error("PostgreSQL provider expected an array result");return e.rows}async close(){await this.pool.end()}}export{i as PostgreSQLProvider};

package/dist/physical/provider.d.ts

@@ -0,0 +1,40 @@
+export type DataRow = Record<string, unknown>;
+export type SqlParameters = readonly unknown[];
+export interface ProviderExecutionRequest {
+    readonly sql: string;
+    readonly parameters: SqlParameters;
+    readonly signal?: AbortSignal;
+}
+export interface SqlRenderCapabilities {
+    /** Whether HAVING may reference an alias declared in the same SELECT list. */
+    readonly supportsHavingAlias?: boolean;
+    quoteIdentifier(identifier: string): string;
+    tableAlias(expression: string, alias: string): string;
+    paginate(sql: string, pageSize: number, offset: number): string;
+    dateBucket(expression: string, level: string): string;
+    dateShift(expression: string, granularity: string, offset: number): string;
+    aggregateFunction(name: string, expression?: string): string;
+    concat(expressions: readonly string[]): string;
+    substring(expression: string, start: number, length: number): string;
+    regex(expression: string, pattern: string, options?: string): string;
+    /** Whether the dialect supports a WITH RECURSIVE subquery. */
+    readonly supportsRecursiveCte?: boolean;
+    arrayContains?(arrayExpression: string, valueExpression: string): string;
+    expandArray?(arrayExpression: string, alias: string, column: string): {
+        readonly joinSql: string;
+        readonly valueExpression: string;
+    };
+}
+/**
+ * Internal physical database contract used by the compiler and executor.
+ */
+export interface CoreComputeProvider extends SqlRenderCapabilities {
+    readonly kind: 'clickhouse' | 'doris' | 'mysql' | 'oracle' | 'postgresql' | 'snowflake' | 'starrocks';
+    /** Maximum items accepted by one SQL IN expression, when the dialect has a limit. */
+    readonly maxInListItems?: number;
+    parameter(index: number, value: unknown): string;
+    /** Render bound parameters for diagnostics only; this SQL is never executed by SemanticDB. */
+    displayQuery(sql: string, parameters: SqlParameters): string;
+    execute(request: ProviderExecutionRequest): Promise<DataRow[]>;
+    close(): Promise<void>;
+}

package/dist/physical/snowflake-provider.d.ts

@@ -0,0 +1,45 @@
+import type { ConnectionOptions } from 'snowflake-sdk';
+import type { CoreComputeProvider, DataRow, ProviderExecutionRequest } from './provider';
+type SnowflakeBind = string | number | boolean | null;
+export interface SnowflakeStatementLike {
+    cancel(callback?: (error?: Error) => void): void;
+}
+export interface SnowflakeConnectionLike {
+    connect(callback: (error?: Error) => void): unknown;
+    execute(options: {
+        readonly sqlText: string;
+        readonly binds: readonly SnowflakeBind[];
+        readonly complete: (error: Error | undefined, statement: SnowflakeStatementLike, rows?: unknown[]) => void;
+    }): SnowflakeStatementLike;
+    destroy(callback: (error?: Error) => void): unknown;
+}
+export interface SnowflakeProviderOptions {
+    /** Options passed to snowflake-sdk's createConnection(). */
+    readonly connection?: ConnectionOptions;
+    /** Injectable SDK connection used by tests or caller-managed connection factories. */
+    readonly client?: SnowflakeConnectionLike;
+}
+export declare class SnowflakeProvider implements CoreComputeProvider {
+    #private;
+    readonly kind: "snowflake";
+    constructor(options?: SnowflakeProviderOptions);
+    quoteIdentifier(identifier: string): string;
+    tableAlias(expression: string, alias: string): string;
+    paginate(sql: string, pageSize: number, offset: number): string;
+    parameter(index: number, value: unknown): string;
+    displayQuery(sql: string, parameters: readonly unknown[]): string;
+    dateBucket(expression: string, level: string): string;
+    dateShift(expression: string, granularity: string, offset: number): string;
+    aggregateFunction(name: string, expression?: string): string;
+    concat(expressions: readonly string[]): string;
+    substring(expression: string, start: number, length: number): string;
+    regex(expression: string, pattern: string, options?: string): string;
+    arrayContains(arrayExpression: string, valueExpression: string): string;
+    expandArray(arrayExpression: string, alias: string, column: string): {
+        joinSql: string;
+        valueExpression: string;
+    };
+    execute(request: ProviderExecutionRequest): Promise<DataRow[]>;
+    close(): Promise<void>;
+}
+export {};

package/dist/physical/snowflake-provider.js

@@ -0,0 +1 @@
+import $ from"snowflake-sdk";import{displayQuestionMarkQuery as h}from"./display-query.js";const p=n=>{if(n==null)return null;if(n instanceof Date)return n.toISOString();if(typeof n=="bigint")return n.toString();if(typeof n=="string"||typeof n=="number"||typeof n=="boolean")return n;throw new TypeError(`Unsupported Snowflake parameter type: ${typeof n}`)},w=n=>n.reason instanceof Error?n.reason:new DOMException("The operation was aborted","AbortError");class l{kind="snowflake";#e;#r=!1;#t;constructor(e={}){this.#e=e.client??$.createConnection(e.connection??{})}quoteIdentifier(e){return`"${e.replaceAll('"','""')}"`}tableAlias(e,r){return`${e} AS ${this.quoteIdentifier(r)}`}paginate(e,r,t){return`${e} LIMIT ${r}${t>0?` OFFSET ${t}`:""}`}parameter(e,r){return"?"}displayQuery(e,r){return h(e,r.map(p))}dateBucket(e,r){if(!new Set(["hour","day","week","month","quarter","year"]).has(r))throw new Error(`Unsupported Snowflake date level: ${r}`);return`DATE_TRUNC('${r.toUpperCase()}', ${e})`}dateShift(e,r,t){if(!new Set(["second","minute","hour","day","week","month","quarter","year"]).has(r)||!Number.isInteger(t))throw new Error(`Unsupported Snowflake date shift: ${r}/${t}`);return`DATEADD(${r.toUpperCase()}, ${t}, ${e})`}aggregateFunction(e,r="*"){if(!/^[A-Za-z][A-Za-z0-9_]*$/.test(e))throw new Error(`Unsupported Snowflake aggregate function: ${e}`);return`${e.toUpperCase()}(${r})`}concat(e){return`CONCAT(${e.join(", ")})`}substring(e,r,t){return`SUBSTRING(${e}, ${r}, ${t})`}regex(e,r,t){if(t&&t!=="i")throw new Error(`Unsupported Snowflake regex options: ${t}`);return t?`REGEXP_INSTR(${e}, ${r}, 1, 1, 0, '${t}') > 0`:`REGEXP_INSTR(${e}, ${r}) > 0`}arrayContains(e,r){return`ARRAY_CONTAINS(${r}::VARIANT, ${e})`}expandArray(e,r,t){const o=this.quoteIdentifier(r);return{joinSql:`, LATERAL FLATTEN(INPUT => ${e}) ${o}`,valueExpression:`${o}.VALUE`}}async#n(){if(!this.#r){this.#t??=new Promise((e,r)=>{this.#e.connect(t=>{if(t){r(t);return}this.#r=!0,e()})});try{await this.#t}catch(e){throw this.#t=void 0,e}}}async execute(e){e.signal?.throwIfAborted(),await this.#n(),e.signal?.throwIfAborted();const r=e.parameters.map(p);return new Promise((t,o)=>{const i=e.signal,c={};let f=!1;const a=s=>{f||(f=!0,i?.removeEventListener("abort",u),s())},u=()=>{c.current?.cancel(),i&&a(()=>o(w(i)))};i?.addEventListener("abort",u,{once:!0}),c.current=this.#e.execute({sqlText:e.sql,binds:r,complete:(s,A,d)=>{if(s){a(()=>o(s));return}if(!Array.isArray(d)){a(()=>o(new Error("Snowflake provider expected an array result")));return}a(()=>t(d))}}),i?.aborted&&u()})}async close(){this.#r&&await new Promise((e,r)=>{this.#e.destroy(t=>{if(t){r(t);return}this.#r=!1,this.#t=void 0,e()})})}}export{l as SnowflakeProvider};

package/dist/physical/starrocks-provider.d.ts

@@ -0,0 +1,9 @@
+import { MySQLProtocolProvider } from './mysql-protocol-provider';
+import type { MySQLProtocolPoolLike, MySQLProtocolProviderOptions } from './mysql-protocol-provider';
+export type StarRocksPoolLike = MySQLProtocolPoolLike;
+export type StarRocksProviderOptions = MySQLProtocolProviderOptions;
+/** StarRocks adapter using its MySQL-compatible protocol and SQL surface. */
+export declare class StarRocksProvider extends MySQLProtocolProvider {
+    readonly kind: "starrocks";
+    constructor(options?: StarRocksProviderOptions);
+}

package/dist/physical/starrocks-provider.js

@@ -0,0 +1 @@
+import{MySQLProtocolProvider as o}from"./mysql-protocol-provider.js";class s extends o{kind="starrocks";constructor(r={}){super(r)}}export{s as StarRocksProvider};

package/dist/planner/build-lineage.d.ts

@@ -0,0 +1,5 @@
+import type { OperatorRegistry } from '../operators/index';
+import type { CoreComputeProvider } from '../physical/index';
+import type { ResolvedSemanticSchema } from '../semantic-types/index';
+import type { LogicalPlan, QueryLineage } from './types';
+export declare const buildLineage: (plan: LogicalPlan, schema: ResolvedSemanticSchema, provider: CoreComputeProvider, operators?: OperatorRegistry) => QueryLineage;

package/dist/planner/build-lineage.js

@@ -0,0 +1 @@
+import{createOperatorRegistry as s}from"../operators/index.js";import{getProperty as I}from"../schema/schema-registry.js";const h=(t,r)=>{const o=I(t,r);return{schemaId:t.id,propertyId:o.id,propertyName:o.name,physicalColumn:o.udf?.sql??o.id}},f=(t,r,o)=>{const c=t.fieldReferences?.[o];return c?{schemaId:c.schemaId,propertyId:c.propertyId??c.column,propertyName:c.property,physicalColumn:c.sql??c.column}:h(r,o)},l=(t,r,o,c)=>{if(t.kind==="column")return{sources:[{schemaId:t.schemaId??o.id,propertyId:t.propertyId??t.column,propertyName:t.property,physicalColumn:t.column}],transformations:["projection"]};if(t.kind==="property-sql")return{sources:[{schemaId:t.schemaId,propertyId:t.propertyId,propertyName:t.property,physicalColumn:t.sql}],transformations:["property-sql"]};if(t.kind==="array-element")return{sources:[{schemaId:t.schemaId,propertyId:t.property,propertyName:t.property,physicalColumn:t.property}],transformations:["array-expand"]};if(t.kind==="window"){const a=[t.input,...t.partitionBy].map(n=>l(n,r,o,c));return{sources:a.flatMap(({sources:n})=>n),transformations:[...a.flatMap(({transformations:n})=>n).filter(n=>n!=="projection"),`window:${t.function}`]}}if(t.kind==="cumulative"){const a=[t.input,...t.partitionBy,...t.orderBy.map(({expression:n})=>n)].map(n=>l(n,r,o,c));return{sources:a.flatMap(({sources:n})=>n),transformations:[...a.flatMap(({transformations:n})=>n).filter(n=>n!=="projection"),`window:cumulative:${t.function}`]}}if(t.kind==="ordinal-encode"||t.kind==="ordinal-decode"){const a=l(t.input,r,o,c);return{sources:a.sources,transformations:[...a.transformations.filter(n=>n!=="projection"),`ordinal:${t.kind==="ordinal-encode"?"encode":"decode"}`]}}const i=[...t.input?[t.input]:[],...t.components??[]].map(a=>l(a,r,o,c)),d={sources:i.flatMap(({sources:a})=>a),transformations:i.flatMap(({transformations:a})=>a)},p=c.get(t.operator),u=new Set([...t.property?[t.property]:[],...p.dependencies??[],...m(t.query)]);return{sources:[...d.sources,...[...u].filter(a=>!d.sources.some(n=>n.propertyName===a)).map(a=>f(r,o,a))],transformations:[...d.transformations.filter(a=>a!=="projection"),`operator:${t.operator}`]}};function m(t){if(!t)return[];const r=[];for(const[o,c]of Object.entries(t))if((o==="$and"||o==="$or")&&Array.isArray(c))for(const i of c)typeof i=="object"&&i!==null&&!Array.isArray(i)&&r.push(...m(i));else o.startsWith("$")||r.push(o);return r}const e=t=>t.kind==="window"?[...e(t.input),...t.partitionBy.flatMap(e)]:t.kind==="cumulative"?[...e(t.input),...t.partitionBy.flatMap(e),...t.orderBy.flatMap(({expression:r})=>e(r))]:t.kind==="ordinal-encode"||t.kind==="ordinal-decode"?e(t.input):t.kind==="operator"?[...m(t.query),...t.input?e(t.input):[],...(t.components??[]).flatMap(e)]:[],y=(t,r,o,c=s())=>{if(t.composition){const i=t.composition.map(d=>y(d,r,o,c));return{source:{schemaId:r.id,schemaName:r.name,physicalTable:i.map(({source:d})=>d.physicalTable).join(", "),provider:o.kind},outputs:t.projections.map(({name:d})=>{const p=i.flatMap(({outputs:u})=>u.filter(a=>a.name===d));return{name:d,sources:p.flatMap(({sources:u})=>u),transformations:[...new Set([...p.flatMap(({transformations:u})=>u),"compose"])]}}),filters:i.flatMap(({filters:d})=>d)}}return{source:{schemaId:r.id,schemaName:r.name,physicalTable:t.source,provider:o.kind},outputs:t.projections.map(i=>({name:i.name,...l(i.expression,t,r,c)})),filters:[...new Set([...m(t.query),...t.projections.flatMap(({expression:i})=>e(i))])].map(i=>f(t,r,i))}};export{y as buildLineage};

package/dist/planner/create-logical-plan.d.ts

@@ -0,0 +1,15 @@
+import type { LogicformType } from '../logicform-types';
+import type { OperatorRegistry } from '../operators/index';
+import { SchemaMappingRegistry } from '../schema-mappings/index';
+import type { ResolvedSemanticSchema } from '../semantic-types/index';
+import type { ResolvedSemanticProperty } from '../semantic-types/index';
+import { type PlannerSemanticRegistry } from './semantics/index';
+import type { LogicalPlan } from './types';
+export declare const createResultSchema: (plan: LogicalPlan, sourceSchema: ResolvedSemanticSchema) => ResolvedSemanticSchema;
+export declare const createDerivedSourceSchema: (sourcePlan: LogicalPlan, outerSchema: ResolvedSemanticSchema) => ResolvedSemanticSchema;
+export interface CreateLogicalPlanOptions {
+    readonly resolveSchema?: (schemaId: string) => ResolvedSemanticSchema;
+    readonly canUsePropertyRowIdentity?: (schema: ResolvedSemanticSchema, property: ResolvedSemanticProperty) => boolean;
+    readonly semanticRegistry?: PlannerSemanticRegistry;
+}
+export declare const createLogicalPlan: (logicform: LogicformType, schema: ResolvedSemanticSchema, operators?: OperatorRegistry, schemaMappings?: SchemaMappingRegistry, options?: CreateLogicalPlanOptions) => LogicalPlan;

package/dist/planner/create-logical-plan.js

@@ -0,0 +1 @@
+import{SemanticDBError as m}from"../errors.js";import{createOperatorRegistry as ce}from"../operators/index.js";import{isComposedLogicform as ue,isLogicform as te}from"../logicform-types.js";import{buildFieldMap as me}from"../schema/schema-registry.js";import{resolvePropertyPath as z}from"../schema/resolve-property-path.js";import{SchemaMappingRegistry as de}from"../schema-mappings/registry.js";import{createPlannerSemanticRegistry as ye}from"./semantics/registry-defaults.js";import{selectSchemaMapping as le,mappedPropertyColumn as ne}from"./select-schema-mapping.js";const fe=(e,o)=>`result:${e}:${o.map(({name:c,type:y,primal_type:d})=>`${c}:${y}:${d}`).join("|")}`,oe=(e,o)=>{const c=(e.columnProperties??[]).map(y=>({...y,id:y.name}));return{id:fe(e.schemaId,e.columnProperties??[]),name:`${o.name} result`,type:o.type,temporalSemantics:"normal",properties:c}},ie=(e,o)=>({...oe(e,o),id:o.id,name:o.name,type:o.type}),v=e=>{if(!e.name)throw new m("MISSING_PRED_NAME","Planner requires every normalized PredItem to have a name");return e.name},he=(e,o,c)=>{const y=new Set(c),d=(I,g)=>{if(!(te(I)||I===null)){if(Array.isArray(I)){I.forEach(l=>d(l,g));return}if(typeof I=="object"){Object.entries(I).forEach(([l,E])=>{["args","$exists","$regex","$contains"].includes(l)||d(E,l)});return}if(!(g&&["args","$exists","$regex","$contains"].includes(g))&&(typeof I!="string"||!y.has(I)))throw new m("COMPARABLE_VALUE_NOT_FOUND",`Comparable category ${o} does not contain value: ${JSON.stringify(I)}`,{property:o,value:I})}};d(e)},ge=(e,o)=>{if(!o.udf)return{};const c=e.properties.find(({type:y})=>y==="timestamp")?.id;return{sql:o.udf.sql,...c?{timestampColumn:c}:{}}},se=e=>e.sql?{kind:"property-sql",schemaId:e.schemaId,property:e.property,propertyId:e.column,sql:e.sql,qualifier:e.qualifier,...e.timestampColumn?{timestampColumn:e.timestampColumn}:{}}:{kind:"column",...e},ae=(e,o,c={})=>({name:e,type:o.type,primal_type:o.primal_type,isArray:o.isArray,...o.ref?{ref:o.ref}:{},...o.comparable?{comparable:o.comparable}:{},...c}),M=(e,o,c,y,d,I,g,l,E="projection")=>{const T=v(e);if(E==="groupby"&&e.query)throw new m("GROUPBY_QUERY_NOT_ALLOWED","A groupby expression cannot define pred.query");if(!e.operator){if(typeof e.pred!="string")throw new m("PRED_PROPERTY_REQUIRED","A projection must reference a property");const h=c(e.pred);return{expression:se(h.field),outputProperty:ae(h.reference,h.property),sourceProperty:h.property,sourceField:h.field}}const S=o.get(e.operator);if(E==="groupby"&&S.kind!=="scalar")throw new m("OPERATOR_NOT_ALLOWED_IN_GROUPBY",`Operator ${e.operator} cannot be used in groupby`,{operator:e.operator});if(E==="groupby"&&!S.toSQL)throw new m("JAVASCRIPT_OPERATOR_NOT_ALLOWED_IN_GROUPBY",`JavaScript-only operator ${e.operator} cannot be used in groupby`,{operator:e.operator});if(S.planInput&&typeof e.pred!="string")throw new m("OPERATOR_DIRECT_PROPERTY_REQUIRED",`${e.operator} requires a direct property pred`);const b=S.planInput&&typeof e.pred=="string"?S.planInput({reference:e.pred,args:e.args??{},schema:g,...l?{resolveSchema:l}:{}}):void 0,A=b?.reference??e.pred,_=b?.args??e.args??{},u=A&&typeof A=="object"&&!Array.isArray(A)?M(A,o,c,y,d,I,g,l,E):typeof A=="string"?M({pred:A,name:A},o,c,y,d,I,g,l,E):void 0,s=e.components?.map(h=>M(h,o,c,y,d,I,g,l,E))??[];if(S.requiresProperty!==!1&&!u&&s.length===0)throw new m("PRED_PROPERTY_REQUIRED",`${e.operator} requires a property`);const P=T,f=S.getOutputProperty?.({name:P,...u?.sourceProperty?{property:u.sourceProperty}:{},...u?{inputProperty:{...u.outputProperty,name:P}}:{},...s.length>0?{componentProperties:s.map(({outputProperty:h})=>h)}:{},args:_})??(u?ae(P,u.outputProperty,{isArray:!1}):{name:P,type:"number",primal_type:"number",isArray:!1});if(S.planExpression){const h=S.planExpression({pred:e,...u?{input:u.expression,inputProperty:u.outputProperty}:{},components:s.map(({expression:w})=>w),args:_,resolveKey:d,getOperator:w=>o.get(w),planQuery:I});if(h)return{expression:h,outputProperty:f,...u?.sourceProperty?{sourceProperty:u.sourceProperty}:{},...u?.sourceField?{sourceField:u.sourceField}:{}}}if(S.kind==="window"){if(!u||s.length>0||e.query)throw new m("INVALID_WINDOW_OPERATOR_INPUT",`${e.operator} requires exactly one nested pred and does not accept pred.query`);const h=e.args?.direction??"desc";if(h!=="asc"&&h!=="desc")throw new m("INVALID_WINDOW_ARGS",`${e.operator} direction must be asc or desc`);const w=e.args?.partitionBy??[];if(!Array.isArray(w)||w.some(D=>typeof D!="string"))throw new m("INVALID_WINDOW_ARGS",`${e.operator} partitionBy must be an array of groupby names`);return{expression:{kind:"window",function:S.windowFunction,input:u.expression,partitionBy:w.map(D=>y(String(D))),direction:h==="asc"?"ASC":"DESC"},outputProperty:f}}return{expression:{kind:"operator",operator:e.operator,args:_,...e.query?{query:I(e.query)}:{},...u?{input:u.expression}:{},...s.length>0?{components:s.map(({expression:h})=>h)}:{},...u?.sourceProperty?{property:u.sourceProperty.name,column:u.sourceProperty.id}:{},...u?.sourceField?{qualifier:u.sourceField.qualifier,schemaId:u.sourceField.schemaId}:{}},outputProperty:f,...u?.sourceProperty?{sourceProperty:u.sourceProperty}:{},...u?.sourceField?{sourceField:u.sourceField}:{}}},Ie=(e,o,c,y,d,I,g,l,E,T)=>{const S=v(e),b=typeof e.pred=="string"?e.pred:void 0,_=M(e,o,!T||!b?c:s=>{const P=c(s);return s===b?{...P,field:{...P.field,column:T}}:P},y,d,I,g,l),u=E?.resolveProjection({pred:e,schema:g,..._.sourceProperty?{sourceProperty:_.sourceProperty}:{},outputProperty:{..._.outputProperty,name:S},...e.operator?{operator:o.get(e.operator)}:{}})??{..._.outputProperty,name:S};return{name:S,expression:_.expression,outputProperty:u}},Se=e=>{const o=new Set;for(const c of e){if(o.has(c.name))throw new m("DUPLICATE_OUTPUT_NAME",`Duplicate output name: ${c.name}`);o.add(c.name)}},Pe=e=>{let o="__semanticdb_row_identity";for(;e.has(o);)o=`_${o}`;return o},X=(e,o,c)=>{if(!e.schema||e.schema===o.id)return o;const y=c.resolveSchema?.(e.schema);if(!y)throw new m("SCHEMA_RESOLVER_REQUIRED",`Cannot plan nested LogicForm schema without a schema resolver: ${e.schema}`,{schemaId:e.schema});return y},we=(e,o,c,y,d)=>{if(e.logicforms.length<2)throw new m("COMPOSITION_REQUIRES_MULTIPLE_LOGICFORMS","logicforms must contain at least two LogicForms");const I=["schema","from","query","preds","groupby","having","limit","page","entity_id"].filter(s=>e[s]!==void 0);if(I.length>0)throw new m("INVALID_COMPOSED_LOGICFORM",`A composed LogicForm cannot define: ${I.join(", ")}`,{fields:I});const g=e.logicforms.map(s=>F(s,X(s,o,d),c,y,d)),l=g[0]?.groupBy.map(({name:s})=>s)??[];for(const s of g){const P=s.groupBy.map(({name:f})=>f);if(P.length!==l.length||P.some((f,h)=>f!==l[h]))throw new m("INCOMPATIBLE_COMPOSITION_GROUPBY","All composed LogicForms must have the same groupby output names in the same order",{expected:l,received:P});if(s.rowIdentity.kind!==(l.length>0?"group":"singleton"))throw new m("UNSTABLE_COMPOSITION_IDENTITY","Composed LogicForms must be grouped or aggregate to a singleton row")}const E=[],T=[],S=new Map;g.forEach((s,P)=>{s.projections.forEach((f,h)=>{const w=l.includes(f.name),D=S.get(f.name);if(D!==void 0&&!w)throw new m("DUPLICATE_COMPOSITION_OUTPUT",`Composed LogicForms produce the same output: ${f.name}`,{name:f.name,childIndexes:[D,P]});if(D!==void 0)return;S.set(f.name,P),E.push({name:f.name,expression:{kind:"column",property:f.name,column:f.name}});const B=s.columnProperties?.[h];B&&T.push(B)})});const b=new Set(E.map(({name:s})=>s)),A=Object.entries(e.sort??{}).map(([s,P])=>{if(!b.has(s))throw new m("INVALID_SORT",`Sort field is not an output: ${s}`);const f=T.find(h=>h.name===s);return{name:s,direction:P===1?"ASC":"DESC",...f?.comparable?{comparable:f.comparable}:{},...f?.comparable?{expression:{kind:"column",property:s,column:s}}:{}}}),_=e.limitBy===void 0||l.length<2?void 0:{count:e.limitBy,partitionBy:l.slice(0,-1),orderBy:A.length>0?A:(()=>{const s=l.at(-1)??"",P=T.find(f=>f.name===s);return[{name:s,direction:"ASC",...P?.comparable?{comparable:P.comparable}:{}}]})()},u=e.limitBy!==void 0&&l.length<2?{kind:"rows",page:1,pageSize:e.limitBy}:void 0;return{schemaId:o.id,source:"",composition:g,fields:Object.fromEntries(E.map(({name:s})=>[s,s])),projections:E,columnProperties:T,groupBy:E.filter(({name:s})=>l.includes(s)),orderBy:A,rowIdentity:l.length>0?{kind:"group",names:l}:{kind:"singleton"},..._?{groupLimit:_}:{},...u?{pagination:u}:{}}},F=(e,o,c=ce(),y=new de,d={})=>{if(ue(e))return we(e,o,c,y,d);for(const r of e.preds??[]){if(!r.operator)continue;const t=c.get(r.operator).rewriteLogicform?.({logicform:e,schema:o});if(t)return F(t,o,c,y,d)}const I=d.semanticRegistry??ye();if(e.from){const r=X(e.from,o,d),t=F(e.from,r,c,y,d),n=ie(t,o),i={...e};delete i.from,i.schema??=n.id;const p=F(i,n,c,y,d),a=new Set(p.projections.map(({name:R})=>R)),N=t.rowIdentity.kind==="group"&&t.rowIdentity.names.every(R=>a.has(R))||t.rowIdentity.kind==="singleton"?t.rowIdentity:{kind:"generated"};return{...p,source:t.source,sourcePlan:t,rowIdentity:N}}if(!e.schema)throw new m("LOGICFORM_SCHEMA_REQUIRED","A physical LogicForm must define schema");const g=le(e,o,y);e=g.logicform;const l=new Map(g.predRewrites.map(({predIndex:r,column:t})=>[r,t])),E=I.resolveQuery({logicform:e,schema:o,...e.query?{query:e.query}:{}}),T=o.id,S=new Map,b=new Map,A=new Map,_=r=>{const t=z(o,r,d.resolveSchema);let n=T;const i=[];for(const a of t.relations){i.push(a.property.name);const N=i.join("_"),R=N;if(!S.has(N)){const q=a.targetSchema.properties.filter(({type:L})=>L==="ID"),[C]=q;if(q.length!==1||!C)throw new m(a.targetSchema.temporalSemantics==="snapshot"?"SNAPSHOT_JOIN_REQUIRES_ID_AND_TIMESTAMP":"RELATION_TARGET_ID_REQUIRED",a.targetSchema.temporalSemantics==="snapshot"?`Snapshot Schema ${a.targetSchema.id} requires an ID Property when joined`:`Relation target ${a.targetSchema.id} must contain exactly one ID property`,{schemaId:a.targetSchema.id,count:q.length});const $=a.sourceSchema.properties.find(({type:L})=>L==="timestamp"),U=a.targetSchema.properties.find(({type:L})=>L==="timestamp"),O=$?.id,Q=U?.id;if(a.targetSchema.temporalSemantics==="snapshot"){if(!U)throw new m("SNAPSHOT_JOIN_REQUIRES_ID_AND_TIMESTAMP",`Snapshot Schema ${a.targetSchema.id} requires an ID and timestamp Property when joined`,{schemaId:a.targetSchema.id});if(!$)throw new m("SNAPSHOT_JOIN_SOURCE_TIMESTAMP_REQUIRED",`Snapshot Schema ${a.targetSchema.id} cannot join from a Schema without a timestamp Property`,{schemaId:a.sourceSchema.id});const L=["second","minute","hour","day","week","month","quarter","year"],J=$.granularity??"day",k=U.granularity??"day";if(L.indexOf(J)>L.indexOf(k))throw new m("SNAPSHOT_JOIN_GRANULARITY_TOO_COARSE",`Cannot join ${a.targetSchema.id} snapshot granularity ${k} to coarser source granularity ${J}`,{sourceSchemaId:a.sourceSchema.id,targetSchemaId:a.targetSchema.id,sourceGranularity:J,targetGranularity:k})}const j=a.property.isArray?N:void 0;j&&!b.has(j)&&b.set(j,{path:j,sourceAlias:n,sourceColumn:a.property.id,...a.property.udf?{sourceSql:a.property.udf.sql,...O?{sourceTimestampColumn:O}:{}}:{},alias:`__array_${N}`});const H=y.get(a.targetSchema.id);S.set(N,{kind:"left",path:N,sourceAlias:n,sourceColumn:a.property.id,...a.property.udf?{sourceSql:a.property.udf.sql,...O?{sourceTimestampColumn:O}:{}}:{},targetSchemaId:a.targetSchema.id,targetSource:H.source,...H.sourceSql?{targetSourceSql:H.sourceSql}:{},targetAlias:R,targetColumn:C.id,...j?{sourceArrayExpansionPath:j}:{},...C.udf?{targetSql:C.udf.sql,...Q?{targetTimestampColumn:Q}:{}}:{},...a.targetSchema.temporalSemantics==="snapshot"&&O?{sourceTimestampColumn:O,sourceTimestampGranularity:$.granularity??"day"}:{},...a.targetSchema.temporalSemantics==="snapshot"&&Q?{targetTimestampColumn:Q,targetTimestampGranularity:U.granularity??"day"}:{}})}n=R}const p={schemaId:t.schema.id,property:t.property.name,propertyId:t.property.id,column:t.relations.length===0?ne(g.mapping,o,t.canonicalName)??t.property.id:t.property.id,qualifier:n,...t.property.isArray?{isArray:!0}:{},...t.property.comparable?{comparable:t.property.comparable}:{},...ge(t.schema,t.property)};return A.set(t.canonicalName,p),{reference:t.canonicalName,schema:t.schema,property:t.property,field:p}},u=r=>{if(r)for(const[t,n]of Object.entries(r))if((t==="$and"||t==="$or")&&Array.isArray(n))for(const i of n)typeof i=="object"&&i!==null&&!Array.isArray(i)&&u(i);else t.startsWith("$")||_(t)},s=r=>{if(te(r)){const t=X(r,o,d),n=F(r,t,c,y,d);if(n.projections.length!==1)throw new m("SUBQUERY_SINGLE_COLUMN_REQUIRED",`Query LogicForm must output exactly one column, received ${n.projections.length}`,{schemaId:r.schema,projectionCount:n.projections.length});return{kind:"logicform-subquery",plan:n}}return Array.isArray(r)?r.map(s):typeof r!="object"||r===null||r instanceof Date?r:Object.fromEntries(Object.entries(r).map(([t,n])=>[t,s(n)]))},P=(r,t)=>{if(typeof t!="object"||t===null||Array.isArray(t))throw new m("INVALID_RECURSIVE_QUERY","$recursive must be normalized before planning");const n=t,i=_(r),p=typeof n.schema=="string"?n.schema:i.property.ref??i.schema.id,a=p===o.id?o:d.resolveSchema?.(p);if(!a)throw new m("SCHEMA_RESOLVER_REQUIRED",`$recursive requires Schema ${p}`);const N=a.properties.find(({id:C,name:$})=>C===n.idProperty||$===n.idProperty),R=a.properties.find(({id:C,name:$})=>C===n.parentProperty||$===n.parentProperty);if(!N)throw new m("RECURSIVE_ID_PROPERTY_REQUIRED",`$recursive ID property not found: ${String(n.idProperty)}`);if(!R)throw new m("RECURSIVE_PARENT_PROPERTY_REQUIRED",`$recursive parent property not found: ${String(n.parentProperty)}`);if(!Array.isArray(n.roots)||typeof n.includeSelf!="boolean")throw new m("INVALID_RECURSIVE_QUERY","$recursive must be normalized before planning");const q=y.get(p);return{kind:"recursive-query",schemaId:p,source:q.source,...q.sourceSql?{sourceSql:q.sourceSql}:{},idColumn:N.id,parentColumn:R.id,roots:n.roots,includeSelf:n.includeSelf}},f=r=>Object.fromEntries(Object.entries(r).map(([t,n])=>{if((t==="$and"||t==="$or")&&Array.isArray(n))return[t,n.map(p=>f(p))];if(typeof n=="object"&&n!==null&&!Array.isArray(n)&&Object.prototype.hasOwnProperty.call(n,"$recursive"))return[t,{$recursive:P(t,n.$recursive)}];const i=t.startsWith("$")?void 0:_(t).property.comparable;return[t,i?{kind:"ordinal-query",comparable:i,condition:s(n)}:s(n)]})),h=r=>{const t=i=>{if(!i||typeof i!="object")return!1;if(Array.isArray(i))return i.some(t);const p=i;return Object.prototype.hasOwnProperty.call(p,"$and")||Object.values(p).some(t)};if(t(r))return r;const n=new Set(Object.keys(r).flatMap(i=>{if(i.startsWith("$"))return[];const p=z(o,i,d.resolveSchema);return p.relations.length===1&&p.property.type==="ID"?[p.relations[0]?.property.name]:[]}));return Object.fromEntries(Object.entries(r).map(([i,p])=>{if(i==="$and"||i==="$or")return Array.isArray(p)?[i,p.map(O=>typeof O=="object"&&O!==null&&!Array.isArray(O)?h(O):O)]:[i,p];if(i.startsWith("$"))return[i,p];const a=z(o,i,d.resolveSchema);if(a.relations.length===0)return[i,p];const N=a.relations.map(({property:O})=>O.name).join("_");if(S.has(N))return[i,p];const[R]=a.relations;if(!R)return[i,p];if(n.has(R.property.name))return[i,p];const q=R.property.name,C=a.canonicalName.slice(q.length+1),$=R.targetSchema.properties.find(({type:O})=>O==="ID");if(!$)throw new m("RELATION_TARGET_ID_REQUIRED",`Relation target ${R.targetSchema.id} must contain an ID property`,{schemaId:R.targetSchema.id});if(a.relations.length===1&&a.property.id===$.id)return[R.property.id,p];const U={version:e.version,schema:R.targetSchema.id,query:C?{[C]:p}:{},preds:[{pred:$.name,name:$.name}]};return[R.property.id,{$in:U}]}))},w=(e.groupby??[]).map(r=>{const t=v(r);if(r.operator==="$case"&&r.args?.mode==="auto"&&(r.args.min===void 0||r.args.max===void 0))throw new m("AUTO_CASE_GROUPBY_REQUIRES_BOUNDS","$case auto mode in groupby requires explicit args.min and args.max");const n=M(r,c,_,D,B,f,o,d.resolveSchema,"groupby");let i=n.expression;if(n.sourceProperty?.isArray&&n.sourceField){const p=`groupby:${t}`;b.set(p,{path:p,sourceAlias:n.sourceField.qualifier,sourceColumn:n.sourceField.column,...n.sourceField.sql?{sourceSql:n.sourceField.sql,...n.sourceField.timestampColumn?{sourceTimestampColumn:n.sourceField.timestampColumn}:{}}:{},alias:`__array_group_${b.size}`}),i={kind:"array-element",schemaId:n.sourceField.schemaId,property:n.sourceProperty.name,expansionPath:p}}return{name:t,expression:i,outputProperty:{...n.outputProperty,name:t,isArray:!1}}});function D(r){const t=(e.groupby??[]).findIndex(i=>typeof i.pred=="string"&&i.pred===r||i.name===r),n=t>=0?w[t]:void 0;if(!n)throw new m("WINDOW_PARTITION_NOT_GROUPED",`Window partition must reference a groupby item: ${r}`);return n.expression}function B(r){const t=(e.groupby??[]).findIndex(i=>typeof i.pred=="string"&&i.pred===r||i.name===r),n=t>=0?w[t]:void 0;return n?n.expression:se(_(r).field)}const G=r=>{r.operator&&c.get(r.operator).validatePlan?.({pred:r,groupByNames:w.map(({name:t})=>t),resolveGroupName:t=>{const n=(e.groupby??[]).findIndex(i=>i.name===t||typeof i.pred=="string"&&i.pred===t);return n>=0?w[n]?.name:void 0},getOperator:t=>c.get(t)}),r.pred&&typeof r.pred=="object"&&G(r.pred);for(const t of r.components??[])G(t)};for(const r of e.preds??[])G(r);const x=[...w,...(e.preds??[]).map((r,t)=>Ie(r,c,_,D,B,f,o,d.resolveSchema,I,l.get(t)))],Z=r=>Object.fromEntries(Object.entries(r).map(([t,n])=>{if((t==="$and"||t==="$or")&&Array.isArray(n))return[t,n.map(p=>Z(p))];const i=x.find(({name:p})=>p===t)?.outputProperty.comparable;return i&&he(n,t,i.values),[t,i?{kind:"ordinal-query",comparable:i,condition:s(n)}:s(n)]})),V=E?h(E):void 0;u(V);const Y=r=>{u(r.query),r.pred&&typeof r.pred=="object"&&Y(r.pred);for(const t of r.components??[])Y(t)};for(const r of e.preds??[])Y(r);if(x.length===0)throw new m("EMPTY_PROJECTION","LogicForm must contain preds or groupby");Se(x);const K=new Set(x.map(({name:r})=>r)),pe=w.length>0?{kind:"group",names:w.map(({name:r})=>r)}:x.every(({expression:r})=>r.kind==="column")?(()=>{const r=o.properties.find(({type:t})=>t==="ID");return r&&(d.canUsePropertyRowIdentity?.(o,r)??!0)?{kind:"property",column:r.id,internalName:Pe(K)}:{kind:"generated"}})():{kind:"singleton"},W=Object.entries(e.sort??{}).map(([r,t])=>{if(!K.has(r))throw new m("INVALID_SORT",`Sort field is not an output: ${r}`);const n=x.find(i=>i.name===r);return{name:r,direction:t===1?"ASC":"DESC",...n?.outputProperty.comparable?{comparable:n.outputProperty.comparable,expression:n.expression}:{}}}),ee=e.limit===void 0?void 0:e.limit>0&&e.limit<1?{kind:"ratio",page:e.page??1,ratio:e.limit}:{kind:"rows",page:e.page??1,pageSize:e.limit},re=e.limitBy===void 0?void 0:{count:e.limitBy,partitionBy:w.slice(0,-1).map(({name:r})=>r),orderBy:W.length>0?W:(()=>{const r=w.at(-1);return[{name:r?.name??"",direction:"ASC",...r?.outputProperty.comparable?{comparable:r.outputProperty.comparable,expression:r.expression}:{}}]})()};return{schemaId:o.id,source:g.mapping.source,...g.mapping.sourceSql?{sourceSql:g.mapping.sourceSql}:{},mappingId:g.mapping.id??g.mapping.source,sourceAlias:T,fields:{...me(o),...Object.fromEntries(o.properties.flatMap(r=>{const t=ne(g.mapping,o,r.name);return t?[[r.name,t],[r.id,t]]:[]}))},fieldReferences:Object.fromEntries(A),joins:[...S.values()],arrayExpansions:[...b.values()],projections:x.map(({name:r,expression:t})=>({name:r,expression:t})),columnProperties:x.map(({outputProperty:r})=>r),groupBy:w.map(({name:r,expression:t})=>({name:r,expression:t})),...V?{query:f(V)}:{},...e.having?{having:Z(e.having)}:{},orderBy:W,rowIdentity:pe,...ee?{pagination:ee}:{},...re?{groupLimit:re}:{}}};export{ie as createDerivedSourceSchema,F as createLogicalPlan,oe as createResultSchema};

package/dist/planner/index.d.ts

@@ -0,0 +1,7 @@
+export { buildLineage } from './build-lineage';
+export { createDerivedSourceSchema, createLogicalPlan, createResultSchema } from './create-logical-plan';
+export type { CreateLogicalPlanOptions } from './create-logical-plan';
+export type { Expression, ArrayExpansionPlan, FieldReferencePlan, GroupLimitPlan, JoinPlan, LogicalQuerySubquery, LogicalRecursiveQuery, LogicalOrdinalQuery, LineageColumnSource, LineageOutput, LogicalPlan, OrderPlan, PaginationPlan, ProjectionPlan, QueryLineage, RowIdentityPlan, } from './types';
+export { isLogicalQuerySubquery, isLogicalRecursiveQuery } from './types';
+export { isLogicalOrdinalQuery } from './types';
+export * from './semantics/index';

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

@@ -0,0 +1,14 @@
+import type { LogicformType } from '../logicform-types';
+import type { SchemaMappingDefinition, SchemaMappingRegistry } from '../schema-mappings/index';
+import type { ResolvedSemanticSchema } from '../semantic-types/index';
+export interface PredMappingRewrite {
+    readonly predIndex: number;
+    readonly column: string;
+}
+export interface SelectedSchemaMapping {
+    readonly mapping: SchemaMappingDefinition;
+    readonly logicform: LogicformType;
+    readonly predRewrites: readonly PredMappingRewrite[];
+}
+export declare const mappedPropertyColumn: (mapping: SchemaMappingDefinition, schema: ResolvedSemanticSchema, reference: string) => string | undefined;
+export declare const selectSchemaMapping: (logicform: LogicformType, schema: ResolvedSemanticSchema, mappings: SchemaMappingRegistry) => SelectedSchemaMapping;

package/dist/planner/select-schema-mapping.js

@@ -0,0 +1 @@
+import{SemanticDBError as M}from"../errors.js";import{clone as v}from"../utils/clone.js";const C=e=>e.id??e.source,h=(e,r)=>{if(e===r)return!0;if(e instanceof Date||r instanceof Date)return e instanceof Date&&r instanceof Date&&e.getTime()===r.getTime();if(Array.isArray(e)||Array.isArray(r))return Array.isArray(e)&&Array.isArray(r)&&e.length===r.length&&e.every((o,s)=>h(o,r[s]));if(typeof e!="object"||e===null||typeof r!="object"||r===null)return!1;const t=Object.entries(e),n=r;return t.length===Object.keys(n).length&&t.every(([o,s])=>Object.prototype.hasOwnProperty.call(n,o)&&h(s,n[o]))},a=e=>{if(!e)return[];const r=[];for(const[t,n]of Object.entries(e))if(n!==void 0){if(t==="$or")return;if(t==="$and"){if(!Array.isArray(n))return;for(const o of n){const s=a(o);if(!s)return;r.push(...s)}continue}if(t.startsWith("$"))return;r.push({property:t,condition:n})}return r},$=(e,r)=>{if(!e)return;const t={};for(const[n,o]of Object.entries(e))if(o!==void 0){if(n==="$and"&&Array.isArray(o)){const s=o.map(d=>$(d,r)).filter(d=>d!==void 0);s.length>0&&(t[n]=s);continue}n!=="$or"&&r.some(s=>s.property===n&&h(s.condition,o))||(t[n]=o)}return Object.keys(t).length>0?t:void 0},b=(e,r)=>e.properties.find(({id:t,name:n})=>t===r||n===r),O=(e,r,t)=>{const n=b(r,t);if(n)return e.properties?e.properties[n.name]??e.properties[n.id]:n.id},I=(e,r,t)=>e.properties===void 0||O(e,r,t)!==void 0,R=(e,r,t)=>{if(!e||r.properties===void 0)return;const n=a(e);if(!n)return"query contains an unsupported logical expression";const o=n.find(({property:s})=>!I(r,t,s));return o?`query property is not available: ${o.property}`:void 0},q=e=>[...typeof e.pred=="string"?[e.pred]:e.pred&&typeof e.pred=="object"?q(e.pred):[],...e.components?.flatMap(q)??[]],w=(e,r,t,n,o)=>{if(e.match.schema!==void 0&&e.match.schema!==n)return!1;const s=typeof r.pred=="string"?b(t,r.pred):void 0,d=b(t,e.match.pred),i=r.pred===e.match.pred||!!(s&&d&&s.id===d.id);if(r.operator!==e.match.operator||!i||r.components||r.args&&Object.keys(r.args).length>0)return!1;const c=a(e.match.query);return c!==void 0&&c.every(u=>o.some(p=>p.property===u.property&&h(p.condition,u.condition)))},D=(e,r,t)=>{if(t.predMappings===void 0&&t.properties===void 0)return{mapping:t,logicform:e,predRewrites:[],priority:t.priority??0,specificity:0};const n=a(e.query);if(!n&&t.predMappings)return"query contains $or or another unsupported logical expression";const o=v(e),s=[],d=[];for(const[u,p]of(e.preds??[]).entries()){const f=a(p.query);if(!f&&t.predMappings)return`PredItem ${u} query contains an unsupported logical expression`;if(t.predMappings){const A=[...n??[],...f??[]],P=t.predMappings.filter(m=>w(m,p,r,p.schema??r.id,A));if(P.length===0)return`PredItem ${u} is not mapped`;if(P.length>1)return`PredItem ${u} matches multiple mapping rules`;const g=P[0],j=a(g.match.query)??[];d.push(...j);const l=o.preds?.[u];if(l){const m=$(l.query,j);m?l.query=m:delete l.query}s.push({predIndex:u,column:g.column});continue}const y=q(p).find(A=>!I(t,r,A));if(y)return`PredItem ${u} property is not available: ${y}`}const i=$(o.query,d);i?o.query=i:delete o.query;const c=R(o.query,t,r);if(c)return c;for(const[u,p]of(o.preds??[]).entries()){const f=R(p.query,t,r);if(f)return`PredItem ${u} ${f}`}for(const u of o.groupby??[]){const f=q(u).find(y=>!I(t,r,y));if(f)return`groupby property is not available: ${f}`}return{mapping:t,logicform:o,predRewrites:s,priority:t.priority??0,specificity:s.length}},E=(e,r,t)=>{const n=[],o=[];for(const i of t.list(r.id)){const c=D(e,r,i);typeof c=="string"?o.push({mappingId:C(i),reason:c}):n.push(c)}if(n.length===0)throw new M("QUERY_NOT_COVERED_BY_DATA_SOURCE","\u5F53\u524D\u63A5\u5165\u7684\u6570\u636E\u4E0D\u652F\u6301\u6B64\u95EE\u9898\u3002\u5982\u9700\u652F\u6301\uFF0C\u9700\u8981\u63A5\u5165\u660E\u7EC6\u5C42\u6570\u636E\uFF0C\u8BF7\u8054\u7CFB\u6570\u636E\u7BA1\u7406\u5458\u3002",{schemaId:r.id,requiredDataLayer:"detail",rejectedMappings:o});n.sort((i,c)=>c.priority-i.priority||c.specificity-i.specificity);const s=n[0],d=n.filter(({priority:i,specificity:c})=>i===s.priority&&c===s.specificity);if(d.length>1)throw new M("SCHEMA_MAPPING_AMBIGUOUS",`Multiple Schema mappings cover the LogicForm for ${r.id}`,{schemaId:r.id,mappingIds:d.map(({mapping:i})=>C(i))});return s};export{O as mappedPropertyColumn,E as selectSchemaMapping};

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

@@ -0,0 +1,5 @@
+export * from './observation/index';
+export * from './lifecycle/index';
+export { PlannerSemanticRegistry } from './registry';
+export type { PlannerSemanticResolution, PlannerSemanticQueryContext, PlannerSemanticRule, PlannerSemanticRuleContext, } from './registry';
+export { createPlannerSemanticRegistry } from './registry-defaults';

package/dist/planner/semantics/lifecycle/classification.d.ts

@@ -0,0 +1,7 @@
+import type { ResolvedSemanticProperty, ResolvedSemanticSchema } from '../../../semantic-types/index';
+export interface LifecycleProperties {
+    readonly timestamp: ResolvedSemanticProperty;
+    readonly start: ResolvedSemanticProperty;
+    readonly end: ResolvedSemanticProperty;
+}
+export declare const resolveLifecycleProperties: (schema: Pick<ResolvedSemanticSchema, "type" | "properties">) => LifecycleProperties | undefined;

package/dist/planner/semantics/lifecycle/classification.js

@@ -0,0 +1 @@
+const p=t=>{if(t.type!=="entity")return;const n=t.properties.find(e=>e.type==="timestamp"),r=t.properties.find(e=>e.type==="start_date"),i=t.properties.find(e=>e.type==="end_date");return n&&r&&i?{timestamp:n,start:r,end:i}:void 0};export{p as resolveLifecycleProperties};

package/dist/planner/semantics/lifecycle/index.d.ts

@@ -0,0 +1,3 @@
+export { resolveLifecycleProperties } from './classification';
+export { applyLifecycleQuery } from './query-policy';
+export { lifecycleSemanticRule } from './rule';

package/dist/planner/semantics/lifecycle/query-policy.d.ts

@@ -0,0 +1,3 @@
+import type { QueryType } from '../../../logicform-types';
+import type { LifecycleProperties } from './classification';
+export declare const applyLifecycleQuery: (query: QueryType | undefined, properties: LifecycleProperties) => QueryType | undefined;

package/dist/planner/semantics/lifecycle/query-policy.js

@@ -0,0 +1 @@
+const s=t=>typeof t=="object"&&t!==null&&!Array.isArray(t),c=t=>s(t)?t.$lte??t.$lt??t.$eq:t,f=(t,n)=>{if(!t)return t;const r=Object.entries(t).find(([i])=>i===n.timestamp.name);if(!r)return t;const[,m]=r,e=c(m);return e===void 0?t:{...Object.fromEntries(Object.entries(t).filter(([i])=>i!==n.timestamp.name)),[n.start.name]:t[n.start.name]??{$lte:e},[n.end.name]:t[n.end.name]??{$or:[{$exists:!1},{$gte:e}]}}};export{f as applyLifecycleQuery};

package/dist/planner/semantics/lifecycle/rule.d.ts

@@ -0,0 +1,2 @@
+import type { PlannerSemanticRule } from '../registry';
+export declare const lifecycleSemanticRule: PlannerSemanticRule;

package/dist/planner/semantics/lifecycle/rule.js

@@ -0,0 +1 @@
+import{resolveLifecycleProperties as p}from"./classification.js";import{applyLifecycleQuery as c}from"./query-policy.js";const l={name:"lifecycle",resolveQuery({logicform:e,schema:r,query:o}){const t=p(r);return!t||e.groupby?.some(i=>typeof i.pred=="string"&&i.pred===t.timestamp.name)?o:c(o,t)},resolveProjection({schema:e,outputProperty:r}){if(p(e))return{outputProperty:{...r,temporal:{kind:"lifecycle"}}}}};export{l as lifecycleSemanticRule};

package/dist/planner/semantics/observation/classification.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedSemanticProperty, ResolvedSemanticSchema } from '../../../semantic-types/index';
+export declare const isObservationProperty: (property: ResolvedSemanticProperty | undefined, schema?: Pick<ResolvedSemanticSchema, "temporalSemantics">) => boolean;
+export declare const observationProperties: (schema: Pick<ResolvedSemanticSchema, "properties" | "temporalSemantics">) => readonly ResolvedSemanticProperty[];

package/dist/planner/semantics/observation/classification.js

@@ -0,0 +1 @@
+const o=(t,e)=>!!(t&&e?.temporalSemantics==="snapshot"&&t.type!=="timestamp");export{o as isObservationProperty};

package/dist/planner/semantics/observation/index.d.ts

@@ -0,0 +1,4 @@
+export { isObservationProperty, observationProperties, } from './classification';
+export { resolveObservationOperatorPolicy, type ObservationOperatorPolicy, } from './operator-policy';
+export type { ObservationOperator, ObservationTemporalMetadata, } from './types';
+export { observationSemanticRule } from './rule';

package/dist/planner/semantics/observation/operator-policy.d.ts

@@ -0,0 +1,11 @@
+import type { PredItemType } from '../../../logicform-types';
+import type { OperatorDefinition } from '../../../operators/index';
+declare const periodBoundaryOperator = "$periodBoundary";
+export interface ObservationOperatorPolicy {
+    readonly operator: typeof periodBoundaryOperator;
+    readonly boundary: 'start' | 'end';
+    readonly implicit: boolean;
+}
+/** Resolves the point-selection policy without changing the caller LogicForm. */
+export declare const resolveObservationOperatorPolicy: (pred: Pick<PredItemType, "operator" | "args">, operator?: OperatorDefinition) => ObservationOperatorPolicy;
+export {};

package/dist/planner/semantics/observation/operator-policy.js

@@ -0,0 +1 @@
+import{SemanticDBError as i}from"../../../errors.js";const e="$periodBoundary",n=(t,r)=>{const o=r?.observationPolicy?.({pred:t});if(o)return{operator:e,...o};if(r?.kind==="aggregate")throw new i("OBSERVATION_REQUIRES_PERIOD_BOUNDARY",`Observation metrics must use ${e}; ${r.name} describes a time range`,{operator:r.name});return{operator:e,boundary:"end",implicit:!0}};export{n as resolveObservationOperatorPolicy};

package/dist/planner/semantics/observation/rule.d.ts

@@ -0,0 +1,2 @@
+import type { PlannerSemanticRule } from '../registry';
+export declare const observationSemanticRule: PlannerSemanticRule;

package/dist/planner/semantics/observation/rule.js

@@ -0,0 +1 @@
+import{isObservationProperty as p}from"./classification.js";import{resolveObservationOperatorPolicy as s}from"./operator-policy.js";const b={name:"observation",resolveProjection({pred:r,schema:e,sourceProperty:o,outputProperty:t,operator:n}){if(!o||!p(o,e))return;const i=o,a=s(r,n);return{outputProperty:{...t,temporal:{kind:"period-boundary",boundary:a.boundary,sourceProperty:i.name}}}}};export{b as observationSemanticRule};

package/dist/planner/semantics/observation/types.d.ts

@@ -0,0 +1,3 @@
+import type { ResultPropertyTemporalMetadata } from '../../../operators/index';
+export type ObservationTemporalMetadata = ResultPropertyTemporalMetadata;
+export type ObservationOperator = '$periodBoundary';

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

@@ -0,0 +1,2 @@
+import { PlannerSemanticRegistry } from './registry';
+export declare const createPlannerSemanticRegistry: () => PlannerSemanticRegistry;

package/dist/planner/semantics/registry-defaults.js

@@ -0,0 +1 @@
+import{observationSemanticRule as e}from"./observation/rule.js";import{lifecycleSemanticRule as r}from"./lifecycle/rule.js";import{PlannerSemanticRegistry as t}from"./registry.js";const i=()=>new t([e,r]);export{i as createPlannerSemanticRegistry};