sovrium 0.0.2

package/src/infrastructure/database/generators/trigger-generators.ts

@@ -0,0 +1,154 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { sanitizeTableName } from '../field-utils'
+import type { Table } from '@/domain/models/app/table'
+
+/**
+ * Generate triggers for created-at fields (set on INSERT, prevent UPDATE)
+ * Includes intrinsic created_at column if not explicitly defined
+ */
+export const generateCreatedAtTriggers = (table: Table): readonly string[] => {
+  const createdAtFields = table.fields.filter((field) => field.type === 'created-at')
+  const hasCreatedAtField = table.fields.some((field) => field.name === 'created_at')
+
+  // Collect all created_at field names
+  const fieldNames = [
+    ...createdAtFields.map((f) => f.name),
+    // Include intrinsic created_at column if not explicitly defined
+    ...(!hasCreatedAtField ? ['created_at'] : []),
+  ]
+
+  if (fieldNames.length === 0) return []
+
+  const sanitized = sanitizeTableName(table.name)
+  const setFunctionName = `set_${sanitized}_created_at`
+  const setTriggerName = `a_trigger_${sanitized}_set_created_at` // Prefix with 'a_' to ensure it runs before formula triggers
+  const preventFunctionName = `prevent_${sanitized}_created_at_update`
+  const preventTriggerName = `a_trigger_${sanitized}_created_at_immutable` // Prefix with 'a_' to ensure it runs before formula triggers
+
+  return [
+    // Create trigger function to set created_at on INSERT
+    `CREATE OR REPLACE FUNCTION ${setFunctionName}()
+RETURNS TRIGGER AS $$
+BEGIN
+  ${fieldNames.map((name) => `IF NEW.${name} IS NULL THEN NEW.${name} = CURRENT_TIMESTAMP; END IF;`).join('\n  ')}
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql`,
+    // Create INSERT trigger
+    `DROP TRIGGER IF EXISTS ${setTriggerName} ON ${sanitized}`,
+    `CREATE TRIGGER ${setTriggerName}
+BEFORE INSERT ON ${sanitized}
+FOR EACH ROW
+EXECUTE FUNCTION ${setFunctionName}()`,
+    // Create trigger function to prevent updates
+    `CREATE OR REPLACE FUNCTION ${preventFunctionName}()
+RETURNS TRIGGER AS $$
+BEGIN
+  ${fieldNames.map((name) => `NEW.${name} = OLD.${name};`).join('\n  ')}
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql`,
+    // Create UPDATE trigger
+    `DROP TRIGGER IF EXISTS ${preventTriggerName} ON ${sanitized}`,
+    `CREATE TRIGGER ${preventTriggerName}
+BEFORE UPDATE ON ${sanitized}
+FOR EACH ROW
+EXECUTE FUNCTION ${preventFunctionName}()`,
+  ]
+}
+
+/**
+ * Generate trigger to prevent updates to autonumber fields (immutability)
+ */
+export const generateAutonumberTriggers = (table: Table): readonly string[] => {
+  const autonumberFields = table.fields.filter((field) => field.type === 'autonumber')
+
+  if (autonumberFields.length === 0) return []
+
+  const sanitized = sanitizeTableName(table.name)
+  const fieldNames = autonumberFields.map((f) => f.name)
+  const triggerFunctionName = `prevent_${sanitized}_autonumber_update`
+  const triggerName = `trigger_${sanitized}_autonumber_immutable`
+
+  return [
+    // Create trigger function
+    `CREATE OR REPLACE FUNCTION ${triggerFunctionName}()
+RETURNS TRIGGER AS $$
+BEGIN
+  ${fieldNames.map((name) => `NEW.${name} = OLD.${name};`).join('\n  ')}
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql`,
+    // Create trigger
+    `DROP TRIGGER IF EXISTS ${triggerName} ON ${sanitized}`,
+    `CREATE TRIGGER ${triggerName}
+BEFORE UPDATE ON ${sanitized}
+FOR EACH ROW
+EXECUTE FUNCTION ${triggerFunctionName}()`,
+  ]
+}
+
+/**
+ * Generate trigger to automatically update updated-by fields on UPDATE
+ */
+export const generateUpdatedByTriggers = (table: Table): readonly string[] => {
+  const updatedByFields = table.fields.filter((field) => field.type === 'updated-by')
+
+  if (updatedByFields.length === 0) return []
+
+  const sanitized = sanitizeTableName(table.name)
+
+  return [
+    // Create trigger (fires on UPDATE only - updated_by should be NULL on INSERT)
+    `DROP TRIGGER IF EXISTS set_updated_by ON ${sanitized}`,
+    `CREATE TRIGGER set_updated_by
+BEFORE UPDATE ON ${sanitized}
+FOR EACH ROW
+EXECUTE FUNCTION set_updated_by()`,
+  ]
+}
+
+/**
+ * Generate triggers to automatically set/update updated-at fields on INSERT/UPDATE
+ * Includes intrinsic updated_at column if not explicitly defined
+ */
+export const generateUpdatedAtTriggers = (table: Table): readonly string[] => {
+  const updatedAtFields = table.fields.filter((field) => field.type === 'updated-at')
+  const hasUpdatedAtField = table.fields.some((field) => field.name === 'updated_at')
+
+  // Collect all updated_at field names
+  const fieldNames = [
+    ...updatedAtFields.map((f) => f.name),
+    // Include intrinsic updated_at column if not explicitly defined
+    ...(!hasUpdatedAtField ? ['updated_at'] : []),
+  ]
+
+  if (fieldNames.length === 0) return []
+
+  const sanitized = sanitizeTableName(table.name)
+  const triggerFunctionName = `update_${sanitized}_updated_at`
+  const triggerName = `a_trigger_${sanitized}_updated_at` // Prefix with 'a_' to ensure it runs before formula triggers
+
+  return [
+    // Create trigger function (handles both INSERT and UPDATE)
+    `CREATE OR REPLACE FUNCTION ${triggerFunctionName}()
+RETURNS TRIGGER AS $$
+BEGIN
+  ${fieldNames.map((name) => `NEW.${name} = CURRENT_TIMESTAMP;`).join('\n  ')}
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql`,
+    // Create trigger for both INSERT and UPDATE
+    `DROP TRIGGER IF EXISTS ${triggerName} ON ${sanitized}`,
+    `CREATE TRIGGER ${triggerName}
+BEFORE INSERT OR UPDATE ON ${sanitized}
+FOR EACH ROW
+EXECUTE FUNCTION ${triggerFunctionName}()`,
+  ]
+}

