@_linked/core 1.0.0-next.20260216062729 → 1.0.0-next.20260225020512

package/CHANGELOG.md

@@ -8,6 +8,12 @@
 
 ### Minor Changes
 
+- [#9](https://github.com/Semantu/linked/pull/9) [`381067b`](https://github.com/Semantu/linked/commit/381067b0fbc25f4a0446c5f8cc0eec57ddded466) Thanks [@flyon](https://github.com/flyon)! - Introduce canonical Intermediate Representation (IR) support for query and mutation objects.
+
+  - Add select-query IR pipeline stages (desugar, canonicalize, projection, alias scope, pipeline helpers) and expose `getCanonicalIR()` on select factories.
+  - Add canonical mutation IR conversion for create/update/delete query objects.
+  - Add IR documentation and parity/golden test coverage for select and mutation conversion behavior.
+
 - [#4](https://github.com/Semantu/linked/pull/4) [`c35e686`](https://github.com/Semantu/linked/commit/c35e6861600d7aa8683b4b288fc4d1dc74c4aff2) Thanks [@flyon](https://github.com/flyon)! - - Added `Shape.selectAll()` plus nested `selectAll()` support on sub-queries.
   - Added inherited property deduplication via `NodeShape.getUniquePropertyShapes()` so subclass overrides win by label and are selected once.
   - Improved `selectAll()` type inference (including nested queries) and excluded base `Shape` keys from inferred results.

package/README.md

@@ -1,7 +1,7 @@
 # @_linked/core
 Core Linked package for the query DSL, SHACL shape decorators/metadata, and package registration.
 
-Linked core gives you a type-safe, schema-parameterized query language and SHACL-driven Shape classes for linked data. It compiles queries into a plain JS query object that can be executed by a store.
+Linked core gives you a type-safe, schema-parameterized query language and SHACL-driven Shape classes for linked data. It compiles queries into a normalized [Intermediate Representation (IR)](./documentation/intermediate-representation.md) that can be executed by any store.
 
 ## Linked core offers
 
@@ -27,6 +27,10 @@ import {linkedPackage} from '@_linked/core/utils/Package';
 - `@_linked/rdf-mem-store`: in-memory RDF store that implements `IQuadStore`.
 - `@_linked/react`: React bindings for Linked queries and shapes.
 
+## Documentation
+
+- [Intermediate Representation (IR)](./documentation/intermediate-representation.md)
+
 ## Linked Package Setup
 
 Linked packages expose shapes, utilities, and ontologies through a small `package.ts` file. This makes module exports discoverable across Linked modules and enables linked decorators.
@@ -428,6 +432,41 @@ Override behavior:
 - Allow `preloadFor` to accept another query (not just a component).
 - Make and expose functions for auto syncing shapes to the graph.
 
+## Intermediate Representation (IR)
+
+Every Linked query compiles to a plain, JSON-serializable JavaScript object — the **Intermediate Representation**. This IR is the contract between the DSL and any storage backend. A store receives these objects and translates them into its native query language (SPARQL, SQL, etc.).
+
+For example, this DSL call:
+
+```typescript
+const names = await Person.select((p) => p.name);
+```
+
+produces the following IR object, which is passed to your store's `selectQuery()` method:
+
+```json
+{
+  "kind": "select",
+  "root": {"kind": "shape_scan", "shape": "https://schema.org/Person", "alias": "a0"},
+  "patterns": [],
+  "projection": [
+    {
+      "alias": "a1",
+      "expression": {"kind": "property_expr", "sourceAlias": "a0", "property": "https://schema.org/name"}
+    }
+  ],
+  "resultMap": [{"key": "name", "alias": "a1"}],
+  "singleResult": false
+}
+```
+
+All IR types are available from `@_linked/core/queries/IntermediateRepresentation`. See the full [Intermediate Representation docs](./documentation/intermediate-representation.md) for the complete type reference, examples, and a store implementer guide.
+
+**Store packages:**
+
+- `@_linked/sparql-store` — SPARQL endpoint store (coming soon)
+- `@_linked/rdf-mem-store` — in-memory RDF store
+
 ## Changelog
 
 See [CHANGELOG.md](./CHANGELOG.md).

package/lib/cjs/index.js

@@ -61,6 +61,7 @@ const DeleteQuery = __importStar(require("./queries/DeleteQuery.js"));
 const CreateQuery = __importStar(require("./queries/CreateQuery.js"));
 const QueryParser = __importStar(require("./queries/QueryParser.js"));
 const QueryFactory = __importStar(require("./queries/QueryFactory.js"));
+const IntermediateRepresentation = __importStar(require("./queries/IntermediateRepresentation.js"));
 const NameSpace = __importStar(require("./utils/NameSpace.js"));
 const ShapeClass = __importStar(require("./utils/ShapeClass.js"));
 const cached = __importStar(require("./utils/cached.js"));
@@ -103,6 +104,7 @@ function initModularApp() {
         CreateQuery,
         QueryParser,
         QueryFactory,
+        IntermediateRepresentation,
         SHACLShapes,
         rdf,
         rdfs,

package/lib/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,wCA+CC;AAvFD;;;;GAIG;AACH,4DAA8C;AAC9C,kFAAoE;AACpE,gFAAkE;AAClE,wEAA0D;AAC1D,kEAAoD;AACpD,kEAAoD;AACpD,yDAA2C;AAC3C,+DAAiD;AACjD,oEAAsD;AACtD,0DAA4C;AAC5C,oDAAsC;AACtC,sEAAwD;AACxD,sEAAwD;AACxD,0EAA4D;AAC5D,sEAAwD;AACxD,sEAAwD;AACxD,sEAAwD;AACxD,wEAA0D;AAC1D,gEAAkD;AAClD,kEAAoD;AACpD,0DAA4C;AAC5C,uDAAyC;AACzC,6EAA+D;AAC/D,uEAAyD;AACzD,uEAAyD;AACzD,yDAA2C;AAC3C,2DAA6C;AAC7C,yDAA2C;AAC3C,6DAA+C;AAC/C,6DAA+C;AAC/C,yDAA2C;AAC3C,yDAA2C;AAC3C,0DAAiC;AACzB,mBADD,mBAAQ,CACC;AAEhB,SAAgB,cAAc;IAC5B,IAAI,WAAW,GAAG;QAChB,OAAO;QACP,kBAAkB;QAClB,iBAAiB;QACjB,aAAa;QACb,OAAO;QACP,OAAO;QACP,KAAK;QACL,QAAQ;QACR,MAAM;QACN,SAAS;QACT,MAAM;QACN,GAAG;QACH,UAAU;QACV,IAAI;QACJ,aAAa;QACb,UAAU;QACV,UAAU;QACV,WAAW;QACX,WAAW;QACX,aAAa;QACb,WAAW;QACX,WAAW;QACX,WAAW;QACX,YAAY;QACZ,WAAW;QACX,GAAG;QACH,IAAI;QACJ,GAAG;QACH,KAAK;QACL,KAAK;QACL,GAAG;QACH,GAAG;KACJ,CAAC;IACF,IAAI,WAAW,GAAG,EAAE,CAAC;IACrB,KAAK,IAAI,OAAO,IAAI,WAAW,EAAE,CAAC;QAChC,IAAI,eAAe,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QAC3C,KAAK,IAAI,SAAS,IAAI,eAAe,EAAE,CAAC;YACtC,WAAW,CAAC,SAAS,CAAC,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC,CAAC;IAC9C,CAAC;SAAM,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QACzC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC,CAAC;IAC9C,CAAC;AACH,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,wCAgDC;AAzFD;;;;GAIG;AACH,4DAA8C;AAC9C,kFAAoE;AACpE,gFAAkE;AAClE,wEAA0D;AAC1D,kEAAoD;AACpD,kEAAoD;AACpD,yDAA2C;AAC3C,+DAAiD;AACjD,oEAAsD;AACtD,0DAA4C;AAC5C,oDAAsC;AACtC,sEAAwD;AACxD,sEAAwD;AACxD,0EAA4D;AAC5D,sEAAwD;AACxD,sEAAwD;AACxD,sEAAwD;AACxD,wEAA0D;AAC1D,oGAAsF;AACtF,gEAAkD;AAClD,kEAAoD;AACpD,0DAA4C;AAC5C,uDAAyC;AACzC,6EAA+D;AAC/D,uEAAyD;AACzD,uEAAyD;AACzD,yDAA2C;AAC3C,2DAA6C;AAC7C,yDAA2C;AAC3C,6DAA+C;AAC/C,6DAA+C;AAC/C,yDAA2C;AAC3C,yDAA2C;AAC3C,0DAAiC;AACzB,mBADD,mBAAQ,CACC;AAEhB,SAAgB,cAAc;IAC5B,IAAI,WAAW,GAAG;QAChB,OAAO;QACP,kBAAkB;QAClB,iBAAiB;QACjB,aAAa;QACb,OAAO;QACP,OAAO;QACP,KAAK;QACL,QAAQ;QACR,MAAM;QACN,SAAS;QACT,MAAM;QACN,GAAG;QACH,UAAU;QACV,IAAI;QACJ,aAAa;QACb,UAAU;QACV,UAAU;QACV,WAAW;QACX,WAAW;QACX,aAAa;QACb,WAAW;QACX,WAAW;QACX,WAAW;QACX,YAAY;QACZ,0BAA0B;QAC1B,WAAW;QACX,GAAG;QACH,IAAI;QACJ,GAAG;QACH,KAAK;QACL,KAAK;QACL,GAAG;QACH,GAAG;KACJ,CAAC;IACF,IAAI,WAAW,GAAG,EAAE,CAAC;IACrB,KAAK,IAAI,OAAO,IAAI,WAAW,EAAE,CAAC;QAChC,IAAI,eAAe,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QAC3C,KAAK,IAAI,SAAS,IAAI,eAAe,EAAE,CAAC;YACtC,WAAW,CAAC,SAAS,CAAC,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC,CAAC;IAC9C,CAAC;SAAM,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QACzC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC,CAAC;IAC9C,CAAC;AACH,CAAC"}

package/lib/cjs/interfaces/IQuadStore.d.ts

@@ -1,14 +1,26 @@
-import { CreateQuery } from '../queries/CreateQuery.js';
-import { DeleteQuery, DeleteResponse } from '../queries/DeleteQuery.js';
-import { SelectQuery } from '../queries/SelectQuery.js';
-import { UpdateQuery } from '../queries/UpdateQuery.js';
+import type { SelectQuery } from '../queries/SelectQuery.js';
+import type { CreateQuery } from '../queries/CreateQuery.js';
+import type { UpdateQuery } from '../queries/UpdateQuery.js';
+import type { DeleteQuery, DeleteResponse } from '../queries/DeleteQuery.js';
+import type { SelectResult, CreateResult, UpdateResult } from '../queries/IntermediateRepresentation.js';
+/**
+ * Store interface for executing IR queries.
+ *
+ * Implement this interface to back Linked with a custom storage engine
+ * (SPARQL endpoint, SQL database, in-memory store, etc.).
+ *
+ * Each method receives a canonical IR query object and returns the result.
+ * The calling layer (LinkedStorage / QueryParser) threads the precise
+ * DSL-level TypeScript result type back to the caller — the store only
+ * needs to produce data that matches the structural result types.
+ */
 export interface IQuadStore {
     /**
      * Prepares the store to be used.
      */
     init?(): Promise<any>;
-    selectQuery<ResultType>(query: SelectQuery<any>): Promise<ResultType>;
-    updateQuery?<RType>(q: UpdateQuery<RType>): Promise<RType>;
-    createQuery?<R>(q: CreateQuery<R>): Promise<R>;
+    selectQuery(query: SelectQuery): Promise<SelectResult>;
+    updateQuery?(query: UpdateQuery): Promise<UpdateResult>;
+    createQuery?(query: CreateQuery): Promise<CreateResult>;
     deleteQuery?(query: DeleteQuery): Promise<DeleteResponse>;
 }

package/lib/cjs/queries/CreateQuery.d.ts

@@ -1,18 +1,17 @@
 import { Shape } from '../shapes/Shape.js';
-import { NodeShape } from '../shapes/SHACL.js';
-import { LinkedQuery } from './SelectQuery.js';
 import { AddId, NodeDescriptionValue, UpdatePartial } from './QueryFactory.js';
 import { MutationQueryFactory } from './MutationQuery.js';
-export interface CreateQuery<ResponseType = null> extends LinkedQuery {
-    type: 'create';
-    shape: NodeShape;
-    description: NodeDescriptionValue;
-}
+import { IRCreateMutation } from './IntermediateRepresentation.js';
+/**
+ * The canonical CreateQuery type — an IR AST node representing a create mutation.
+ * This is the type received by IQuadStore.createQuery().
+ */
+export type CreateQuery = IRCreateMutation;
 export type CreateResponse<U> = AddId<U, true>;
 export declare class CreateQueryFactory<ShapeType extends Shape, U extends UpdatePartial<ShapeType>> extends MutationQueryFactory {
     shapeClass: typeof Shape;
     readonly id: string;
     readonly description: NodeDescriptionValue;
     constructor(shapeClass: typeof Shape, updateObjectOrFn: U);
-    getQueryObject(): CreateQuery<AddId<U, true>>;
+    build(): CreateQuery;
 }

package/lib/cjs/queries/CreateQuery.js

@@ -2,18 +2,18 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CreateQueryFactory = void 0;
 const MutationQuery_js_1 = require("./MutationQuery.js");
+const IRMutation_js_1 = require("./IRMutation.js");
 class CreateQueryFactory extends MutationQuery_js_1.MutationQueryFactory {
     constructor(shapeClass, updateObjectOrFn) {
         super();
         this.shapeClass = shapeClass;
         this.description = this.convertUpdateObject(updateObjectOrFn, this.shapeClass.shape, true);
     }
-    getQueryObject() {
-        return {
-            type: 'create',
+    build() {
+        return (0, IRMutation_js_1.buildCanonicalCreateMutationIR)({
             shape: this.shapeClass.shape,
             description: this.description,
-        };
+        });
     }
 }
 exports.CreateQueryFactory = CreateQueryFactory;

package/lib/cjs/queries/CreateQuery.js.map

@@ -1 +1 @@
-{"version":3,"file":"CreateQuery.js","sourceRoot":"","sources":["../../../src/queries/CreateQuery.ts"],"names":[],"mappings":";;;AAIA,yDAAwD;AAUxD,MAAa,kBAGX,SAAQ,uCAAoB;IAI5B,YACS,UAAwB,EAC/B,gBAAmB;QAEnB,KAAK,EAAE,CAAC;QAHD,eAAU,GAAV,UAAU,CAAc;QAI/B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,mBAAmB,CACzC,gBAAgB,EAChB,IAAI,CAAC,UAAU,CAAC,KAAK,EACrB,IAAI,CACL,CAAC;IACJ,CAAC;IAED,cAAc;QACZ,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,KAAK;YAC5B,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC;IACJ,CAAC;CACF;AA1BD,gDA0BC"}
+{"version":3,"file":"CreateQuery.js","sourceRoot":"","sources":["../../../src/queries/CreateQuery.ts"],"names":[],"mappings":";;;AAEA,yDAAwD;AAExD,mDAA+D;AAU/D,MAAa,kBAGX,SAAQ,uCAAoB;IAI5B,YACS,UAAwB,EAC/B,gBAAmB;QAEnB,KAAK,EAAE,CAAC;QAHD,eAAU,GAAV,UAAU,CAAc;QAI/B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,mBAAmB,CACzC,gBAAgB,EAChB,IAAI,CAAC,UAAU,CAAC,KAAK,EACrB,IAAI,CACL,CAAC;IACJ,CAAC;IAED,KAAK;QACH,OAAO,IAAA,8CAA8B,EAAC;YACpC,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,KAAK;YAC5B,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC,CAAC;IACL,CAAC;CACF;AAzBD,gDAyBC"}

package/lib/cjs/queries/DeleteQuery.d.ts

@@ -1,13 +1,12 @@
 import { Shape } from '../shapes/Shape.js';
-import { NodeShape } from '../shapes/SHACL.js';
-import { LinkedQuery } from './SelectQuery.js';
 import { NodeReferenceValue, UpdatePartial } from './QueryFactory.js';
 import { MutationQueryFactory, NodeId } from './MutationQuery.js';
-export interface DeleteQuery extends LinkedQuery {
-    type: 'delete';
-    shape: NodeShape;
-    ids: NodeReferenceValue[];
-}
+import { IRDeleteMutation } from './IntermediateRepresentation.js';
+/**
+ * The canonical DeleteQuery type — an IR AST node representing a delete mutation.
+ * This is the type received by IQuadStore.deleteQuery().
+ */
+export type DeleteQuery = IRDeleteMutation;
 export type DeleteResponse = {
     /**
      * The IDs of the items that were successfully deleted.
@@ -31,5 +30,5 @@ export declare class DeleteQueryFactory<ShapeType extends Shape, U extends Updat
     readonly id: string;
     readonly ids: NodeReferenceValue[];
     constructor(shapeClass: typeof Shape, ids: NodeId[] | NodeId);
-    getQueryObject(): DeleteQuery;
+    build(): DeleteQuery;
 }

package/lib/cjs/queries/DeleteQuery.js

@@ -2,18 +2,18 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DeleteQueryFactory = void 0;
 const MutationQuery_js_1 = require("./MutationQuery.js");
+const IRMutation_js_1 = require("./IRMutation.js");
 class DeleteQueryFactory extends MutationQuery_js_1.MutationQueryFactory {
     constructor(shapeClass, ids) {
         super();
         this.shapeClass = shapeClass;
         this.ids = this.convertNodeReferences(ids);
     }
-    getQueryObject() {
-        return {
-            type: 'delete',
+    build() {
+        return (0, IRMutation_js_1.buildCanonicalDeleteMutationIR)({
             shape: this.shapeClass.shape,
             ids: this.ids,
-        };
+        });
     }
 }
 exports.DeleteQueryFactory = DeleteQueryFactory;

package/lib/cjs/queries/DeleteQuery.js.map

@@ -1 +1 @@
-{"version":3,"file":"DeleteQuery.js","sourceRoot":"","sources":["../../../src/queries/DeleteQuery.ts"],"names":[],"mappings":";;;AAIA,yDAAgE;AA2BhE,MAAa,kBAGX,SAAQ,uCAAoB;IAI5B,YACS,UAAwB,EAC/B,GAAsB;QAEtB,KAAK,EAAE,CAAC;QAHD,eAAU,GAAV,UAAU,CAAc;QAI/B,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAC;IAC7C,CAAC;IAED,cAAc;QACZ,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,KAAK;YAC5B,GAAG,EAAE,IAAI,CAAC,GAAG;SACd,CAAC;IACJ,CAAC;CACF;AAtBD,gDAsBC"}
+{"version":3,"file":"DeleteQuery.js","sourceRoot":"","sources":["../../../src/queries/DeleteQuery.ts"],"names":[],"mappings":";;;AAEA,yDAAgE;AAEhE,mDAA+D;AA2B/D,MAAa,kBAGX,SAAQ,uCAAoB;IAI5B,YACS,UAAwB,EAC/B,GAAsB;QAEtB,KAAK,EAAE,CAAC;QAHD,eAAU,GAAV,UAAU,CAAc;QAI/B,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAC;IAC7C,CAAC;IAED,KAAK;QACH,OAAO,IAAA,8CAA8B,EAAC;YACpC,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,KAAK;YAC5B,GAAG,EAAE,IAAI,CAAC,GAAG;SACd,CAAC,CAAC;IACL,CAAC;CACF;AArBD,gDAqBC"}

package/lib/cjs/queries/IRAliasScope.d.ts

@@ -0,0 +1,20 @@
+/** A named alias binding in a scope, tracking its source and nesting depth. */
+export type IRAliasBinding = {
+    alias: string;
+    source: string;
+    scopeDepth: number;
+};
+export declare class IRAliasScope {
+    readonly scopeName: string;
+    private readonly parent?;
+    private bindings;
+    private generatedCount;
+    constructor(scopeName: string, parent?: IRAliasScope);
+    get depth(): number;
+    registerAlias(alias: string, source: string): IRAliasBinding;
+    generateAlias(source: string): IRAliasBinding;
+    resolveAlias(alias: string): IRAliasBinding;
+    createChildScope(name: string): IRAliasScope;
+}
+/** Validates that an alias exists in the current scope chain, throwing if not found. */
+export declare const validateAliasReference: (alias: string, currentScope: IRAliasScope) => IRAliasBinding;

package/lib/cjs/queries/IRAliasScope.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAliasReference = exports.IRAliasScope = void 0;
+class IRAliasScope {
+    constructor(scopeName, parent) {
+        this.scopeName = scopeName;
+        this.parent = parent;
+        this.bindings = new Map();
+        this.generatedCount = 0;
+    }
+    get depth() {
+        return this.parent ? this.parent.depth + 1 : 0;
+    }
+    registerAlias(alias, source) {
+        if (this.bindings.has(alias)) {
+            throw new Error(`Alias already exists in scope: ${alias}`);
+        }
+        const binding = {
+            alias,
+            source,
+            scopeDepth: this.depth,
+        };
+        this.bindings.set(alias, binding);
+        return binding;
+    }
+    generateAlias(source) {
+        let alias;
+        do {
+            alias = `a${this.generatedCount++}`;
+        } while (this.bindings.has(alias));
+        return this.registerAlias(alias, source);
+    }
+    resolveAlias(alias) {
+        if (this.bindings.has(alias)) {
+            return this.bindings.get(alias);
+        }
+        if (this.parent) {
+            return this.parent.resolveAlias(alias);
+        }
+        throw new Error(`Alias not found in scope chain: ${alias}`);
+    }
+    createChildScope(name) {
+        return new IRAliasScope(name, this);
+    }
+}
+exports.IRAliasScope = IRAliasScope;
+/** Validates that an alias exists in the current scope chain, throwing if not found. */
+const validateAliasReference = (alias, currentScope) => {
+    return currentScope.resolveAlias(alias);
+};
+exports.validateAliasReference = validateAliasReference;
+//# sourceMappingURL=IRAliasScope.js.map

package/lib/cjs/queries/IRAliasScope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IRAliasScope.js","sourceRoot":"","sources":["../../../src/queries/IRAliasScope.ts"],"names":[],"mappings":";;;AAOA,MAAa,YAAY;IAIvB,YACkB,SAAiB,EAChB,MAAqB;QADtB,cAAS,GAAT,SAAS,CAAQ;QAChB,WAAM,GAAN,MAAM,CAAe;QALhC,aAAQ,GAAG,IAAI,GAAG,EAA0B,CAAC;QAC7C,mBAAc,GAAG,CAAC,CAAC;IAKxB,CAAC;IAEJ,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACjD,CAAC;IAED,aAAa,CAAC,KAAa,EAAE,MAAc;QACzC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,kCAAkC,KAAK,EAAE,CAAC,CAAC;QAC7D,CAAC;QACD,MAAM,OAAO,GAAmB;YAC9B,KAAK;YACL,MAAM;YACN,UAAU,EAAE,IAAI,CAAC,KAAK;SACvB,CAAC;QACF,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAClC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,aAAa,CAAC,MAAc;QAC1B,IAAI,KAAa,CAAC;QAClB,GAAG,CAAC;YACF,KAAK,GAAG,IAAI,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC;QACtC,CAAC,QAAQ,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE;QACnC,OAAO,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAC3C,CAAC;IAED,YAAY,CAAC,KAAa;QACxB,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7B,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAClC,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QACzC,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,mCAAmC,KAAK,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,gBAAgB,CAAC,IAAY;QAC3B,OAAO,IAAI,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;CACF;AA/CD,oCA+CC;AAED,wFAAwF;AACjF,MAAM,sBAAsB,GAAG,CACpC,KAAa,EACb,YAA0B,EACV,EAAE;IAClB,OAAO,YAAY,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;AAC1C,CAAC,CAAC;AALW,QAAA,sBAAsB,0BAKjC"}

package/lib/cjs/queries/IRCanonicalize.d.ts

@@ -0,0 +1,36 @@
+import { DesugaredSelectionPath, DesugaredSelectQuery, DesugaredWhere, DesugaredWhereArg } from './IRDesugar.js';
+import { WhereMethods } from './SelectQuery.js';
+export type CanonicalWhereComparison = {
+    kind: 'where_binary';
+    operator: WhereMethods;
+    left: DesugaredSelectionPath;
+    right: DesugaredWhereArg[];
+};
+export type CanonicalWhereLogical = {
+    kind: 'where_logical';
+    operator: 'and' | 'or';
+    expressions: CanonicalWhereExpression[];
+};
+export type CanonicalWhereExists = {
+    kind: 'where_exists';
+    path: DesugaredSelectionPath;
+    predicate: CanonicalWhereExpression;
+};
+export type CanonicalWhereNot = {
+    kind: 'where_not';
+    expression: CanonicalWhereExpression;
+};
+export type CanonicalWhereExpression = CanonicalWhereComparison | CanonicalWhereLogical | CanonicalWhereExists | CanonicalWhereNot;
+export type CanonicalDesugaredSelectQuery = Omit<DesugaredSelectQuery, 'where'> & {
+    where?: CanonicalWhereExpression;
+};
+/**
+ * Recursively rewrites a desugared where-clause into canonical form:
+ * flattens nested AND/OR groups, converts quantifiers (some/every) to exists patterns.
+ */
+export declare const canonicalizeWhere: (where: DesugaredWhere) => CanonicalWhereExpression;
+/**
+ * Canonicalizes a desugared select query by normalizing its where-clause.
+ * All other fields pass through unchanged.
+ */
+export declare const canonicalizeDesugaredSelectQuery: (query: DesugaredSelectQuery) => CanonicalDesugaredSelectQuery;

package/lib/cjs/queries/IRCanonicalize.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalizeDesugaredSelectQuery = exports.canonicalizeWhere = void 0;
+const SelectQuery_js_1 = require("./SelectQuery.js");
+const toComparison = (comparison) => {
+    return {
+        kind: 'where_binary',
+        operator: comparison.operator,
+        left: comparison.left,
+        right: comparison.right,
+    };
+};
+const isDesugaredWhere = (arg) => {
+    return (typeof arg === 'object' &&
+        !!arg &&
+        'kind' in arg &&
+        (arg.kind === 'where_comparison' ||
+            arg.kind === 'where_boolean'));
+};
+const toExists = (comparison) => {
+    const nested = comparison.right.find(isDesugaredWhere);
+    if (!nested) {
+        return toComparison(comparison);
+    }
+    const nestedExpr = (0, exports.canonicalizeWhere)(nested);
+    if (comparison.operator === SelectQuery_js_1.WhereMethods.SOME) {
+        return {
+            kind: 'where_exists',
+            path: comparison.left,
+            predicate: nestedExpr,
+        };
+    }
+    if (comparison.operator === SelectQuery_js_1.WhereMethods.EVERY) {
+        return {
+            kind: 'where_not',
+            expression: {
+                kind: 'where_exists',
+                path: comparison.left,
+                predicate: {
+                    kind: 'where_not',
+                    expression: nestedExpr,
+                },
+            },
+        };
+    }
+    return toComparison(comparison);
+};
+const flattenLogical = (operator, left, right) => {
+    const expressions = [];
+    if (left.kind === 'where_logical' && left.operator === operator) {
+        expressions.push(...left.expressions);
+    }
+    else {
+        expressions.push(left);
+    }
+    if (right.kind === 'where_logical' && right.operator === operator) {
+        expressions.push(...right.expressions);
+    }
+    else {
+        expressions.push(right);
+    }
+    return {
+        kind: 'where_logical',
+        operator,
+        expressions,
+    };
+};
+/**
+ * Recursively rewrites a desugared where-clause into canonical form:
+ * flattens nested AND/OR groups, converts quantifiers (some/every) to exists patterns.
+ */
+const canonicalizeWhere = (where) => {
+    if (where.kind === 'where_comparison') {
+        if (where.operator === SelectQuery_js_1.WhereMethods.EQUALS) {
+            const nestedQuantifier = where.right.find((arg) => isDesugaredWhere(arg) &&
+                arg.kind === 'where_comparison' &&
+                (arg.operator === SelectQuery_js_1.WhereMethods.SOME ||
+                    arg.operator === SelectQuery_js_1.WhereMethods.EVERY));
+            if (nestedQuantifier) {
+                return (0, exports.canonicalizeWhere)(nestedQuantifier);
+            }
+        }
+        if (where.operator === SelectQuery_js_1.WhereMethods.SOME ||
+            where.operator === SelectQuery_js_1.WhereMethods.EVERY ||
+            where.operator === 'some' ||
+            where.operator === 'every') {
+            return toExists(where);
+        }
+        return toComparison(where);
+    }
+    const grouped = where;
+    let current = toComparison(grouped.first);
+    grouped.andOr.forEach((token) => {
+        if (token.and) {
+            current = flattenLogical('and', current, (0, exports.canonicalizeWhere)(token.and));
+        }
+        else if (token.or) {
+            current = flattenLogical('or', current, (0, exports.canonicalizeWhere)(token.or));
+        }
+    });
+    return current;
+};
+exports.canonicalizeWhere = canonicalizeWhere;
+/**
+ * Canonicalizes a desugared select query by normalizing its where-clause.
+ * All other fields pass through unchanged.
+ */
+const canonicalizeDesugaredSelectQuery = (query) => {
+    return Object.assign(Object.assign({}, query), { where: query.where ? (0, exports.canonicalizeWhere)(query.where) : undefined });
+};
+exports.canonicalizeDesugaredSelectQuery = canonicalizeDesugaredSelectQuery;
+//# sourceMappingURL=IRCanonicalize.js.map

package/lib/cjs/queries/IRCanonicalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IRCanonicalize.js","sourceRoot":"","sources":["../../../src/queries/IRCanonicalize.ts"],"names":[],"mappings":";;;AAQA,qDAA8C;AAoC9C,MAAM,YAAY,GAAG,CACnB,UAAoC,EACV,EAAE;IAC5B,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,QAAQ,EAAE,UAAU,CAAC,QAAQ;QAC7B,IAAI,EAAE,UAAU,CAAC,IAAI;QACrB,KAAK,EAAE,UAAU,CAAC,KAAK;KACxB,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,gBAAgB,GAAG,CAAC,GAAsB,EAAyB,EAAE;IACzE,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,CAAC,CAAC,GAAG;QACL,MAAM,IAAI,GAAG;QACb,CAAE,GAAsB,CAAC,IAAI,KAAK,kBAAkB;YACjD,GAAsB,CAAC,IAAI,KAAK,eAAe,CAAC,CACpD,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,QAAQ,GAAG,CACf,UAAoC,EACV,EAAE;IAC5B,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;IACvD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,YAAY,CAAC,UAAU,CAAC,CAAC;IAClC,CAAC;IAED,MAAM,UAAU,GAAG,IAAA,yBAAiB,EAAC,MAAM,CAAC,CAAC;IAC7C,IAAI,UAAU,CAAC,QAAQ,KAAK,6BAAY,CAAC,IAAI,EAAE,CAAC;QAC9C,OAAO;YACL,IAAI,EAAE,cAAc;YACpB,IAAI,EAAE,UAAU,CAAC,IAAI;YACrB,SAAS,EAAE,UAAU;SACtB,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,CAAC,QAAQ,KAAK,6BAAY,CAAC,KAAK,EAAE,CAAC;QAC/C,OAAO;YACL,IAAI,EAAE,WAAW;YACjB,UAAU,EAAE;gBACV,IAAI,EAAE,cAAc;gBACpB,IAAI,EAAE,UAAU,CAAC,IAAI;gBACrB,SAAS,EAAE;oBACT,IAAI,EAAE,WAAW;oBACjB,UAAU,EAAE,UAAU;iBACvB;aACF;SACF,CAAC;IACJ,CAAC;IAED,OAAO,YAAY,CAAC,UAAU,CAAC,CAAC;AAClC,CAAC,CAAC;AAEF,MAAM,cAAc,GAAG,CACrB,QAAsB,EACtB,IAA8B,EAC9B,KAA+B,EACR,EAAE;IACzB,MAAM,WAAW,GAA+B,EAAE,CAAC;IAEnD,IAAI,IAAI,CAAC,IAAI,KAAK,eAAe,IAAI,IAAI,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAChE,WAAW,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC;IACxC,CAAC;SAAM,CAAC;QACN,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IAED,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,IAAI,KAAK,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAClE,WAAW,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;IACzC,CAAC;SAAM,CAAC;QACN,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAED,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,QAAQ;QACR,WAAW;KACZ,CAAC;AACJ,CAAC,CAAC;AAEF;;;GAGG;AACI,MAAM,iBAAiB,GAAG,CAC/B,KAAqB,EACK,EAAE;IAC5B,IAAI,KAAK,CAAC,IAAI,KAAK,kBAAkB,EAAE,CAAC;QACtC,IAAI,KAAK,CAAC,QAAQ,KAAK,6BAAY,CAAC,MAAM,EAAE,CAAC;YAC3C,MAAM,gBAAgB,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CACvC,CAAC,GAAG,EAAmC,EAAE,CACvC,gBAAgB,CAAC,GAAG,CAAC;gBACrB,GAAG,CAAC,IAAI,KAAK,kBAAkB;gBAC/B,CAAC,GAAG,CAAC,QAAQ,KAAK,6BAAY,CAAC,IAAI;oBACjC,GAAG,CAAC,QAAQ,KAAK,6BAAY,CAAC,KAAK,CAAC,CACzC,CAAC;YACF,IAAI,gBAAgB,EAAE,CAAC;gBACrB,OAAO,IAAA,yBAAiB,EAAC,gBAAgB,CAAC,CAAC;YAC7C,CAAC;QACH,CAAC;QAED,IACE,KAAK,CAAC,QAAQ,KAAK,6BAAY,CAAC,IAAI;YACpC,KAAK,CAAC,QAAQ,KAAK,6BAAY,CAAC,KAAK;YACpC,KAAK,CAAC,QAA8B,KAAK,MAAM;YAC/C,KAAK,CAAC,QAA8B,KAAK,OAAO,EACjD,CAAC;YACD,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC;QACD,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;IAED,MAAM,OAAO,GAAG,KAA8B,CAAC;IAC/C,IAAI,OAAO,GAA6B,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAEpE,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;QAC9B,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC;YACd,OAAO,GAAG,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,IAAA,yBAAiB,EAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QACzE,CAAC;aAAM,IAAI,KAAK,CAAC,EAAE,EAAE,CAAC;YACpB,OAAO,GAAG,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,IAAA,yBAAiB,EAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;QACvE,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,OAAO,CAAC;AACjB,CAAC,CAAC;AAxCW,QAAA,iBAAiB,qBAwC5B;AAEF;;;GAGG;AACI,MAAM,gCAAgC,GAAG,CAC9C,KAA2B,EACI,EAAE;IACjC,uCACK,KAAK,KACR,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,IAAA,yBAAiB,EAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,IAC/D;AACJ,CAAC,CAAC;AAPW,QAAA,gCAAgC,oCAO3C"}

package/lib/cjs/queries/IRDesugar.d.ts

@@ -0,0 +1,98 @@
+import { JSNonNullPrimitive, SelectPath, SortByPath, WhereMethods, WherePath } from './SelectQuery.js';
+import { NodeReferenceValue, ShapeReferenceValue } from './QueryFactory.js';
+/**
+ * Internal pipeline input type — captures exactly what the desugar pass
+ * needs from a select query factory. Replaces the old LegacySelectQuery
+ * as the pipeline entry point.
+ */
+export type RawSelectInput = {
+    select: SelectPath;
+    where?: WherePath;
+    sortBy?: SortByPath;
+    subject?: unknown;
+    shape?: unknown;
+    limit?: number;
+    offset?: number;
+    singleResult?: boolean;
+};
+export type DesugaredPropertyStep = {
+    kind: 'property_step';
+    propertyShapeId: string;
+    where?: DesugaredWhere;
+};
+export type DesugaredCountStep = {
+    kind: 'count_step';
+    path: DesugaredPropertyStep[];
+    label?: string;
+};
+export type DesugaredTypeCastStep = {
+    kind: 'type_cast_step';
+    shapeId: string;
+};
+export type DesugaredStep = DesugaredPropertyStep | DesugaredCountStep | DesugaredTypeCastStep;
+export type DesugaredSelectionPath = {
+    kind: 'selection_path';
+    steps: DesugaredStep[];
+};
+export type DesugaredSubSelect = {
+    kind: 'sub_select';
+    parentPath: DesugaredStep[];
+    selections: DesugaredSelection;
+};
+export type DesugaredCustomObjectSelect = {
+    kind: 'custom_object_select';
+    entries: DesugaredCustomObjectEntry[];
+};
+export type DesugaredCustomObjectEntry = {
+    key: string;
+    value: DesugaredSelection;
+};
+export type DesugaredEvaluationSelect = {
+    kind: 'evaluation_select';
+    where: DesugaredWhere;
+};
+export type DesugaredMultiSelection = {
+    kind: 'multi_selection';
+    selections: DesugaredSelectionPath[];
+};
+export type DesugaredSelection = DesugaredSelectionPath | DesugaredSubSelect | DesugaredCustomObjectSelect | DesugaredEvaluationSelect | DesugaredMultiSelection;
+export type DesugaredWhereComparison = {
+    kind: 'where_comparison';
+    operator: WhereMethods;
+    left: DesugaredSelectionPath;
+    right: DesugaredWhereArg[];
+};
+export type DesugaredWhereBoolean = {
+    kind: 'where_boolean';
+    first: DesugaredWhereComparison;
+    andOr: Array<{
+        and?: DesugaredWhere;
+        or?: DesugaredWhere;
+    }>;
+};
+export type DesugaredWhere = DesugaredWhereComparison | DesugaredWhereBoolean;
+export type DesugaredSortBy = {
+    direction: 'ASC' | 'DESC';
+    paths: DesugaredSelectionPath[];
+};
+export type DesugaredWhereArg = JSNonNullPrimitive | NodeReferenceValue | ShapeReferenceValue | {
+    kind: 'arg_path';
+    subject?: ShapeReferenceValue;
+    path: DesugaredSelectionPath;
+} | DesugaredWhere;
+export type DesugaredSelectQuery = {
+    kind: 'desugared_select';
+    shapeId?: string;
+    subjectId?: string;
+    singleResult?: boolean;
+    limit?: number;
+    offset?: number;
+    selections: DesugaredSelection[];
+    sortBy?: DesugaredSortBy;
+    where?: DesugaredWhere;
+};
+/**
+ * Converts a RawSelectInput (DSL-level query) into a flat DesugaredSelectQuery
+ * by walking proxy-traced select/where/sortBy paths and extracting property steps.
+ */
+export declare const desugarSelectQuery: (query: RawSelectInput) => DesugaredSelectQuery;