semanticdb-v2 2.0.0-alpha.1

package/README.md

@@ -0,0 +1,448 @@
+# SemanticDB
+
+SemanticDB translates its own LogicForm into SQL and executes it on a single core compute layer.
+Callers provide schemas, schema mappings, operators, and database connection information.
+SemanticDB creates the matching provider and owns its connection lifecycle.
+
+## Public API
+
+```ts
+import { Logicform } from 'semanticdb-v2';
+import { SchemaMappingRegistry } from 'semanticdb-v2';
+
+const schemaMappings = new SchemaMappingRegistry([
+  {
+    schemaId: 'sales',
+    connectionId: 'analytics',
+    source: 'analytics.sales_detail',
+    freshness: { mode: 'ttl', ttlSeconds: 300 },
+  },
+]);
+
+const response = await Logicform.execute(
+  {
+    version: '2.0',
+    schema: 'sales',
+    groupby: [{
+      operator: '$dateBucket',
+      pred: 'order_date',
+      args: { granularity: 'month' },
+    }],
+    preds: [{ operator: '$sum', pred: 'amount', name: 'revenue' }],
+  },
+  {
+    connections: [{
+      id: 'analytics',
+      kind: 'clickhouse',
+      url: 'http://localhost:8123',
+      username: 'default',
+      password: process.env.CLICKHOUSE_PASSWORD,
+      database: 'analytics',
+    }],
+    schemas,
+    schemaMappings,
+    operators,
+    onProgress(event) {
+      console.log(event.stage, event);
+    },
+  },
+);
+```
+
+Every executable LogicForm, including LogicForms used as subqueries, must declare `version`. This
+SDK accepts semantic versions greater than or equal to `2.0`; missing, malformed, or older versions
+fail with `UNSUPPORTED_LOGICFORM_VERSION` before Schema resolution or database access. A relation
+query shaped as `{ schema, query }` is part of its parent LogicForm and inherits the parent's version.
+
+PredItems without an explicit `name` receive a human-readable name during normalization. Generated
+names default to Chinese; pass `locale: 'en-US'` in `ExecuteOptions` for the built-in English
+names. Every operator owns its localized default names and receives the requested locale directly:
+
+```ts
+operators.register({
+  name: '$weightedAverage',
+  defaultName: ({ operandName, locale }) => locale.toLowerCase().startsWith('en')
+    ? `Weighted average of ${operandName}`
+    : `${operandName}加权平均值`,
+  kind: 'aggregate',
+  toSQL: ({ column }) => `weighted_avg(${column})`,
+});
+```
+
+The same locale applies to `preds`, `groupby`, nested expressions, custom-function components,
+and entity-population queries. A PredItem's normalized `query` is included in its
+generated name, for example `门店为上海的销售额合计`. Operator-specific `args` also participate
+through each operator's `defaultName()`; period operators distinguish同比、环比 and other offsets.
+An explicitly authored `name` is preserved unchanged.
+
+`entity_id` identifies one entity by `hierarchy.property` on hierarchy Schemas and by the unique
+`type: 'ID'` property on other Schemas. Normalization adds that identity filter unless the query
+already contains one, in which case the explicit query wins. The legacy value `placeholder` is
+preserved as entity context but never becomes a SQL filter. This also applies to relation queries
+shaped as `{ schema, query, entity_id }`. `representation` is presentation metadata for frontend
+consumers and does not change normalization, planning, or execution. See
+[Hierarchy plugin](docs/hierarchy-plugin.md) for Schema configuration, `$hierarchyLevel`, legacy
+compatibility, and its plugin boundary.
+
+Compound capabilities can be supplied by external packages through `ExecuteOptions.plugins`.
+Plugins may own Schema metadata, legacy conversion, `entity_id` selection, and Operators while
+remaining scoped to one execution. See [Register an external plugin](docs/register-plugin.md).
+
+Parent-child Schemas may declare `parentProperty`. `$recursive` filters a property to a root node and
+all descendants; object properties infer the tree Schema from `ref`. MySQL, Doris, StarRocks, and
+PostgreSQL compile this as a parameterized recursive CTE.
+
+Top-level projections may set `schema` to read metrics from another registered Schema. SemanticDB
+splits those projections into independent provider queries, aligns shared query/groupby dimensions,
+and merges rows by the group keys before applying `having`, `sort`, `limitBy`, and pagination.
+
+The progress stream emits `started`, `validated`, `normalized`, `planned`, `lineage`,
+`compiled`, `executing`, `hydrating`, `result`, and `completed`. Every event includes a cumulative
+`partialResult`; for example, `compiled` includes `sqls`, while `result` includes `sqls` and
+`result`. Failures emit `failed` before rejection and preserve the partial result accumulated so
+far.
+
+Each `sqls` item keeps the executable statement and its parameters together, plus a complete
+SQL string for diagnostics:
+
+```ts
+interface ExecutedSql {
+  type: 'semantic-resolution' | 'computation';
+  sql: string;
+  parameters: readonly unknown[];
+  displaySql: string;
+}
+```
+
+`semantic-resolution` identifies supporting SQL used to resolve semantic input or output, such as
+latest-data-date lookup and object entity population. `computation` identifies SQL that calculates
+the requested LogicForm result. `sqls` includes every physical SQL involved in the execution; an
+entry remains visible when its result is served by the query cache.
+
+Providers execute only parameterized `sql + parameters`; SemanticDB never executes `displaySql`.
+Because `displaySql` contains literal values and may expose sensitive data, use it only in trusted
+debugging and observability channels.
+
+### Permissions
+
+Pass table, row, and column permissions together through `ExecuteOptions.permissions`:
+
+```ts
+import type { Permissions } from 'semanticdb-v2';
+
+const permissions = {
+  orders: {
+    rowPermissions: {
+      订单状态: { $ne: '已删除' },
+      所属部门: {
+        schema: 'departments',
+        query: {
+          部门名称: { $in: ['华东销售部', '华南销售部'] },
+        },
+      },
+    },
+    columnPermissions: {
+      whitelist: ['ID', '订单状态', '销售额', '所属部门', 'createdAt'],
+    },
+  },
+  departments: {
+    rowPermissions: {
+      部门名称: { $in: ['华东销售部', '华南销售部'] },
+    },
+    columnPermissions: {
+      whitelist: ['ID', '部门名称'],
+    },
+  },
+} satisfies Permissions;
+
+await Logicform.execute(logicform, {
+  schemas,
+  schemaMappings,
+  connection,
+  permissions,
+});
+```
+
+When `permissions` is omitted, execution remains unrestricted. When it is present, its Schema keys
+are the table allowlist. `rowPermissions` is always combined with the caller query using `AND`,
+including internal latest-data-date queries, related-table joins, and object population queries.
+`columnPermissions.whitelist` accepts property names or IDs and restricts caller projections,
+filters, grouping, operator inputs, and relation paths. A row policy may still use a non-whitelisted
+column as an internal filter. If an ID is not whitelisted, SemanticDB generates the executor-owned
+result-row `_id` instead of exposing the physical ID as that identity.
+
+### Custom composite metrics
+
+Pass legacy-compatible `genComponents`, `mergeComponents`, and `genMergeSQL` definitions through
+`ExecuteOptions.customFunctions`. JavaScript merge supports async callbacks; SQL merge compiles
+components into CTEs. `Logicform.genComponents()` expands the same definitions into an indicator
+tree without accessing a database. Cross-Schema components independently pass table, row, and
+column permissions. See [Custom composite metrics](docs/custom-functions.md) for the complete
+contract, merge-mode selection, and trusted function-string behavior.
+
+The root entry point accepts a `connections` array of `DatabaseConnection` items. Every item has a unique `id`; set `kind` to `mysql`,
+`doris`, `starrocks`, `clickhouse`, `snowflake`, `oracle`, or `postgresql`, then add that driver's
+native connection fields directly on the item. Each Schema Mapping selects an item through
+`connectionId`. SemanticDB lazily creates and reuses the matching internal provider. Call
+`await Logicform.close()` during application shutdown to close every connection pool and session.
+
+### PostgreSQL connection
+
+PostgreSQL uses the official `pg` pool and PostgreSQL-native `$1`, `$2` parameters:
+
+```ts
+await Logicform.execute(logicform, {
+  schemas,
+  schemaMappings,
+  connections: [{
+    id: 'primary',
+    kind: 'postgresql',
+    connectionString: process.env.DATABASE_URL,
+  }],
+});
+```
+
+### Doris and StarRocks connections
+
+Doris and StarRocks expose MySQL-compatible protocols, so both use `mysql2` connection fields:
+
+```ts
+const doris = { id: 'doris-main', kind: 'doris', host, port, user, password, database } as const;
+const starrocks = { id: 'starrocks-main', kind: 'starrocks', host, port, user, password, database } as const;
+```
+
+They are independent providers with distinct `kind` values. Their currently compatible identifier,
+pagination, date, aggregate, string, regex, parameter, and display-SQL behavior comes from a shared
+MySQL-compatible SQL helper. Database-specific differences should be implemented by overriding the
+corresponding internal dialect capability.
+
+### Snowflake connection
+
+Snowflake connection fields are passed to the official `snowflake-sdk`:
+
+```ts
+await Logicform.execute(logicform, {
+  schemas,
+  schemaMappings,
+  connections: [{
+    id: 'warehouse',
+    kind: 'snowflake',
+    account: process.env.SNOWFLAKE_ACCOUNT,
+    username: process.env.SNOWFLAKE_USERNAME,
+    password: process.env.SNOWFLAKE_PASSWORD,
+    warehouse: process.env.SNOWFLAKE_WAREHOUSE,
+    database: process.env.SNOWFLAKE_DATABASE,
+    schema: process.env.SNOWFLAKE_SCHEMA,
+    role: process.env.SNOWFLAKE_ROLE,
+  }],
+});
+```
+
+### Oracle connection
+
+Oracle uses the official `oracledb` driver in Thin mode and does not require Oracle Client
+libraries:
+
+```ts
+await Logicform.execute(logicform, {
+  schemas,
+  schemaMappings,
+  connections: [{
+    id: 'oracle-main',
+    kind: 'oracle',
+    user: process.env.ORACLE_USER,
+    password: process.env.ORACLE_PASSWORD,
+    connectString: process.env.ORACLE_CONNECT_STRING,
+  }],
+});
+```
+
+### Semantic types
+
+`Schema.properties[].type` is an extensible semantic type. SemanticDB supplies the built-in
+types and derives each property's `primal_type` while resolving the Schema. A supplied
+`primal_type` must match the registered type. `isArray` describes the value container and
+defaults to `false`; for example, tags are represented as `type: 'category', isArray: true`.
+
+```ts
+import { createSemanticTypeRegistry, Logicform } from 'semanticdb-v2';
+
+const semanticTypes = createSemanticTypeRegistry();
+semanticTypes.register({
+  name: 'email',
+  primalType: 'string',
+  validateProperty(property) {
+    if (property.isArray) throw new Error('email must be scalar');
+  },
+});
+
+await Logicform.execute(logicform, { schemas, schemaMappings, connection, semanticTypes });
+```
+
+Registries are instance-local. Applications can reuse one registry across executions without
+introducing global mutable registration.
+
+See [Register a custom SemanticType](docs/register-semantic-type.md) for the complete external
+registration API, validation lifecycle, and Schema example.
+
+### SQL-derived properties
+
+A Property can map to a trusted, provider-specific SQL expression instead of one physical column:
+
+```ts
+{
+  id: 'net_amount',
+  name: 'Net amount',
+  type: 'currency',
+  udf: { sql: 'COALESCE(amount, 0) - COALESCE(discount, 0)' },
+}
+```
+
+`udf.sql` is used consistently for projection, filtering, grouping, operator input, and relation
+keys. In an event Schema, `$TS` expands to the quoted physical timestamp column. The expression is
+trusted model metadata, must match the active provider dialect, and cannot contain statements,
+comments, or parameter placeholders. Property UDFs do not support the legacy `function` or
+`dependencies` fields; application-side computed values belong outside this query SDK.
+
+### Query cache
+
+All compiled provider queries, including the internal latest-data-date query, can share one
+caller-owned query cache. Redis is published from `semanticdb-v2/cache/redis`; cache identity
+includes namespace, provider, SQL, and parameters. Physical expiration belongs to each Schema
+mapping's `freshness` policy. See [Query cache and Redis](docs/query-cache.md).
+
+When Redis is shared with other applications, pass an application-specific key prefix:
+
+```ts
+import { createRedisQueryCache } from 'semanticdb-v2/cache/redis';
+
+const cache = await createRedisQueryCache({
+  url: process.env.REDIS_URL,
+  keyPrefix: process.env.REDIS_KEY_PREFIX,
+});
+```
+
+Operators convert SQL expressions and declare the semantic type of their single output column. See
+[LogicForm operators](docs/operators.md) for the built-in syntax and composition rules, and
+[Register an operator](docs/register-operator.md) for the extension contract.
+
+Schema and Property metadata use only `id`; neither defines `sid`. See the
+[breaking-change migration checklist](docs/breaking-change-schema-property-id.md) before
+updating an upstream Schema producer or downstream consumer.
+
+## Architecture
+
+The execution pipeline is split into explicit layers:
+
+```text
+LogicForm
+  -> normalizer  validates and canonicalizes the request
+  -> planner     builds a provider-independent LogicalPlan and lineage
+  -> compiler    renders the LogicalPlan through the provider contract
+  -> physical    executes SQL through a concrete database provider
+```
+
+`executor` is the application layer that coordinates the pipeline and publishes progress
+events. `semantic-types` validates and resolves Schema property types before normalization;
+`schema` owns Schema lookup and logical field mapping, while `schema-mappings` owns the
+physical source bindings. Each layer owns its types, while the provider contract and concrete
+database adapters live in `physical`. Physical adapters do not own normalization,
+planning, or compilation rules.
+
+After physical execution, the executor's Result Hydrator runs SemanticType result hooks and
+batch-populates directly selected object properties. See [Result Hydrator](docs/result-hydrator.md).
+
+Each layer exposes an `index.ts` boundary. Cross-layer imports should use that boundary rather
+than reach into another layer's implementation files.
+
+See [LogicForm to SQL pipeline](docs/logicform-to-sql-pipeline.md) for the responsibility and
+input/output contract of every stage.
+
+The [legacy test migration report](docs/legacy-test-migration.md) records how the old project's
+test suite maps to this rewrite, including migrated behavior and explicit non-migration reasons.
+
+Scalar object properties can be traversed with paths such as `门店_城市`. The planner resolves
+these paths into provider-independent LEFT JOIN plans. See
+[Object relations and LEFT JOIN](docs/object-relations.md).
+
+## MySQL test configuration
+
+The test suite includes a real MySQL execution test. Configure it through the project `.env`:
+
+```bash
+cp .env.example .env
+npm test
+```
+
+The supported variables are `TEST_MYSQL_HOST`, `TEST_MYSQL_PORT`, `TEST_MYSQL_USER`,
+`TEST_MYSQL_PASSWORD`, and `TEST_MYSQL_DATABASE`. The test creates an isolated table, verifies
+the returned aggregates, and removes the table afterward. If `TEST_MYSQL_DATABASE` is omitted,
+it creates and reuses the isolated `semanticdb_v2_integration` database.
+
+## PostgreSQL test configuration
+
+Set `TEST_POSTGRESQL_URL` in `.env` to enable the real PostgreSQL integration test. It creates an
+isolated table in the configured database, verifies parameterized execution and LogicForm
+aggregation, and removes the table afterward.
+
+## Redis test configuration
+
+The test suite also includes a real Redis integration test. Configure the connection in `.env`:
+
+```bash
+REDIS_URL=redis://localhost:6379/0
+REDIS_KEY_PREFIX=semanticdb-v2
+```
+
+`REDIS_KEY_PREFIX` is the application namespace and should be unique when Redis is shared. The
+test appends its own process ID and UUID, verifies real expiry and source-index behavior, and
+removes its keys afterward. It is skipped only when `REDIS_URL` is absent; a configured but
+unreachable Redis server fails the test.
+
+## Snowflake test configuration
+
+The ordinary test suite includes a real Snowflake provider and LogicForm execution test. Uncomment
+and fill the `TEST_SNOWFLAKE_*` variables in `.env`; `ACCOUNT`, `USERNAME`, `PASSWORD`, `WAREHOUSE`,
+and `DATABASE` are required, while `SCHEMA` and `ROLE` are optional. The test only reads
+`INFORMATION_SCHEMA.TABLES`. It is skipped when the required configuration is absent and fails when
+configured credentials cannot connect.
+
+## Oracle test configuration
+
+The ordinary test suite includes real Oracle provider and LogicForm execution tests. Uncomment
+and fill `TEST_ORACLE_USER`, `TEST_ORACLE_PASSWORD`, and `TEST_ORACLE_CONNECT_STRING` in `.env`.
+Thin mode is the default. To test Thick mode, set `TEST_ORACLE_MODE=thick` and optionally set
+`TEST_ORACLE_CLIENT_LIB_DIR` and `TEST_ORACLE_CONFIG_DIR`. The tests query Oracle's `DUAL` table;
+they are skipped when required connection values are absent and fail when configured Oracle
+credentials, client libraries, or connectivity are invalid.
+
+## Debugging the pipeline
+
+[`debug/debug.ts`](debug/debug.ts) prepares an isolated MySQL table and executes one complete
+LogicForm pipeline against it. It uses the same `TEST_MYSQL_*` variables from `.env` as the
+integration tests.
+
+In Trae or VS Code, open **Run and Debug**, select **Debug SemanticDB pipeline**, set a breakpoint
+on the `Logicform.execute()` call or inside `src/`, and start debugging. The same entry point can
+be run without the IDE:
+
+```bash
+npm run debug
+```
+
+## Current scope
+
+- ClickHouse, MySQL, Oracle, and Snowflake core compute providers
+- Projections, conditional aggregates, and `$sum`, `$count`, `$countDistinct`, `$avg`, `$min`, `$max`
+- Structured arithmetic, share-of-total, period comparison, period-boundary, date-bucket,
+  cumulative period, trusted SQL expression, string, case, and window operators
+- Declarative operators
+- Grouping with hour/day/week/month/quarter/year time buckets
+- `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$exists`, `$contains`, `$regex`
+- `$and` and `$or`, HAVING, sorting, row-count and percentage pagination, and per-group `limitBy`
+- Query-level and output-column lineage
+- Multi-level scalar and array object relation paths, array groupby, and batched entity population
+- Nested `from` LogicForms compiled as parameterized derived tables
+
+Exports and metadata persistence are intentionally deferred. Directly selected array-object
+properties are populated without expanding the root result rows.