package/src/infrastructure/database/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+/**
+ * Database Infrastructure Module
+ *
+ * Provides database access and ORM utilities.
+ * Currently uses Drizzle ORM with PostgreSQL via Bun SQL.
+ *
+ * @example
+ * ```typescript
+ * import { Database, DatabaseLive } from '@/infrastructure/database'
+ * import { users } from '@/infrastructure/database/schema'
+ *
+ * const program = Effect.gen(function* () {
+ *   const db = yield* Database
+ *   const allUsers = yield* Effect.tryPromise(() => db.select().from(users))
+ *   return allUsers
+ * }).pipe(Effect.provide(DatabaseLive))
+ * ```
+ */
+
+export { db, type DrizzleDB, type DrizzleTransaction } from './drizzle/db'
+export { Database, DatabaseLive } from './drizzle/layer'
+export * from './drizzle/schema'
+export {
+  SessionContextError,
+  ForbiddenError,
+  UniqueConstraintViolationError,
+  ValidationError,
+} from './session-context'

package/src/infrastructure/database/lookup/lookup-expression-generators.ts

@@ -0,0 +1,356 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+/**
+ * Expression generators for lookup, rollup, and count fields
+ *
+ * These functions generate SQL subquery expressions for computed columns
+ * used in lookup VIEWs.
+ */
+
+import { generateSqlCondition } from '../filter-operators'
+import { toSingular, generateJunctionTableName } from '../sql/sql-generators'
+import type { Fields } from '@/domain/models/app/table/fields'
+import type { ViewFilterCondition } from '@/domain/models/app/table/views/filters'
+
+/**
+ * Build WHERE clause from filter condition
+ */
+const buildWhereClause = (filter: ViewFilterCondition, aliasPrefix: string): string => {
+  const { field, operator, value } = filter
+  const column = `${aliasPrefix}.${field}`
+  // Use legacy string escaping mode for backward compatibility
+  return generateSqlCondition(column, operator, value, { useEscapeSqlString: true })
+}
+
+/**
+ * Options for generating lookup expressions
+ */
+interface LookupExpressionOptions {
+  readonly lookupName: string
+  readonly relationshipField: string
+  readonly relatedField: string
+  readonly filters: ViewFilterCondition | undefined
+  readonly tableAlias: string
+  readonly actualTableName: string
+}
+
+/**
+ * Generate reverse lookup expression (one-to-many)
+ */
+const generateReverseLookupExpression = (options: LookupExpressionOptions): string => {
+  const { lookupName, relationshipField, relatedField, filters, tableAlias, actualTableName } =
+    options
+  // Infer table name from lookup field name (e.g., "active_tasks" → "tasks")
+  const lookupNameParts = lookupName.split('_')
+  const relatedTable = lookupNameParts[lookupNameParts.length - 1] ?? actualTableName
+
+  const alias = `${relatedTable}_for_${lookupName}`
+  const baseCondition = `${alias}.${relationshipField} = ${tableAlias}.id`
+  const whereConditions = filters
+    ? [baseCondition, buildWhereClause(filters, alias)]
+    : [baseCondition]
+  const whereClause = whereConditions.join(' AND ')
+
+  return `(
+    SELECT STRING_AGG(${alias}.${relatedField}::TEXT, ', ' ORDER BY ${alias}.${relatedField})
+    FROM ${relatedTable} AS ${alias}
+    WHERE ${whereClause}
+  ) AS ${lookupName}`
+}
+
+/**
+ * Options for many-to-many lookup expressions
+ */
+interface ManyToManyLookupOptions {
+  readonly lookupName: string
+  readonly relatedTable: string
+  readonly relatedField: string
+  readonly filters: ViewFilterCondition | undefined
+  readonly tableAlias: string
+  readonly actualTableName: string
+}
+
+/**
+ * Generate many-to-many lookup expression (through junction table)
+ */
+const generateManyToManyLookupExpression = (options: ManyToManyLookupOptions): string => {
+  const { lookupName, relatedTable, relatedField, filters, tableAlias, actualTableName } = options
+  const alias = `${relatedTable}_for_${lookupName}`
+  const junctionTable = generateJunctionTableName(actualTableName, relatedTable)
+  const junctionAlias = `junction_${lookupName}`
+  const foreignKeyInJunction = `${toSingular(actualTableName)}_id`
+  const relatedForeignKeyInJunction = `${toSingular(relatedTable)}_id`
+
+  const baseCondition = `${junctionAlias}.${foreignKeyInJunction} = ${tableAlias}.id`
+  const joinCondition = `${alias}.id = ${junctionAlias}.${relatedForeignKeyInJunction}`
+  const whereConditions = filters
+    ? [baseCondition, buildWhereClause(filters, alias)]
+    : [baseCondition]
+  const whereClause = whereConditions.join(' AND ')
+
+  return `(
+    SELECT STRING_AGG(${alias}.${relatedField}::TEXT, ', ' ORDER BY ${alias}.${relatedField})
+    FROM ${junctionTable} AS ${junctionAlias}
+    INNER JOIN ${relatedTable} AS ${alias} ON ${joinCondition}
+    WHERE ${whereClause}
+  ) AS ${lookupName}`
+}
+
+/**
+ * Options for forward lookup expressions
+ */
+interface ForwardLookupOptions {
+  readonly lookupName: string
+  readonly relationshipField: string
+  readonly relatedTable: string
+  readonly relatedField: string
+  readonly filters: ViewFilterCondition | undefined
+  readonly tableAlias: string
+}
+
+/**
+ * Generate forward lookup expression (many-to-one)
+ */
+const generateForwardLookupExpression = (options: ForwardLookupOptions): string => {
+  const { lookupName, relationshipField, relatedTable, relatedField, filters, tableAlias } = options
+  const alias = `${relatedTable}_for_${lookupName}`
+
+  if (filters) {
+    const whereClause = buildWhereClause(filters, alias)
+    return `(
+      SELECT ${alias}.${relatedField}
+      FROM ${relatedTable} AS ${alias}
+      WHERE ${alias}.id = ${tableAlias}.${relationshipField} AND ${whereClause}
+    ) AS ${lookupName}`
+  }
+
+  // Direct column reference via LEFT JOIN (handled in main VIEW SELECT)
+  return `${alias}.${relatedField} AS ${lookupName}`
+}
+
+/**
+ * Check if field is a many-to-many relationship with related table
+ */
+const isManyToManyWithRelatedTable = (
+  field: Fields[number]
+): field is Fields[number] & { relationType: 'many-to-many'; relatedTable: string } =>
+  'relationType' in field &&
+  field.relationType === 'many-to-many' &&
+  'relatedTable' in field &&
+  typeof field.relatedTable === 'string'
+
+/**
+ * Check if field has a related table
+ */
+const hasRelatedTable = (
+  field: Fields[number]
+): field is Fields[number] & { relatedTable: string } =>
+  'relatedTable' in field && typeof field.relatedTable === 'string'
+
+/**
+ * Generate lookup column expression
+ * Handles forward (many-to-one), reverse (one-to-many), and many-to-many lookups
+ */
+export const generateLookupExpression = (
+  lookupField: Fields[number] & {
+    readonly type: 'lookup'
+    readonly relationshipField: string
+    readonly relatedField: string
+    readonly filters?: ViewFilterCondition
+  },
+  tableAlias: string,
+  allFields: readonly Fields[number][],
+  actualTableName: string
+): string => {
+  const { name: lookupName, relationshipField, relatedField, filters } = lookupField
+  const relationshipFieldDef = allFields.find((f) => f.name === relationshipField)
+  const baseOptions = { lookupName, relationshipField, relatedField, filters, tableAlias }
+
+  // Reverse lookup (relationship field not in current table)
+  if (!relationshipFieldDef || relationshipFieldDef.type !== 'relationship') {
+    return generateReverseLookupExpression({ ...baseOptions, actualTableName })
+  }
+
+  // Many-to-many lookup (via junction table)
+  if (isManyToManyWithRelatedTable(relationshipFieldDef)) {
+    return generateManyToManyLookupExpression({
+      ...baseOptions,
+      relatedTable: relationshipFieldDef.relatedTable,
+      actualTableName,
+    })
+  }
+
+  // Forward lookup (many-to-one)
+  if (hasRelatedTable(relationshipFieldDef)) {
+    return generateForwardLookupExpression({
+      ...baseOptions,
+      relatedTable: relationshipFieldDef.relatedTable,
+    })
+  }
+
+  // Fallback: NULL if relationship is invalid
+  return `NULL AS ${lookupName}`
+}
+
+/**
+ * Map aggregation function name to PostgreSQL aggregate function
+ */
+const mapAggregationToPostgres = (aggregation: string, relatedField: string): string => {
+  const upperAgg = aggregation.toUpperCase()
+
+  switch (upperAgg) {
+    case 'SUM':
+      return `SUM(${relatedField})`
+    case 'COUNT':
+      return `COUNT(${relatedField})`
+    case 'AVG':
+      return `AVG(${relatedField})`
+    case 'MIN':
+      return `MIN(${relatedField})`
+    case 'MAX':
+      return `MAX(${relatedField})`
+    case 'COUNTA':
+      return `COUNT(CASE WHEN ${relatedField} IS NOT NULL AND ${relatedField} != '' THEN 1 END)`
+    case 'COUNTALL':
+      return `COUNT(*)`
+    case 'ARRAYUNIQUE':
+      return `ARRAY_AGG(DISTINCT ${relatedField} ORDER BY ${relatedField})`
+    default:
+      return `SUM(${relatedField})`
+  }
+}
+
+/**
+ * Generate default value for empty aggregation results
+ */
+const getDefaultValueForAggregation = (aggregation: string): string => {
+  const upperAgg = aggregation.toUpperCase()
+
+  switch (upperAgg) {
+    case 'AVG':
+    case 'MIN':
+    case 'MAX':
+      return 'NULL'
+    case 'ARRAYUNIQUE':
+      return 'ARRAY[]::TEXT[]'
+    default:
+      return '0'
+  }
+}
+
+/**
+ * Generate rollup column expression with aggregation
+ */
+export const generateRollupExpression = (
+  rollupField: Fields[number] & {
+    readonly type: 'rollup'
+    readonly relationshipField: string
+    readonly relatedField: string
+    readonly aggregation: string
+    readonly filters?: ViewFilterCondition
+  },
+  tableName: string,
+  allFields: readonly Fields[number][]
+): string => {
+  const { name: rollupName, relationshipField, relatedField, aggregation, filters } = rollupField
+
+  const relationshipFieldDef = allFields.find((f) => f.name === relationshipField)
+
+  if (!relationshipFieldDef || relationshipFieldDef.type !== 'relationship') {
+    return `${getDefaultValueForAggregation(aggregation)} AS ${rollupName}`
+  }
+
+  if (
+    !('relatedTable' in relationshipFieldDef) ||
+    typeof relationshipFieldDef.relatedTable !== 'string'
+  ) {
+    return `${getDefaultValueForAggregation(aggregation)} AS ${rollupName}`
+  }
+
+  const { relatedTable } = relationshipFieldDef
+  const alias = `${relatedTable}_for_${rollupName}`
+
+  const aggregationExpr = mapAggregationToPostgres(aggregation, `${alias}.${relatedField}`)
+  const defaultValue = getDefaultValueForAggregation(aggregation)
+
+  // Determine the foreign key column in the related table
+  const foreignKeyColumn =
+    'foreignKey' in relationshipFieldDef && typeof relationshipFieldDef.foreignKey === 'string'
+      ? relationshipFieldDef.foreignKey
+      : relationshipField
+
+  const baseCondition = `${alias}.${foreignKeyColumn} = ${tableName}.id`
+  const whereConditions = filters
+    ? [baseCondition, buildWhereClause(filters, alias)]
+    : [baseCondition]
+
+  const whereClause = whereConditions.join(' AND ')
+
+  return `COALESCE(
+    (SELECT ${aggregationExpr}
+     FROM ${relatedTable} AS ${alias}
+     WHERE ${whereClause}),
+    ${defaultValue}
+  ) AS ${rollupName}`
+}
+
+/**
+ * Generate count column expression with optional filtering
+ * Counts linked records from a relationship field, with optional conditions
+ */
+export const generateCountExpression = (
+  countField: Fields[number] & {
+    readonly type: 'count'
+    readonly relationshipField: string
+    readonly conditions?: readonly ViewFilterCondition[]
+  },
+  tableName: string,
+  allFields: readonly Fields[number][]
+): string => {
+  const { name: countName, relationshipField, conditions } = countField
+
+  const relationshipFieldDef = allFields.find((f) => f.name === relationshipField)
+
+  // Count field must reference a valid relationship field in same table
+  if (!relationshipFieldDef || relationshipFieldDef.type !== 'relationship') {
+    return `0 AS ${countName}`
+  }
+
+  if (
+    !('relatedTable' in relationshipFieldDef) ||
+    typeof relationshipFieldDef.relatedTable !== 'string'
+  ) {
+    return `0 AS ${countName}`
+  }
+
+  const { relatedTable } = relationshipFieldDef
+  const alias = `${relatedTable}_for_${countName}`
+
+  // Determine the foreign key column in the related table
+  const foreignKeyColumn =
+    'foreignKey' in relationshipFieldDef && typeof relationshipFieldDef.foreignKey === 'string'
+      ? relationshipFieldDef.foreignKey
+      : relationshipField
+
+  // Build WHERE clause with base condition + optional filter conditions
+  const baseCondition = `${alias}.${foreignKeyColumn} = ${tableName}.id`
+
+  // Convert conditions array to WHERE clauses
+  const filterConditions = conditions?.map((condition) => buildWhereClause(condition, alias)) ?? []
+
+  const whereConditions = [baseCondition, ...filterConditions]
+  const whereClause = whereConditions.join(' AND ')
+
+  // Use COALESCE to ensure 0 instead of NULL when no records match
+  return `COALESCE(
+    (SELECT COUNT(*)
+     FROM ${relatedTable} AS ${alias}
+     WHERE ${whereClause}),
+    0
+  ) AS ${countName}`
+}

