@distrohelena/canton-typescript-sdk 0.1.35 → 0.1.37

package/dist/query/pqs/pqs-relational-sql-compiler.d.ts

@@ -1,23 +1,15 @@
 import { PqsRelation, PqsSchemaProfileV1 } from "./pqs-schema-profile.js";
+import type { NormalizedAggregateQuery, NormalizedCountQuery, NormalizedFindManyQuery, NormalizedGroupByQuery } from "../canonical/query-ast.js";
+import { type PqsRelationResultShape } from "./pqs-result-shape.js";
+export type { PqsIncludedResultShape, PqsJsonResultProjection, PqsRelationResultShape, PqsSelectedScalarField } from "./pqs-result-shape.js";
 export interface CompiledPqsRelationQuery {
     readonly text: string;
     readonly values: readonly unknown[];
 }
-interface RelationFindManyArgs {
-    readonly where?: Readonly<Record<string, unknown>>;
-    readonly select?: Readonly<Record<string, boolean>>;
-    readonly orderBy?: readonly Readonly<Record<string, "asc" | "desc">>[];
-    readonly take?: number;
-    readonly skip?: number;
+export interface CompiledPqsRelationFindManyQuery extends CompiledPqsRelationQuery {
+    readonly resultShape: PqsRelationResultShape;
 }
-export declare function compilePqsRelationFindMany(relation: PqsRelation, args: RelationFindManyArgs, profile: PqsSchemaProfileV1): CompiledPqsRelationQuery;
-export declare function compilePqsRelationGroupBy(relation: PqsRelation, args: {
-    readonly by: readonly unknown[];
-    readonly aggregate: {
-        readonly count?: true;
-        readonly min?: readonly string[];
-        readonly max?: readonly string[];
-        readonly sum?: readonly string[];
-    };
-}, profile: PqsSchemaProfileV1, parameterOffset?: number): CompiledPqsRelationQuery;
-export {};
+export declare function compilePqsRelationFindMany(relation: PqsRelation, query: NormalizedFindManyQuery, profile: PqsSchemaProfileV1): CompiledPqsRelationFindManyQuery;
+export declare function compilePqsRelationCount(relation: PqsRelation, query: NormalizedCountQuery, profile: PqsSchemaProfileV1): CompiledPqsRelationQuery;
+export declare function compilePqsRelationAggregate(relation: PqsRelation, query: NormalizedAggregateQuery, profile: PqsSchemaProfileV1): CompiledPqsRelationQuery;
+export declare function compilePqsRelationGroupBy(relation: PqsRelation, query: NormalizedGroupByQuery, profile: PqsSchemaProfileV1): CompiledPqsRelationQuery;

package/dist/query/pqs/pqs-relational-sql-compiler.js

@@ -1,137 +1,166 @@
 import { PqsSchemaProfileV1, pqsRelationMetadata } from "./pqs-schema-profile.js";
 import { pqsRelationEdges } from "./pqs-schema-profile.js";
-export function compilePqsRelationFindMany(relation, args, profile) {
-    assertPage(args);
+import { compileCanonicalPhysicalField, compileCanonicalPhysicalIncludes, compileCanonicalPhysicalPredicate } from "./pqs-sql-compiler.js";
+import { quotePqsIdentifier } from "./pqs-sql-syntax.js";
+import { compilePqsResultShape } from "./pqs-result-shape.js";
+export function compilePqsRelationFindMany(relation, query, profile) {
+    assertCanonicalPhysicalFindMany(relation, query);
     const metadata = pqsRelationMetadata[relation];
+    const source = logicalTypeRootSource(relation, profile);
     const values = [];
     const add = (value) => {
         values.push(value);
         return `$${values.length}`;
     };
-    const fields = selectedFields(relation, metadata, args.select);
-    const where = compileWhere(relation, metadata, args.where, add);
-    const orderBy = compileOrderBy(relation, metadata, args.orderBy);
-    const limit = args.take === undefined ? "" : ` limit ${add(args.take)}`;
-    const offset = args.skip === undefined ? "" : ` offset ${add(args.skip)}`;
+    const fields = selectedCanonicalFields(relation, metadata, query.select?.fields, (query.select?.json.length ?? 0) > 0);
+    const predicate = query.predicate === undefined ? "" : compileCanonicalPhysicalPredicate(relation, query.predicate, "", profile, add);
+    const where = predicate.length === 0 ? "" : ` where ${predicate}`;
+    const orderBy = compileCanonicalOrderBy(relation, metadata, query.orderBy, profile);
+    const limit = query.take === undefined ? "" : ` limit ${add(query.take)}`;
+    const offset = query.skip === 0 ? "" : ` offset ${add(query.skip)}`;
+    const included = compileCanonicalPhysicalIncludes(relation, source.reference, query.includes, profile, add);
+    const json = compileCanonicalJsonSelections(relation, query.select, profile, add);
+    const shape = compilePqsResultShape(relation, "many", query.select, query.includes);
     return {
-        text: `select ${fields.map(([field, column]) => `"${column}" as "${field}"`).join(", ")} from ${profile.relation(relation)}${where}${orderBy}${limit}${offset}`,
+        text: `${source.withClause}select ${[...fields.map(([field]) => `${compileCanonicalPhysicalField(relation, field, "", profile)} as "${field}"`), ...json, ...included.map((include) => include.selection)].join(", ")} from ${source.relation}${where}${orderBy}${limit}${offset}`,
         values,
+        resultShape: shape,
     };
 }
-export function compilePqsRelationGroupBy(relation, args, profile, parameterOffset = 0) {
-    if (args.by.length === 0 || (!args.aggregate.count && !args.aggregate.min && !args.aggregate.max && !args.aggregate.sum))
+export function compilePqsRelationCount(relation, query, profile) {
+    assertCanonicalPhysicalQuery(relation, query, "count");
+    const source = logicalTypeRootSource(relation, profile);
+    const values = [];
+    const add = (value) => {
+        values.push(value);
+        return `$${values.length}`;
+    };
+    const predicate = query.predicate === undefined ? "" : ` where ${compileCanonicalPhysicalPredicate(relation, query.predicate, "", profile, add)}`;
+    return { text: `${source.withClause}select count(*)::text as count from ${source.relation}${predicate}`, values };
+}
+export function compilePqsRelationAggregate(relation, query, profile) {
+    assertCanonicalPhysicalQuery(relation, query, "aggregate");
+    const metadata = pqsRelationMetadata[relation];
+    const source = logicalTypeRootSource(relation, profile);
+    const values = [];
+    const add = (value) => {
+        values.push(value);
+        return `$${values.length}`;
+    };
+    const selected = [];
+    if (query.aggregates.count)
+        selected.push("count(*)::text as count");
+    for (const [operation, fields] of [["min", query.aggregates.min], ["max", query.aggregates.max], ["sum", query.aggregates.sum]]) {
+        for (const name of fields) {
+            if (!metadata.numericFields.includes(name))
+                throw new Error(`${name} is not a numeric aggregate field of ${relation}`);
+            selected.push(`${operation}(${compileCanonicalPhysicalField(relation, name, "", profile)})::text as "${operation}_${name}"`);
+        }
+    }
+    if (selected.length === 0)
+        throw new Error("aggregate must request at least one result");
+    const predicate = query.predicate === undefined ? "" : ` where ${compileCanonicalPhysicalPredicate(relation, query.predicate, "", profile, add)}`;
+    return { text: `${source.withClause}select ${selected.join(", ")} from ${source.relation}${predicate}`, values };
+}
+export function compilePqsRelationGroupBy(relation, query, profile) {
+    assertCanonicalPhysicalQuery(relation, query, "groupBy");
+    if (query.by.length === 0 || (!query.aggregates.count && query.aggregates.min.length === 0 && query.aggregates.max.length === 0 && query.aggregates.sum.length === 0))
         throw new Error("groupBy requires a key and aggregate");
     const metadata = pqsRelationMetadata[relation];
+    const source = logicalTypeRootSource(relation, profile);
     const root = relation === "__events" ? "event" : "root";
     const joins = [];
     const expressions = [];
     const selected = [];
     const values = [];
-    const add = (value) => { values.push(value); return `$${parameterOffset + values.length}`; };
-    for (const key of args.by) {
-        if (typeof key === "string") {
-            const column = field(relation, metadata, key);
-            const expression = metadata.arrayFields.includes(key)
-                ? `"${key}".value`
-                : `"${root}"."${column}"`;
-            if (metadata.arrayFields.includes(key))
-                joins.push(`cross join lateral unnest("${root}"."${column}") as "${key}"(value)`);
+    const add = (value) => { values.push(value); return `$${values.length}`; };
+    const predicate = query.predicate === undefined ? "" : ` where ${compileCanonicalPhysicalPredicate(relation, query.predicate, `"${root}"`, profile, add)}`;
+    for (const key of query.by) {
+        if (key.kind === "field") {
+            const fieldName = key.path[0];
+            const column = field(relation, metadata, fieldName);
+            const expression = metadata.arrayFields.includes(fieldName)
+                ? `"${fieldName}".value`
+                : compileCanonicalPhysicalField(relation, fieldName, `"${root}"`, profile);
+            if (metadata.arrayFields.includes(fieldName))
+                joins.push(`cross join lateral unnest("${root}"."${column}") as "${fieldName}"(value)`);
             expressions.push(expression);
-            selected.push(`${expression} as "${key}"`);
+            selected.push(`${expression} as "${fieldName}"`);
             continue;
         }
-        if (key === null || typeof key !== "object")
-            throw new Error("invalid group key");
-        const [edgeName, nested] = Object.entries(key)[0] ?? [];
-        if (nested !== null && typeof nested === "object" && "name" in nested && "path" in nested && "as" in nested) {
-            const projection = nested;
-            if (typeof projection.name !== "string" || !Array.isArray(projection.path) || !projection.path.every((segment) => typeof segment === "string" && segment.length > 0) || !["text", "numeric", "boolean", "timestamp"].includes(String(projection.as)) || !PqsSchemaProfileV1.jsonField(relation, edgeName))
-                throw new Error("invalid profiled JSON group key");
-            const column = field(relation, metadata, edgeName);
-            const text = `"${root}"."${column}" #>> ${add(projection.path)}::text[]`;
-            const expression = projection.as === "text" ? text : projection.as === "numeric" ? `(${text})::numeric` : projection.as === "boolean" ? `(${text})::boolean` : `(${text})::timestamptz`;
+        if (key.kind === "json") {
+            field(relation, metadata, key.field);
+            const text = `${compileCanonicalPhysicalField(relation, key.field, `"${root}"`, profile)} #>> ${add(key.path)}::text[]`;
+            const expression = key.as === "text" ? text : key.as === "numeric" ? `(${text})::numeric` : key.as === "boolean" ? `(${text})::boolean` : `(${text})::timestamptz`;
             expressions.push(expression);
-            selected.push(`${expression} as "${projection.name}"`);
+            selected.push(`${expression} as ${quotePqsIdentifier(key.name)}`);
             continue;
         }
-        if (nested !== null && typeof nested === "object" && "bucket" in nested && PqsSchemaProfileV1.bucketField(relation, edgeName)) {
-            const bucket = nested.bucket;
-            if (typeof bucket !== "string" || !["hour", "day", "week", "month"].includes(bucket))
-                throw new Error("invalid profiled time bucket");
-            const column = field(relation, metadata, edgeName);
-            const expression = `date_trunc('${bucket}', "${root}"."${column}")`;
+        if (key.kind === "bucket" && key.path.length === 1) {
+            field(relation, metadata, key.path[0]);
+            const expression = `date_trunc('${key.bucket}', ${compileCanonicalPhysicalField(relation, key.path[0], `"${root}"`, profile)})`;
             expressions.push(expression);
-            selected.push(`${expression} as "${edgeName}_${bucket}"`);
+            selected.push(`${expression} as "${key.path[0]}_${key.bucket}"`);
             continue;
         }
+        const edgeName = key.path[0];
+        const fieldName = key.path[1];
         const edge = pqsRelationEdges[relation]?.[edgeName];
-        if (edge === undefined || edge.cardinality !== "one" || nested === null || typeof nested !== "object")
+        if (edge === undefined || edge.cardinality !== "one")
             throw new Error("group key must follow a profiled to-one edge");
-        const [fieldName, bucketValue] = Object.entries(nested)[0] ?? [];
-        const bucket = bucketValue !== null && typeof bucketValue === "object" ? bucketValue.bucket : undefined;
-        if (typeof bucket !== "string" || !["hour", "day", "week", "month"].includes(bucket) || !PqsSchemaProfileV1.bucketField(edge.target, fieldName))
-            throw new Error("invalid profiled time bucket");
-        const targetColumn = field(edge.target, pqsRelationMetadata[edge.target], fieldName);
+        field(edge.target, pqsRelationMetadata[edge.target], fieldName);
         joins.push(`join ${profile.relation(edge.target)} "${edgeName}" on "${edgeName}"."${edge.targetColumn}" = "${root}"."${edge.sourceColumn}"`);
-        const expression = `date_trunc('${bucket}', "${edgeName}"."${targetColumn}")`;
+        const expression = `date_trunc('${key.bucket}', ${compileCanonicalPhysicalField(edge.target, fieldName, `"${edgeName}"`, profile)})`;
         expressions.push(expression);
-        selected.push(`${expression} as "${edgeName}_${fieldName}_${bucket}"`);
+        selected.push(`${expression} as "${edgeName}_${fieldName}_${key.bucket}"`);
     }
-    if (args.aggregate.count)
+    if (query.aggregates.count)
         selected.push("count(*)::text as count");
-    for (const [operation, fields] of [["min", args.aggregate.min], ["max", args.aggregate.max], ["sum", args.aggregate.sum]])
-        for (const name of fields ?? []) {
+    for (const [operation, fields] of [["min", query.aggregates.min], ["max", query.aggregates.max], ["sum", query.aggregates.sum]])
+        for (const name of fields) {
             if (!metadata.numericFields.includes(name))
                 throw new Error(`${name} is not a numeric aggregate field of ${relation}`);
-            selected.push(`${operation}("${root}"."${field(relation, metadata, name)}")::text as "${operation}_${name}"`);
+            field(relation, metadata, name);
+            selected.push(`${operation}(${compileCanonicalPhysicalField(relation, name, `"${root}"`, profile)})::text as "${operation}_${name}"`);
         }
-    return { text: `select ${selected.join(", ")} from ${profile.relation(relation)} "${root}" ${joins.join(" ")} group by ${expressions.join(", ")}`, values };
+    return { text: `${source.withClause}select ${selected.join(", ")} from ${source.relation} "${root}"${joins.length === 0 ? "" : ` ${joins.join(" ")}`}${predicate} group by ${expressions.join(", ")}`, values };
+}
+function logicalTypeRootSource(relation, profile) {
+    if (relation !== "__contract_tpe" && relation !== "__exercise_tpe") {
+        const physical = profile.relation(relation);
+        return { withClause: "", relation: physical, reference: physical };
+    }
+    const publicKey = compileCanonicalPhysicalField(relation, "pk", '"physical_type"', profile);
+    const logicalRelation = '"logical_type_root"';
+    return {
+        withClause: `with ${logicalRelation} as (select distinct on (${publicKey}) "physical_type".* from ${profile.relation(relation)} "physical_type" order by ${publicKey}, "physical_type"."pk" asc) `,
+        relation: logicalRelation,
+        reference: logicalRelation,
+    };
 }
-function selectedFields(relation, metadata, select) {
-    const fields = select === undefined
-        ? Object.entries(metadata.fields)
-        : Object.entries(select).filter(([, enabled]) => enabled).map(([name]) => [name, field(relation, metadata, name)]);
-    if (fields.length === 0)
+function selectedCanonicalFields(relation, metadata, selected, allowEmpty = false) {
+    const fields = selected === undefined ? Object.entries(metadata.fields) : selected.map((name) => [name, field(relation, metadata, name)]);
+    if (fields.length === 0 && !allowEmpty)
         throw new Error("select must include at least one field");
     return fields;
 }
-function compileWhere(relation, metadata, where, add) {
-    const conditions = [];
-    for (const [name, value] of Object.entries(where ?? {})) {
-        const column = field(relation, metadata, name);
-        if (value === null || Array.isArray(value) || typeof value !== "object")
-            throw new Error(`${name} must be a filter`);
-        const filter = value;
-        for (const [operator, operand] of Object.entries(filter)) {
-            if (operator === "equals")
-                conditions.push(`"${column}" = ${add(operand)}`);
-            else if (operator === "in" && Array.isArray(operand))
-                conditions.push(operand.length === 0 ? "false" : `"${column}" = any(${add(operand)})`);
-            else if (operator === "is" && operand === null)
-                conditions.push(`"${column}" is null`);
-            else if (operator === "isNot" && operand === null)
-                conditions.push(`"${column}" is not null`);
-            else if (["lt", "lte", "gt", "gte", "like", "ilike"].includes(operator)) {
-                const sql = { lt: "<", lte: "<=", gt: ">", gte: ">=", like: "like", ilike: "ilike" }[operator];
-                conditions.push(`"${column}" ${sql} ${add(operand)}`);
-            }
-            else
-                throw new Error(`${operator} is not supported for ${name}`);
-        }
-    }
-    return conditions.length === 0 ? "" : ` where ${conditions.join(" and ")}`;
+function compileCanonicalJsonSelections(relation, selection, profile, add) {
+    return (selection?.json ?? []).map((projection) => {
+        if (!PqsSchemaProfileV1.jsonField(relation, projection.field))
+            throw new Error(`${projection.field} is not a JSON field of ${relation}`);
+        field(relation, pqsRelationMetadata[relation], projection.field);
+        const text = `${compileCanonicalPhysicalField(relation, projection.field, "", profile)} #>> ${add(projection.path)}::text[]`;
+        const expression = projection.as === "text" ? text : projection.as === "numeric" ? `(${text})::numeric::text` : projection.as === "boolean" ? `(${text})::boolean` : `(${text})::timestamptz`;
+        return `${expression} as ${quotePqsIdentifier(projection.name)}`;
+    });
 }
-function compileOrderBy(relation, metadata, orderBy) {
-    if (orderBy === undefined)
+function compileCanonicalOrderBy(relation, metadata, orderBy, profile) {
+    if (orderBy.length === 0)
         return "";
-    const requested = orderBy.flatMap((entry) => Object.entries(entry));
-    if (requested.length === 0 || requested.some(([, direction]) => direction !== "asc" && direction !== "desc"))
-        throw new Error("orderBy must be a non-empty list of one-field entries");
-    const ordered = requested.map(([name, direction]) => [field(relation, metadata, name), direction]);
-    const stableKey = metadata.uniqueKeys[0]?.[0];
-    if (stableKey !== undefined && !ordered.some(([column]) => column === metadata.fields[stableKey]))
-        ordered.push([metadata.fields[stableKey], "asc"]);
-    return ` order by ${ordered.map(([column, direction]) => `"${column}" ${direction}`).join(", ")}`;
+    return ` order by ${orderBy.map((order) => {
+        field(relation, metadata, order.path[0]);
+        return `${compileCanonicalPhysicalField(relation, order.path[0], "", profile)} ${order.direction}`;
+    }).join(", ")}`;
 }
 function field(relation, metadata, name) {
     const column = metadata.fields[name];
@@ -139,8 +168,20 @@ function field(relation, metadata, name) {
         throw new Error(`${name} is not a field of ${relation}`);
     return column;
 }
-function assertPage(args) {
-    for (const [name, value] of [["take", args.take], ["skip", args.skip]])
-        if (value !== undefined && (!Number.isInteger(value) || value < 0))
-            throw new Error(`${name} must be a non-negative integer`);
+function assertCanonicalPhysicalFindMany(relation, query) {
+    if (query === null || typeof query !== "object" || query.kind !== "findMany" || !Array.isArray(query.includes) || !Array.isArray(query.orderBy)) {
+        throw new Error("compilePqsRelationFindMany requires a canonical findMany query");
+    }
+    if (relationForCanonical(query.relation) !== relation)
+        throw new Error(`Canonical relation ${query.relation} does not match ${relation}`);
+}
+function assertCanonicalPhysicalQuery(relation, query, kind) {
+    if (query === null || typeof query !== "object" || query.kind !== kind) {
+        throw new Error(`compilePqsRelation${kind[0].toUpperCase()}${kind.slice(1)} requires a canonical ${kind} query`);
+    }
+    if (relationForCanonical(query.relation) !== relation)
+        throw new Error(`Canonical relation ${query.relation} does not match ${relation}`);
+}
+function relationForCanonical(relation) {
+    return { contracts: "__contracts", contractTypes: "__contract_tpe", events: "__events", exercises: "__exercises", exerciseTypes: "__exercise_tpe", packages: "__packages", transactions: "__transactions", watermark: "__watermark" }[relation];
 }

package/dist/query/pqs/pqs-result-shape.d.ts

@@ -0,0 +1,25 @@
+import type { NormalizedInclude, NormalizedSelection } from "../canonical/query-ast.js";
+import { PqsRelation } from "./pqs-schema-profile.js";
+export interface PqsSelectedScalarField {
+    readonly name: string;
+}
+export interface PqsJsonResultProjection {
+    readonly name: string;
+    readonly field: string;
+    readonly path: readonly string[];
+    readonly as: "text" | "numeric" | "boolean" | "timestamp";
+}
+export interface PqsIncludedResultShape {
+    readonly edge: string;
+    readonly target: PqsRelation;
+    readonly cardinality: "one" | "many";
+    readonly shape: PqsRelationResultShape;
+}
+export interface PqsRelationResultShape {
+    readonly relation: PqsRelation;
+    readonly cardinality: "one" | "many";
+    readonly fields: readonly PqsSelectedScalarField[];
+    readonly json: readonly PqsJsonResultProjection[];
+    readonly includes: readonly PqsIncludedResultShape[];
+}
+export declare function compilePqsResultShape(relation: PqsRelation, cardinality: "one" | "many", selection: NormalizedSelection | undefined, includes: readonly NormalizedInclude[]): PqsRelationResultShape;

package/dist/query/pqs/pqs-result-shape.js

@@ -0,0 +1,25 @@
+import { pqsRelationEdges, pqsRelationMetadata } from "./pqs-schema-profile.js";
+export function compilePqsResultShape(relation, cardinality, selection, includes) {
+    const fields = relation === "__contracts"
+        ? selection?.fields ?? ["contractId", "templateId", "packageId", "payload", "witnesses", "createdEventOffset", "createdAt", "archivedEventOffset", "archivedAt", "active"]
+        : selection?.fields ?? Object.keys(pqsRelationMetadata[relation].fields);
+    const shape = {
+        relation,
+        cardinality,
+        fields: fields.map((name) => Object.freeze({ name })),
+        json: (selection?.json ?? []).map((projection) => Object.freeze({ ...projection, path: Object.freeze([...projection.path]) })),
+        includes: includes.map((include) => {
+            const edge = pqsRelationEdges[relation]?.[include.edge];
+            if (edge === undefined || edge.target !== relationForCanonical(include.relation) || edge.cardinality !== include.cardinality)
+                throw new Error(`Invalid canonical include ${include.edge}`);
+            return Object.freeze({ edge: include.edge, target: edge.target, cardinality: include.cardinality, shape: compilePqsResultShape(edge.target, include.cardinality, include.select, include.includes) });
+        }),
+    };
+    Object.freeze(shape.fields);
+    Object.freeze(shape.json);
+    Object.freeze(shape.includes);
+    return Object.freeze(shape);
+}
+function relationForCanonical(relation) {
+    return { contracts: "__contracts", contractTypes: "__contract_tpe", events: "__events", exercises: "__exercises", exerciseTypes: "__exercise_tpe", packages: "__packages", transactions: "__transactions", watermark: "__watermark" }[relation];
+}

package/dist/query/pqs/pqs-schema-profile.js

@@ -1,4 +1,5 @@
 import { PqsSchemaProfileError } from "../errors/pqs-schema-profile-error.js";
+import { queryRelationEdges, queryRelationMetadata, } from "../canonical/query-schema.js";
 const schemaIdentifier = /^[A-Za-z_][A-Za-z0-9_]*$/;
 export const requiredPqsRelations = [
     "__contracts",
@@ -10,56 +11,56 @@ export const requiredPqsRelations = [
     "__transactions",
     "__watermark",
 ];
-export const pqsRelationEdges = {
-    __contracts: {
-        contractType: { target: "__contract_tpe", sourceColumn: "tpe_pk", targetColumn: "pk", cardinality: "one", nullable: false },
-        createdTransaction: { target: "__transactions", sourceColumn: "created_at_ix", targetColumn: "ix", cardinality: "one", nullable: false },
-        archivedTransaction: { target: "__transactions", sourceColumn: "archived_at_ix", targetColumn: "ix", cardinality: "one", nullable: true },
-        exercises: { target: "__exercises", sourceColumn: "contract_id", targetColumn: "contract_id", cardinality: "many", nullable: false },
-    },
-    __contract_tpe: {
-        contracts: { target: "__contracts", sourceColumn: "pk", targetColumn: "tpe_pk", cardinality: "many", nullable: false },
-        exercises: { target: "__exercises", sourceColumn: "pk", targetColumn: "contract_tpe_pk", cardinality: "many", nullable: false },
-    },
-    __events: {
-        transaction: { target: "__transactions", sourceColumn: "tx_ix", targetColumn: "ix", cardinality: "one", nullable: false },
-        exercises: { target: "__exercises", sourceColumn: "pk", targetColumn: "exercise_event_pk", cardinality: "many", nullable: false },
-    },
-    __exercises: {
-        exerciseType: { target: "__exercise_tpe", sourceColumn: "tpe_pk", targetColumn: "pk", cardinality: "one", nullable: false },
-        contractType: { target: "__contract_tpe", sourceColumn: "contract_tpe_pk", targetColumn: "pk", cardinality: "one", nullable: false },
-        event: { target: "__events", sourceColumn: "exercise_event_pk", targetColumn: "pk", cardinality: "one", nullable: true },
-        transaction: { target: "__transactions", sourceColumn: "exercised_at_ix", targetColumn: "ix", cardinality: "one", nullable: true },
-        package: { target: "__packages", sourceColumn: "package_pk", targetColumn: "pk", cardinality: "one", nullable: false },
-        contract: { target: "__contracts", sourceColumn: "contract_id", targetColumn: "contract_id", cardinality: "one", nullable: false },
-    },
-    __exercise_tpe: { exercises: { target: "__exercises", sourceColumn: "pk", targetColumn: "tpe_pk", cardinality: "many", nullable: false } },
-    __packages: { exercises: { target: "__exercises", sourceColumn: "pk", targetColumn: "package_pk", cardinality: "many", nullable: false } },
-    __transactions: {
-        events: { target: "__events", sourceColumn: "ix", targetColumn: "tx_ix", cardinality: "many", nullable: false },
-        createdContracts: { target: "__contracts", sourceColumn: "ix", targetColumn: "created_at_ix", cardinality: "many", nullable: false },
-        archivedContracts: { target: "__contracts", sourceColumn: "ix", targetColumn: "archived_at_ix", cardinality: "many", nullable: false },
-        exercises: { target: "__exercises", sourceColumn: "ix", targetColumn: "exercised_at_ix", cardinality: "many", nullable: false },
-    },
+const queryRelationByPqsRelation = {
+    __contracts: "contracts",
+    __contract_tpe: "contractTypes",
+    __events: "events",
+    __exercises: "exercises",
+    __exercise_tpe: "exerciseTypes",
+    __packages: "packages",
+    __transactions: "transactions",
+    __watermark: "watermark",
 };
-const pqsJsonFields = {
-    __contracts: ["payload"],
-    __exercises: ["argument", "result"],
-    __transactions: ["traceContext"],
+const pqsRelationByQueryRelation = {
+    contracts: "__contracts",
+    contractTypes: "__contract_tpe",
+    events: "__events",
+    exercises: "__exercises",
+    exerciseTypes: "__exercise_tpe",
+    packages: "__packages",
+    transactions: "__transactions",
+    watermark: "__watermark",
 };
-const pqsBucketFields = {
-    __transactions: ["effectiveAt"],
+const pqsEdgeColumns = {
+    __contracts: { contractType: { sourceColumn: "tpe_pk", targetColumn: "pk" }, createdTransaction: { sourceColumn: "created_at_ix", targetColumn: "ix" }, archivedTransaction: { sourceColumn: "archived_at_ix", targetColumn: "ix" }, exercises: { sourceColumn: "contract_id", targetColumn: "contract_id" } },
+    __contract_tpe: { contracts: { sourceColumn: "pk", targetColumn: "tpe_pk" }, exercises: { sourceColumn: "pk", targetColumn: "contract_tpe_pk" } },
+    __events: { transaction: { sourceColumn: "tx_ix", targetColumn: "ix" }, exercises: { sourceColumn: "pk", targetColumn: "exercise_event_pk" } },
+    __exercises: { exerciseType: { sourceColumn: "tpe_pk", targetColumn: "pk" }, contractType: { sourceColumn: "contract_tpe_pk", targetColumn: "pk" }, event: { sourceColumn: "exercise_event_pk", targetColumn: "pk" }, transaction: { sourceColumn: "exercised_at_ix", targetColumn: "ix" }, package: { sourceColumn: "package_pk", targetColumn: "pk" }, contract: { sourceColumn: "contract_id", targetColumn: "contract_id" } },
+    __exercise_tpe: { exercises: { sourceColumn: "pk", targetColumn: "tpe_pk" } },
+    __packages: { exercises: { sourceColumn: "pk", targetColumn: "package_pk" } },
+    __transactions: { events: { sourceColumn: "ix", targetColumn: "tx_ix" }, createdContracts: { sourceColumn: "ix", targetColumn: "created_at_ix" }, archivedContracts: { sourceColumn: "ix", targetColumn: "archived_at_ix" }, exercises: { sourceColumn: "ix", targetColumn: "exercised_at_ix" } },
 };
-export const pqsRelationMetadata = {
-    __contracts: { fields: {}, uniqueKeys: [["contractId"]], numericFields: ["createdEventOffset", "archivedEventOffset"], arrayFields: ["witnesses"], dateFields: ["createdAt", "archivedAt"], binaryFields: [] },
-    __contract_tpe: { fields: { pk: "pk", payloadType: "payload_type", aliases: "aliases", packageName: "package_name", moduleName: "module_name", entityName: "entity_name", templateFqn: "template_fqn" }, uniqueKeys: [["pk"]], numericFields: ["pk"], arrayFields: ["aliases"], dateFields: [], binaryFields: [] },
-    __events: { fields: { pk: "pk", txIx: "tx_ix", eventId: "event_id", type: "type" }, uniqueKeys: [["pk"]], numericFields: ["pk", "txIx"], arrayFields: [], dateFields: [], binaryFields: [], stringFields: ["eventId", "type"] },
-    __exercises: { fields: { tpePk: "tpe_pk", contractTpePk: "contract_tpe_pk", exerciseEventPk: "exercise_event_pk", exercisedAtIx: "exercised_at_ix", contractId: "contract_id", argument: "argument", result: "result", redactionId: "redaction_id", packagePk: "package_pk", controllers: "controllers", lastDescendantNodeId: "last_descendant_node_id", witnesses: "witnesses" }, uniqueKeys: [], numericFields: ["tpePk", "contractTpePk", "exerciseEventPk", "exercisedAtIx", "packagePk", "lastDescendantNodeId"], arrayFields: ["controllers", "witnesses"], dateFields: [], binaryFields: [] },
-    __exercise_tpe: { fields: { pk: "pk", choice: "choice", consuming: "consuming", aliases: "aliases", packageName: "package_name", moduleName: "module_name", entityName: "entity_name", templateFqn: "template_fqn", choiceFqn: "choice_fqn" }, uniqueKeys: [["pk"]], numericFields: ["pk"], arrayFields: ["aliases"], dateFields: [], binaryFields: [] },
-    __packages: { fields: { pk: "pk", name: "name", version: "version", id: "id" }, uniqueKeys: [["pk"], ["id"]], numericFields: ["pk"], arrayFields: [], dateFields: [], binaryFields: [], stringFields: ["name", "version", "id"] },
-    __transactions: { fields: { ix: "ix", offset: "offset", transactionId: "transaction_id", effectiveAt: "effective_at", workflowId: "workflow_id", domainId: "domain_id", traceContext: "trace_context", externalTransactionHash: "external_transaction_hash", paidTrafficCost: "paid_traffic_cost" }, uniqueKeys: [["ix"], ["offset"]], numericFields: ["ix", "offset", "paidTrafficCost"], arrayFields: [], dateFields: ["effectiveAt"], binaryFields: ["externalTransactionHash"] },
-    __watermark: { fields: { singleton: "singleton", ix: "ix", offset: "offset", instanceId: "instance_id" }, uniqueKeys: [["singleton"]], numericFields: ["ix", "offset"], arrayFields: [], dateFields: [], binaryFields: [] },
+export const pqsRelationEdges = Object.fromEntries(requiredPqsRelations.map((relation) => [relation, Object.fromEntries(Object.entries(queryRelationEdges[queryRelationByPqsRelation[relation]] ?? {}).map(([name, edge]) => {
+        const columns = pqsEdgeColumns[relation]?.[name];
+        if (columns === undefined) {
+            throw new Error(`Missing physical PQS edge mapping for ${relation}.${name}`);
+        }
+        return [name, { target: pqsRelationByQueryRelation[edge.target], ...columns, cardinality: edge.cardinality, nullable: edge.nullable }];
+    }))]));
+const pqsFields = {
+    __contracts: {},
+    __contract_tpe: { pk: "pk", payloadType: "payload_type", aliases: "aliases", packageName: "package_name", moduleName: "module_name", entityName: "entity_name", templateFqn: "template_fqn" },
+    __events: { pk: "pk", txIx: "tx_ix", eventId: "event_id", type: "type" },
+    __exercises: { tpePk: "tpe_pk", contractTpePk: "contract_tpe_pk", exerciseEventPk: "exercise_event_pk", exercisedAtIx: "exercised_at_ix", contractId: "contract_id", argument: "argument", result: "result", redactionId: "redaction_id", packagePk: "package_pk", controllers: "controllers", lastDescendantNodeId: "last_descendant_node_id", witnesses: "witnesses" },
+    __exercise_tpe: { pk: "pk", choice: "choice", consuming: "consuming", aliases: "aliases", packageName: "package_name", moduleName: "module_name", entityName: "entity_name", templateFqn: "template_fqn", choiceFqn: "choice_fqn" },
+    __packages: { pk: "pk", name: "name", version: "version", id: "id" },
+    __transactions: { ix: "ix", offset: "offset", transactionId: "transaction_id", effectiveAt: "effective_at", workflowId: "workflow_id", domainId: "domain_id", traceContext: "trace_context", externalTransactionHash: "external_transaction_hash", paidTrafficCost: "paid_traffic_cost" },
+    __watermark: { singleton: "singleton", ix: "ix", offset: "offset", instanceId: "instance_id" },
 };
+export const pqsRelationMetadata = Object.fromEntries(requiredPqsRelations.map((relation) => {
+    const logical = queryRelationMetadata[queryRelationByPqsRelation[relation]];
+    return [relation, { fields: pqsFields[relation], uniqueKeys: logical.uniqueKeys, numericFields: logical.numericFields, arrayFields: logical.arrayFields, dateFields: logical.dateFields, binaryFields: logical.binaryFields, stringFields: logical.stringFields }];
+}));
 export const requiredPqsColumns = {
     __contracts: [
         "tpe_pk",
@@ -140,10 +141,10 @@ export class PqsSchemaProfileV1 {
         return `${quoteIdentifier(this.schema)}.${quoteIdentifier(relation)}`;
     }
     static jsonField(relation, field) {
-        return pqsJsonFields[relation]?.includes(field) ?? false;
+        return queryRelationMetadata[queryRelationByPqsRelation[relation]].jsonFields.includes(field);
     }
     static bucketField(relation, field) {
-        return pqsBucketFields[relation]?.includes(field) ?? false;
+        return queryRelationMetadata[queryRelationByPqsRelation[relation]].bucketFields.includes(field);
     }
 }
 export async function validatePqsSchemaAsync(client, profile) {

package/dist/query/pqs/pqs-sql-compiler.d.ts

@@ -1,8 +1,23 @@
-import { ContractFindManyArgs, ContractGroupByArgs } from "../model-types.js";
+import type { NormalizedAggregateQuery, NormalizedCountQuery, NormalizedFindManyQuery, NormalizedGroupByQuery, NormalizedInclude, QueryPredicate } from "../canonical/query-ast.js";
 import { PqsSchemaProfileV1 } from "./pqs-schema-profile.js";
+import { PqsRelation } from "./pqs-schema-profile.js";
+import { type PqsRelationResultShape } from "./pqs-result-shape.js";
 export interface CompiledPqsQuery {
     readonly text: string;
     readonly values: readonly unknown[];
 }
-export declare function compileContractFindMany(args: ContractFindManyArgs, profile: PqsSchemaProfileV1): CompiledPqsQuery;
-export declare function compileContractGroupBy(args: ContractGroupByArgs, profile: PqsSchemaProfileV1): CompiledPqsQuery;
+export interface CompiledPqsInclude {
+    readonly key: string;
+    readonly expression: string;
+    readonly selection: string;
+}
+export interface CompiledContractFindManyQuery extends CompiledPqsQuery {
+    readonly resultShape: PqsRelationResultShape;
+}
+export declare function compileCanonicalPhysicalField(relation: PqsRelation, field: string, alias: string, profile: PqsSchemaProfileV1): string;
+export declare function compileContractFindMany(query: NormalizedFindManyQuery, profile: PqsSchemaProfileV1): CompiledContractFindManyQuery;
+export declare function compileContractCount(query: NormalizedCountQuery, profile: PqsSchemaProfileV1): CompiledPqsQuery;
+export declare function compileContractAggregate(query: NormalizedAggregateQuery, profile: PqsSchemaProfileV1): CompiledPqsQuery;
+export declare function compileCanonicalPhysicalIncludes(source: PqsRelation, parentAlias: string, includes: readonly NormalizedInclude[], profile: PqsSchemaProfileV1, add: (value: unknown) => string): readonly CompiledPqsInclude[];
+export declare function compileCanonicalPhysicalPredicate(relation: PqsRelation, predicate: QueryPredicate, alias: string, profile: PqsSchemaProfileV1, add: (value: unknown) => string): string;
+export declare function compileContractGroupBy(query: NormalizedGroupByQuery, profile: PqsSchemaProfileV1): CompiledPqsQuery;