package/dist/cache/expiry.d.ts

@@ -0,0 +1,5 @@
+import type { SourceFreshnessPolicy } from '../schema-mappings/index';
+export declare const nextDailyExpiration: (policy: Extract<SourceFreshnessPolicy, {
+    readonly mode: "daily";
+}>, now: Date) => Date;
+export declare const resolveQueryExpiration: (policies: readonly SourceFreshnessPolicy[], now: Date) => Date | undefined;

package/dist/cache/expiry.js

@@ -0,0 +1 @@
+import{parseDailyExpireAt as s}from"../schema-mappings/freshness.js";const i=(n,o)=>{const r=new Intl.DateTimeFormat("en-US",{timeZone:o,year:"numeric",month:"2-digit",day:"2-digit",hour:"2-digit",minute:"2-digit",second:"2-digit",hourCycle:"h23"}).formatToParts(n),e=a=>Number(r.find(t=>t.type===a)?.value);return{year:e("year"),month:e("month"),day:e("day"),hour:e("hour"),minute:e("minute"),second:e("second")}},m=(n,o)=>{const r=Date.UTC(n.year,n.month-1,n.day,n.hour,n.minute,n.second);let e=r;for(let a=0;a<3;a+=1){const t=i(new Date(e),o),u=Date.UTC(t.year,t.month-1,t.day,t.hour,t.minute,t.second);e+=r-u}return new Date(e)},d=(n,o)=>{const r=s(n.expireAt);if(!r)throw new Error(`Invalid daily expiration time: ${n.expireAt}`);if(!n.timeZone){const t=new Date(o);return t.setHours(r.hour,r.minute,r.second,0),t.getTime()<=o.getTime()&&t.setDate(t.getDate()+1),t}const e=i(o,n.timeZone);let a=m({...e,...r},n.timeZone);if(a.getTime()<=o.getTime()){const t=new Date(Date.UTC(e.year,e.month-1,e.day+1));a=m({year:t.getUTCFullYear(),month:t.getUTCMonth()+1,day:t.getUTCDate(),...r},n.timeZone)}return a},h=(n,o)=>{const r=n.flatMap(e=>e.mode==="manual"?[]:e.mode==="ttl"?[new Date(o.getTime()+e.ttlSeconds*1e3)]:[d(e,o)]);return r.length===0?void 0:new Date(Math.min(...r.map(e=>e.getTime())))};export{d as nextDailyExpiration,h as resolveQueryExpiration};