package/src/infrastructure/database/lookup/lookup-expressions.ts

@@ -0,0 +1,116 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { toSingular, generateJunctionTableName } from '../sql/sql-generators'
+import { buildWhereClause } from './lookup-view-helpers'
+import type { ViewFilterCondition } from '@/domain/models/app/table/views/filters'
+
+/**
+ * Configuration for lookup expression generation
+ */
+export type LookupExpressionConfig = {
+  readonly lookupName: string
+  readonly relationshipField: string
+  readonly relatedField: string
+  readonly filters: ViewFilterCondition | undefined
+  readonly tableAlias: string
+  readonly actualTableName: string
+}
+
+/**
+ * Configuration for many-to-many lookup expression
+ */
+export type ManyToManyLookupConfig = {
+  readonly lookupName: string
+  readonly relatedTable: string
+  readonly relatedField: string
+  readonly filters: ViewFilterCondition | undefined
+  readonly tableAlias: string
+  readonly actualTableName: string
+}
+
+/**
+ * Configuration for forward lookup expression
+ */
+export type ForwardLookupConfig = {
+  readonly lookupName: string
+  readonly relationshipField: string
+  readonly relatedTable: string
+  readonly relatedField: string
+  readonly filters: ViewFilterCondition | undefined
+  readonly tableAlias: string
+}
+
+/**
+ * Generate reverse lookup expression (one-to-many)
+ */
+export const generateReverseLookupExpression = (config: LookupExpressionConfig): string => {
+  const { lookupName, relationshipField, relatedField, filters, tableAlias, actualTableName } =
+    config
+  // Infer table name from lookup field name (e.g., "active_tasks" → "tasks")
+  const lookupNameParts = lookupName.split('_')
+  const relatedTable = lookupNameParts[lookupNameParts.length - 1] ?? actualTableName
+
+  const alias = `${relatedTable}_for_${lookupName}`
+  const baseCondition = `${alias}.${relationshipField} = ${tableAlias}.id`
+  const whereConditions = filters
+    ? [baseCondition, buildWhereClause(filters, alias)]
+    : [baseCondition]
+  const whereClause = whereConditions.join(' AND ')
+
+  return `(
+    SELECT STRING_AGG(${alias}.${relatedField}::TEXT, ', ' ORDER BY ${alias}.${relatedField})
+    FROM ${relatedTable} AS ${alias}
+    WHERE ${whereClause}
+  ) AS ${lookupName}`
+}
+
+/**
+ * Generate many-to-many lookup expression (through junction table)
+ */
+export const generateManyToManyLookupExpression = (config: ManyToManyLookupConfig): string => {
+  const { lookupName, relatedTable, relatedField, filters, tableAlias, actualTableName } = config
+  const alias = `${relatedTable}_for_${lookupName}`
+  const junctionTable = generateJunctionTableName(actualTableName, relatedTable)
+  const junctionAlias = `junction_${lookupName}`
+  const foreignKeyInJunction = `${toSingular(actualTableName)}_id`
+  const relatedForeignKeyInJunction = `${toSingular(relatedTable)}_id`
+
+  const baseCondition = `${junctionAlias}.${foreignKeyInJunction} = ${tableAlias}.id`
+  const joinCondition = `${alias}.id = ${junctionAlias}.${relatedForeignKeyInJunction}`
+  const whereConditions = filters
+    ? [baseCondition, buildWhereClause(filters, alias)]
+    : [baseCondition]
+  const whereClause = whereConditions.join(' AND ')
+
+  return `(
+    SELECT STRING_AGG(${alias}.${relatedField}::TEXT, ', ' ORDER BY ${alias}.${relatedField})
+    FROM ${junctionTable} AS ${junctionAlias}
+    INNER JOIN ${relatedTable} AS ${alias} ON ${joinCondition}
+    WHERE ${whereClause}
+  ) AS ${lookupName}`
+}
+
+/**
+ * Generate forward lookup expression (many-to-one)
+ */
+export const generateForwardLookupExpression = (config: ForwardLookupConfig): string => {
+  const { lookupName, relationshipField, relatedTable, relatedField, filters, tableAlias } = config
+  const alias = `${relatedTable}_for_${lookupName}`
+
+  if (filters) {
+    const whereClause = buildWhereClause(filters, alias)
+    return `(
+      SELECT ${alias}.${relatedField}
+      FROM ${relatedTable} AS ${alias}
+      WHERE ${alias}.id = ${tableAlias}.${relationshipField} AND ${whereClause}
+    ) AS ${lookupName}`
+  }
+
+  // Direct column reference via LEFT JOIN (handled in main VIEW SELECT)
+  return `${alias}.${relatedField} AS ${lookupName}`
+}