package/dist/cache/identity.d.ts

@@ -0,0 +1,3 @@
+import type { QueryCacheIdentity } from './types';
+export declare const queryCacheIdentityHash: (identity: QueryCacheIdentity) => string;
+export declare const sourceCacheIndexHash: (namespace: string, source: string) => string;

package/dist/cache/identity.js

@@ -0,0 +1 @@
+import{createHash as s}from"node:crypto";const n=e=>e===void 0?{type:"undefined"}:typeof e=="bigint"?{type:"bigint",value:e.toString()}:typeof e=="number"&&!Number.isFinite(e)?{type:"number",value:String(e)}:e instanceof Date?{type:"date",value:e.toISOString()}:Array.isArray(e)?e.map(n):e&&typeof e=="object"?Object.fromEntries(Object.entries(e).sort(([r],[t])=>r.localeCompare(t)).map(([r,t])=>[r,n(t)])):e,i=e=>s("sha256").update(JSON.stringify(n(e))).digest("hex"),o=e=>i({namespace:e.namespace,provider:e.provider,sql:e.sql,parameters:e.parameters}),p=(e,r)=>i({namespace:e,source:r});export{o as queryCacheIdentityHash,p as sourceCacheIndexHash};

package/dist/cache/index.d.ts

@@ -0,0 +1,3 @@
+export { nextDailyExpiration, resolveQueryExpiration, } from './expiry';
+export { queryCacheIdentityHash, sourceCacheIndexHash, } from './identity';
+export type { QueryCache, QueryCacheExecutionOptions, QueryCacheIdentity, QueryCacheWriteOptions, } from './types';

package/dist/cache/redis-query-cache.d.ts

@@ -0,0 +1,37 @@
+import type { QueryCache, QueryCacheIdentity, QueryCacheWriteOptions } from './types';
+import type { DataRow } from '../physical/index';
+export interface RedisMultiLike {
+    set(key: string, value: string, options?: {
+        readonly PXAT: number;
+    }): this;
+    zRemRangeByScore(key: string, min: number, max: number): this;
+    zAdd(key: string, entry: {
+        readonly score: number;
+        readonly value: string;
+    }): this;
+    exec(): Promise<unknown>;
+}
+export interface RedisQueryCacheClient {
+    get(key: string): Promise<string | null>;
+    multi(): RedisMultiLike;
+    zRange(key: string, start: number, stop: number): Promise<string[]>;
+    del(keys: string | string[]): Promise<number>;
+    close(): Promise<unknown>;
+}
+export interface RedisQueryCacheOptions {
+    readonly url?: string;
+    readonly keyPrefix?: string;
+}
+/** Redis implementation of the provider-independent QueryCache contract. */
+export declare class RedisQueryCache implements QueryCache {
+    #private;
+    constructor(client: RedisQueryCacheClient, options?: {
+        readonly keyPrefix?: string;
+        readonly ownsClient?: boolean;
+    });
+    get(identity: QueryCacheIdentity): Promise<readonly DataRow[] | undefined>;
+    set(identity: QueryCacheIdentity, rows: readonly DataRow[], options: QueryCacheWriteOptions): Promise<void>;
+    invalidateSource(namespace: string, source: string): Promise<void>;
+    close(): Promise<void>;
+}
+export declare const createRedisQueryCache: (options?: RedisQueryCacheOptions) => Promise<RedisQueryCache>;

package/dist/cache/redis-query-cache.js

@@ -0,0 +1 @@
+import{createClient as y}from"redis";import{queryCacheIdentityHash as d,sourceCacheIndexHash as f}from"./identity.js";import{deserializeQueryRows as w,serializeQueryRows as x}from"./serialization.js";const m=Number.MAX_SAFE_INTEGER;class u{#e;#t;#s;constructor(e,t={}){this.#e=e,this.#t=t.keyPrefix??"semanticdb:cache",this.#s=t.ownsClient??!1}#r(e){return`${this.#t}:query:${d(e)}`}#i(e,t){return`${this.#t}:source:${f(e,t)}`}async get(e){const t=await this.#e.get(this.#r(e));if(t!==null)return w(t)}async set(e,t,i){const s=this.#r(e),a=x(t),c=i.expiresAt?.getTime(),l=c??m,n=this.#e.multi();c===void 0?n.set(s,a):n.set(s,a,{PXAT:c});for(const h of new Set(i.sources)){const o=this.#i(e.namespace,h);n.zRemRangeByScore(o,0,Date.now()),n.zAdd(o,{score:l,value:s})}await n.exec()}async invalidateSource(e,t){const i=this.#i(e,t),s=await this.#e.zRange(i,0,-1);s.length>0&&await this.#e.del(s),await this.#e.del(i)}async close(){this.#s&&await this.#e.close()}}const C=async(r={})=>{const e=y(r.url?{url:r.url}:{});return e.on("error",()=>{}),await e.connect(),new u(e,{...r.keyPrefix?{keyPrefix:r.keyPrefix}:{},ownsClient:!0})};export{u as RedisQueryCache,C as createRedisQueryCache};

package/dist/cache/serialization.d.ts

@@ -0,0 +1,3 @@
+import type { DataRow } from '../physical/index';
+export declare const serializeQueryRows: (rows: readonly DataRow[]) => string;
+export declare const deserializeQueryRows: (serialized: string) => DataRow[] | undefined;

package/dist/cache/serialization.js

@@ -0,0 +1 @@
+const n=e=>e===void 0?{type:"undefined"}:typeof e=="bigint"?{type:"bigint",value:e.toString()}:typeof e=="number"&&!Number.isFinite(e)?{type:"number",value:String(e)}:e instanceof Date?{type:"date",value:e.toISOString()}:Array.isArray(e)?{type:"array",value:e.map(n)}:e&&typeof e=="object"?{type:"object",value:Object.entries(e).map(([r,t])=>[r,n(t)])}:e,i=e=>{if(e===null||typeof e!="object")return e;switch(e.type){case"undefined":return;case"bigint":return BigInt(e.value);case"number":return Number(e.value);case"date":return new Date(e.value);case"array":return e.value.map(i);case"object":return Object.fromEntries(e.value.map(([r,t])=>[r,i(t)]))}},s=e=>JSON.stringify(n(e)),o=e=>{const r=i(JSON.parse(e));if(!(!Array.isArray(r)||r.some(t=>!t||typeof t!="object"||Array.isArray(t))))return r};export{o as deserializeQueryRows,s as serializeQueryRows};

package/dist/cache/types.d.ts

@@ -0,0 +1,27 @@
+import type { CoreComputeProvider, DataRow, SqlParameters } from '../physical/index';
+export interface QueryCacheIdentity {
+    readonly namespace: string;
+    readonly provider: CoreComputeProvider['kind'];
+    readonly sql: string;
+    readonly parameters: SqlParameters;
+}
+export interface QueryCacheWriteOptions {
+    readonly sources: readonly string[];
+    /** Omitted for manually invalidated entries. */
+    readonly expiresAt?: Date;
+}
+/**
+ * Cross-execution cache for compiled provider queries. Implementations must
+ * treat SQL parameters and the data-source namespace as part of the identity.
+ */
+export interface QueryCache {
+    get(identity: QueryCacheIdentity): Promise<readonly DataRow[] | undefined>;
+    set(identity: QueryCacheIdentity, rows: readonly DataRow[], options: QueryCacheWriteOptions): Promise<void>;
+    invalidateSource(namespace: string, source: string): Promise<void>;
+    close(): Promise<void>;
+}
+export interface QueryCacheExecutionOptions {
+    readonly store: QueryCache;
+    /** Isolates tenants and physical data sources that can produce identical SQL. */
+    readonly namespace: string;
+}

package/dist/calendar/constants.d.ts

@@ -0,0 +1,7 @@
+/** Fixed internal physical table names. These are intentionally not configurable yet. */
+export declare const CALENDAR_DATES_TABLE = "semanticdb_calendar_dates";
+export declare const CALENDAR_RELATIONS_TABLE = "semanticdb_calendar_relations";
+export declare const CALENDAR_SYSTEM_SCHEMA_IDS: {
+    readonly dates: "__semanticdb_calendar_dates";
+    readonly relations: "__semanticdb_calendar_relations";
+};

package/dist/calendar/constants.js

@@ -0,0 +1 @@
+const _="semanticdb_calendar_dates",a="semanticdb_calendar_relations",e={dates:"__semanticdb_calendar_dates",relations:"__semanticdb_calendar_relations"};export{_ as CALENDAR_DATES_TABLE,a as CALENDAR_RELATIONS_TABLE,e as CALENDAR_SYSTEM_SCHEMA_IDS};

package/dist/calendar/index.d.ts

@@ -0,0 +1,6 @@
+export { CALENDAR_DATES_TABLE, CALENDAR_RELATIONS_TABLE, CALENDAR_SYSTEM_SCHEMA_IDS, } from './constants';
+export { resolveCalendarPeriod, resolveCalendarPeriodFromStore, selectCalendarDates, } from './resolver';
+export type { CalendarRelationStore } from './resolver';
+export { ProviderCalendarRelationStore } from './provider-relation-store';
+export { calendarSystemSchemas } from './system-schemas';
+export type { CalendarAlignment, CalendarComparison, CalendarDateRow, CalendarRelation, CalendarRelationRow, ResolvedCalendarPeriod, } from './types';

package/dist/calendar/provider-relation-store.d.ts

@@ -0,0 +1,9 @@
+import type { CoreComputeProvider } from '../physical/index';
+import type { CalendarRelationStore } from './resolver';
+import type { CalendarComparison, CalendarRelationRow } from './types';
+/** Loads calendar mappings from the fixed internal relations table. */
+export declare class ProviderCalendarRelationStore implements CalendarRelationStore {
+    private readonly provider;
+    constructor(provider: CoreComputeProvider);
+    loadRelations(currentDateIds: readonly (string | number)[], comparison: CalendarComparison): Promise<readonly CalendarRelationRow[]>;
+}

package/dist/calendar/provider-relation-store.js

@@ -0,0 +1 @@
+import{CALENDAR_RELATIONS_TABLE as s}from"./constants.js";const g=["source_date_id","target_date_id","calendar","grain","relation","relation_key"];class _{provider;constructor(t){this.provider=t}async loadRelations(t,i){if(t.length===0)return[];const n=[...t,i.calendar,i.grain,i.relation];i.key!==void 0&&n.push(i.key);const l=t.map((e,d)=>this.provider.parameter(d,e)),a=e=>this.provider.parameter(e,n[e]),r=e=>this.provider.quoteIdentifier(e),o=[`${r("source_date_id")} IN (${l.join(", ")})`,`${r("calendar")} = ${a(t.length)}`,`${r("grain")} = ${a(t.length+1)}`,`${r("relation")} = ${a(t.length+2)}`];return i.key!==void 0&&o.push(`${r("relation_key")} = ${a(t.length+3)}`),(await this.provider.execute({sql:`SELECT ${g.map(r).join(", ")} FROM ${r(s)} WHERE ${o.join(" AND ")}`,parameters:n})).map(e=>({sourceDateId:e.source_date_id,targetDateId:e.target_date_id,calendar:String(e.calendar),grain:String(e.grain),relation:String(e.relation),...typeof e.relation_key=="string"||typeof e.relation_key=="number"?{key:String(e.relation_key)}:{}}))}}export{_ as ProviderCalendarRelationStore};

package/dist/calendar/resolver.d.ts

@@ -0,0 +1,10 @@
+import type { CalendarComparison, CalendarDateRow, CalendarRelationRow, ResolvedCalendarPeriod } from './types';
+export interface CalendarRelationStore {
+    loadRelations(currentDateIds: readonly (string | number)[], comparison: CalendarComparison): Promise<readonly CalendarRelationRow[]>;
+}
+/** Resolve current natural-day IDs through an explicit calendar relation. */
+export declare const resolveCalendarPeriod: (currentDateIds: readonly (string | number)[], comparison: CalendarComparison, relations: readonly CalendarRelationRow[]) => ResolvedCalendarPeriod;
+/** Async resolver boundary used by the executor; storage remains provider-owned. */
+export declare const resolveCalendarPeriodFromStore: (currentDateIds: readonly (string | number)[], comparison: CalendarComparison, store: CalendarRelationStore) => Promise<ResolvedCalendarPeriod>;
+/** Select natural days by calendar coordinates before resolving a relation. */
+export declare const selectCalendarDates: (rows: readonly CalendarDateRow[], predicate: Partial<Pick<CalendarDateRow, "calendar" | "grain" | "periodKey" | "relativeDay">>) => readonly (string | number)[];

package/dist/calendar/resolver.js

@@ -0,0 +1 @@
+const l=n=>`${typeof n}:${String(n)}`,p=(n,t)=>{const r=typeof n=="number"?n:Number(n),o=typeof t=="number"?t:Number(t);return Number.isFinite(r)&&Number.isFinite(o)?r-o:String(n).localeCompare(String(t))},m=(n,t,r)=>{const o=r.filter(e=>e.calendar===t.calendar&&e.grain===t.grain&&e.relation===t.relation&&(t.key===void 0||e.key===t.key)),d=new Map(o.map(e=>[l(e.sourceDateId),e])),b=n.flatMap(e=>{const a=d.get(l(e))?.targetDateId;return a==null?[]:[a]}),f=[...new Map(b.map(e=>[l(e),e])).values()].sort(p),s=[];for(const e of f){const a=s[s.length-1];if(a&&typeof a.end=="number"&&typeof e=="number"&&e===a.end+1)a.end=e;else if(a&&String(a.end).match(/^\d{8}$/)&&String(e).match(/^\d{8}$/)){const i=Number(a.end),c=Number(e),u=new Date(Date.UTC(Math.floor(i/1e4),Math.floor(i/100)%100-1,i%100));u.setUTCDate(u.getUTCDate()+1);const g=new Date(Date.UTC(Math.floor(c/1e4),Math.floor(c/100)%100-1,c%100));if(u.getTime()===g.getTime()){a.end=e;continue}s.push({start:e,end:e})}else s.push({start:e,end:e})}return{dateIds:f,ranges:s}},y=async(n,t,r)=>m(n,t,await r.loadRelations(n,t)),D=(n,t)=>n.filter(r=>Object.entries(t).every(([o,d])=>r[o]===d)).map(r=>r.dateId);export{m as resolveCalendarPeriod,y as resolveCalendarPeriodFromStore,D as selectCalendarDates};

package/dist/calendar/system-schemas.d.ts

@@ -0,0 +1,3 @@
+import type { SemanticSchemaDraft } from '../semantic-types/index';
+/** Internal logical metadata for the fixed calendar tables. Not part of caller schemas. */
+export declare const calendarSystemSchemas: Readonly<Record<string, SemanticSchemaDraft>>;

package/dist/calendar/system-schemas.js

@@ -0,0 +1 @@
+import{CALENDAR_RELATIONS_TABLE as t,CALENDAR_SYSTEM_SCHEMA_IDS as e,CALENDAR_DATES_TABLE as i}from"./constants.js";const r={[e.dates]:{id:e.dates,name:e.dates,type:"entity",source:i,properties:[{id:"date_id",name:"date_id",type:"id",primal_type:"string"},{id:"calendar",name:"calendar",type:"string",primal_type:"string"},{id:"grain",name:"grain",type:"string",primal_type:"string"},{id:"period_key",name:"period_key",type:"string",primal_type:"string"},{id:"relative_day",name:"relative_day",type:"int",primal_type:"number"}]},[e.relations]:{id:e.relations,name:e.relations,type:"entity",source:t,properties:[{id:"source_date_id",name:"source_date_id",type:"string",primal_type:"string"},{id:"target_date_id",name:"target_date_id",type:"string",primal_type:"string"},{id:"calendar",name:"calendar",type:"string",primal_type:"string"},{id:"grain",name:"grain",type:"string",primal_type:"string"},{id:"relation",name:"relation",type:"string",primal_type:"string"},{id:"relation_key",name:"relation_key",type:"string",primal_type:"string"}]}};export{r as calendarSystemSchemas};

package/dist/calendar/types.d.ts

@@ -0,0 +1,31 @@
+export type CalendarRelation = 'previous_period' | 'next_period' | 'previous_occurrence' | 'next_occurrence';
+export type CalendarAlignment = 'same_period' | 'same_elapsed_position' | 'same_relative_day';
+export interface CalendarComparison {
+    readonly calendar: string;
+    readonly grain: string;
+    readonly relation: CalendarRelation;
+    readonly alignment?: CalendarAlignment;
+    readonly key?: string;
+}
+export interface CalendarDateRow {
+    readonly dateId: string | number;
+    readonly calendar: string;
+    readonly grain: string;
+    readonly periodKey?: string | number;
+    readonly relativeDay?: number;
+}
+export interface CalendarRelationRow {
+    readonly sourceDateId: string | number;
+    readonly targetDateId: string | number | null;
+    readonly calendar: string;
+    readonly grain: string;
+    readonly relation: CalendarRelation;
+    readonly key?: string;
+}
+export interface ResolvedCalendarPeriod {
+    readonly dateIds: readonly (string | number)[];
+    readonly ranges: readonly {
+        readonly start: string | number;
+        readonly end: string | number;
+    }[];
+}

package/dist/compatibility/index.d.ts

@@ -0,0 +1,2 @@
+export { assertNoLegacyLogicformFields, normalizeLegacyLogicform, splitLegacySchemas, } from './logicform';
+export { normalizeSchemas } from '../executor/compatibility';