sovrium 0.0.2

package/src/infrastructure/database/auth/auth-validation.ts

@@ -0,0 +1,101 @@
+/**
+ * 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 { Data } from 'effect'
+import { logInfo } from '@/infrastructure/logging/logger'
+import { isUserReferenceField, isUserField } from '../sql/sql-generators'
+import type { Table } from '@/domain/models/app/table'
+
+export class BetterAuthUsersTableRequired extends Data.TaggedError('BetterAuthUsersTableRequired')<{
+  readonly message: string
+}> {}
+
+/**
+ * Check if any table needs the users table for foreign keys
+ */
+export const needsUsersTable = (tables: readonly Table[]): boolean =>
+  tables.some((table) =>
+    table.fields.some((field) => isUserReferenceField(field) || isUserField(field))
+  )
+
+/**
+ * Check if any table has updated-by fields that need the trigger function
+ */
+export const needsUpdatedByTrigger = (tables: readonly Table[]): boolean =>
+  tables.some((table) => table.fields.some((field) => field.type === 'updated-by'))
+
+/**
+ * Verify Better Auth users table exists for foreign key references
+ *
+ * User fields (user, created-by, updated-by, deleted-by) require Better Auth's users table.
+ * Better Auth uses TEXT ids, so user fields store TEXT foreign keys.
+ *
+ * @throws BetterAuthUsersTableRequired if users table doesn't exist or lacks required columns
+ */
+/* eslint-disable functional/no-throw-statements */
+export const ensureBetterAuthUsersTable = async (tx: {
+  unsafe: (sql: string) => Promise<unknown>
+}): Promise<void> => {
+  logInfo('[ensureBetterAuthUsersTable] Verifying Better Auth users table exists...')
+
+  // Check if users table exists (in auth schema)
+  const tableExistsResult = (await tx.unsafe(`
+    SELECT EXISTS (
+      SELECT 1 FROM information_schema.tables
+      WHERE table_schema = 'auth' AND table_name = 'user'
+    ) as exists
+  `)) as readonly { exists: boolean }[]
+
+  if (!tableExistsResult[0]?.exists) {
+    throw new BetterAuthUsersTableRequired({
+      message:
+        'User fields require Better Auth users table. Please configure Better Auth authentication before using user, created-by, updated-by, or deleted-by field types.',
+    })
+  }
+
+  // Verify Better Auth schema (TEXT id column)
+  const idColumnResult = (await tx.unsafe(`
+    SELECT data_type FROM information_schema.columns
+    WHERE table_schema = 'auth' AND table_name = 'user' AND column_name = 'id'
+  `)) as readonly { data_type: string }[]
+
+  if (!idColumnResult[0]) {
+    throw new BetterAuthUsersTableRequired({
+      message:
+        'Users table exists but lacks id column. Please ensure Better Auth is properly configured.',
+    })
+  }
+
+  const idType = idColumnResult[0].data_type.toLowerCase()
+  if (idType !== 'text' && idType !== 'character varying') {
+    throw new BetterAuthUsersTableRequired({
+      message: `Users table has incompatible id column type '${idType}'. Better Auth uses TEXT ids. Please configure Better Auth authentication.`,
+    })
+  }
+
+  logInfo('[ensureBetterAuthUsersTable] Better Auth users table verified successfully')
+}
+/* eslint-enable functional/no-throw-statements */
+
+/**
+ * Ensure global set_updated_by trigger function exists
+ * This function is shared across all tables with updated-by fields
+ */
+/* eslint-disable functional/no-expression-statements */
+export const ensureUpdatedByTriggerFunction = async (tx: {
+  unsafe: (sql: string) => Promise<unknown>
+}): Promise<void> => {
+  await tx.unsafe(`
+    CREATE OR REPLACE FUNCTION set_updated_by()
+    RETURNS TRIGGER AS $$
+    BEGIN
+      RETURN NEW;
+    END;
+    $$ LANGUAGE plpgsql
+  `)
+}
+/* eslint-enable functional/no-expression-statements */

package/src/infrastructure/database/drizzle/db-bun.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 { drizzle } from 'drizzle-orm/bun-sql'
+import * as schema from './schema'
+
+// Bun-specific database driver using native bun:sql
+export const db = drizzle({
+  connection: { url: process.env.DATABASE_URL! },
+  schema,
+})
+
+export type DrizzleDB = typeof db

package/src/infrastructure/database/drizzle/db.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 type { DrizzleDB } from './db-bun'
+
+export { db } from './db-bun'
+export type { DrizzleDB } from './db-bun'
+
+/**
+ * Type for Drizzle transaction callback parameter
+ * Extracts the transaction type from the db.transaction method
+ */
+export type DrizzleTransaction = Parameters<Parameters<DrizzleDB['transaction']>[0]>[0]

package/src/infrastructure/database/drizzle/index.ts

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+
+/**
+ * Drizzle Database Module
+ *
+ * Provides database functionality using Drizzle ORM with Bun SQL.
+ * Re-exports all database-related services, schema, and types.
+ */
+export { db, type DrizzleDB } from './db'
+export { Database, DatabaseLive } from './layer'
+export * from './schema'

package/src/infrastructure/database/drizzle/layer.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 { Context, Layer } from 'effect'
+import { db, type DrizzleDB } from './db.js'
+
+/**
+ * Database Effect Context
+ *
+ * Provides Drizzle database instance for dependency injection in Effect programs.
+ * Use this in Application layer to access database without direct imports.
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const db = yield* Database
+ *   const users = yield* Effect.tryPromise(() => db.select().from(usersTable))
+ *   return users
+ * })
+ * ```
+ */
+export class Database extends Context.Tag('Database')<Database, DrizzleDB>() {}
+
+/**
+ * Live Database Layer
+ *
+ * Provides the production Drizzle database instance.
+ * Uses DATABASE_URL environment variable for connection.
+ */
+export const DatabaseLive = Layer.succeed(Database, db)

package/src/infrastructure/database/drizzle/migrate.ts

@@ -0,0 +1,77 @@
+/**
+ * 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 { SQL } from 'bun'
+import { drizzle } from 'drizzle-orm/bun-sql'
+import { migrate } from 'drizzle-orm/bun-sql/migrator'
+import { Effect, Console, Data } from 'effect'
+import * as schema from './schema'
+
+/**
+ * Error when database connection fails
+ */
+export class DatabaseConnectionError extends Data.TaggedError('DatabaseConnectionError')<{
+  readonly message: string
+  readonly cause?: unknown
+}> {}
+
+/**
+ * Error when migration fails
+ */
+export class MigrationError extends Data.TaggedError('MigrationError')<{
+  readonly message: string
+  readonly cause?: unknown
+}> {}
+
+/**
+ * Run Drizzle migrations to create/update database schema
+ *
+ * This applies all migrations from the ./drizzle folder:
+ * - Better Auth tables (users, sessions, accounts, etc.)
+ * - Migration audit tables (system.migration_history, etc.)
+ * - Auth schema with helper functions (auth.is_authenticated, auth.user_has_role)
+ *
+ * CRITICAL: Must run BEFORE initializeSchema() because:
+ * 1. User fields (created-by, updated-by, user) need users table to exist
+ * 2. The users table must be created before app-specific tables
+ * 3. initializeSchema() creates app-specific tables that reference users
+ *
+ * @param databaseUrl - PostgreSQL connection URL
+ * @returns Effect that completes when migrations are applied
+ */
+export const runMigrations = (
+  databaseUrl: string
+): Effect.Effect<void, DatabaseConnectionError | MigrationError> =>
+  Effect.gen(function* () {
+    yield* Console.log('[runMigrations] Running Drizzle migrations...')
+
+    const client = new SQL(databaseUrl)
+    const db = drizzle({ client, schema })
+
+    // Test database connection first to fail fast on connection errors
+    yield* Effect.tryPromise({
+      try: () => client.unsafe('SELECT 1'),
+      catch: (error) =>
+        new DatabaseConnectionError({
+          message: `Database connection failed: ${String(error)}`,
+          cause: error,
+        }),
+    })
+
+    yield* Effect.tryPromise({
+      try: () => migrate(db, { migrationsFolder: './drizzle' }),
+      catch: (error) =>
+        new MigrationError({
+          message: `Migration failed: ${String(error)}`,
+          cause: error,
+        }),
+    })
+
+    yield* Effect.promise(() => client.close())
+
+    yield* Console.log('[runMigrations] ✓ Drizzle migrations completed')
+  })

package/src/infrastructure/database/drizzle/schema/activity-log.ts

@@ -0,0 +1,111 @@
+/**
+ * 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 { sql } from 'drizzle-orm'
+import { text, timestamp, jsonb, index } from 'drizzle-orm/pg-core'
+import { users } from '../../../auth/better-auth/schema'
+import { systemSchema } from './migration-audit'
+
+/**
+ * Activity Action Type
+ *
+ * Defines the types of actions that can be recorded in the activity log.
+ * - create: A new record was created
+ * - update: An existing record was modified
+ * - delete: A record was soft-deleted or hard-deleted
+ * - restore: A soft-deleted record was restored
+ */
+export type ActivityAction = 'create' | 'update' | 'delete' | 'restore'
+
+/**
+ * Activity Log Changes Type
+ *
+ * Captures the before/after state of record modifications.
+ * - For 'create': only 'after' is populated
+ * - For 'update': both 'before' and 'after' are populated with changed fields
+ * - For 'delete': only 'before' is populated (or null for hard deletes)
+ * - For 'restore': both 'before' and 'after' are populated
+ */
+export type ActivityLogChanges = {
+  readonly before?: Record<string, unknown>
+  readonly after?: Record<string, unknown>
+}
+
+/**
+ * Activity Log Table Schema
+ *
+ * Central audit log tracking all data modifications across the application.
+ * Optimized for:
+ * - Time-range queries (recent activity)
+ * - User activity lookups (user audit trail)
+ * - Record history queries (record-specific changes)
+ *
+ * Retention: 1 year (compliance requirement)
+ *
+ * Authentication Optional:
+ * - userId is nullable to support anonymous activity logging
+ * - When Better Auth is not configured, activities are logged without user context
+ */
+export const activityLogs = systemSchema.table(
+  'activity_logs',
+  {
+    // Primary key - UUID for distributed systems compatibility
+    // Default generates UUID automatically via PostgreSQL gen_random_uuid()
+    id: text('id')
+      .primaryKey()
+      .default(sql`gen_random_uuid()`),
+
+    // Event metadata
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+
+    // User who performed the action (null when auth disabled)
+    userId: text('user_id').references(() => users.id, { onDelete: 'set null' }),
+
+    // Optional session tracking for additional context
+    sessionId: text('session_id'),
+
+    // Action type: create, update, delete, restore
+    action: text('action').notNull().$type<ActivityAction>(),
+
+    // Table identification
+    tableName: text('table_name').notNull(),
+    // tableId is optional - not all activity sources have a table schema ID
+    tableId: text('table_id'),
+
+    // Record identification within the table
+    recordId: text('record_id').notNull(),
+
+    // Change tracking - JSONB for efficient storage and querying
+    // Contains { before?: {...}, after?: {...} }
+    changes: jsonb('changes').$type<ActivityLogChanges>(),
+
+    // Request context for security auditing
+    ipAddress: text('ip_address'),
+    userAgent: text('user_agent'),
+  },
+  (table) => [
+    // Index for recent activity queries (most common)
+    // Supports: GET /api/activity (sorted by createdAt DESC)
+    index('activity_logs_created_at_idx').on(table.createdAt),
+
+    // Composite index for user activity queries
+    // Supports: GET /api/users/:userId/activity
+    index('activity_logs_user_created_at_idx').on(table.userId, table.createdAt),
+
+    // Composite index for record history queries
+    // Supports: GET /api/tables/:tableId/records/:recordId/history
+    index('activity_logs_table_record_idx').on(table.tableName, table.recordId),
+
+    // Index for filtering by action type
+    // Supports: GET /api/activity?action=create
+    index('activity_logs_action_idx').on(table.action),
+  ]
+)
+
+// Type exports for consumers
+export type ActivityLog = typeof activityLogs.$inferSelect
+export type NewActivityLog = typeof activityLogs.$inferInsert

package/src/infrastructure/database/drizzle/schema/analytics-page-views.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 { sql } from 'drizzle-orm'
+import { boolean, index, smallint, text, timestamp } from 'drizzle-orm/pg-core'
+import { systemSchema } from './migration-audit'
+
+/**
+ * Analytics Page Views Table Schema
+ *
+ * Stores individual page view events for the built-in analytics engine.
+ * Designed for privacy-first tracking without cookies or PII.
+ *
+ * Key design decisions:
+ * - visitorHash: SHA-256(date + IP + UA + salt) — rotates daily, no PII stored
+ * - sessionHash: SHA-256(visitorHash + time-window) — groups views into sessions
+ * - No foreign keys to users table — analytics is anonymous
+ * - All device/browser/OS data parsed server-side from User-Agent
+ * - UTM parameters captured from tracking script payload
+ *
+ * Indexes optimized for:
+ * - Time-series queries (overview, trends)
+ * - Unique visitor counting
+ * - Per-page analytics
+ * - Referrer analysis
+ * - UTM campaign analysis
+ * - Device breakdown queries
+ */
+export const analyticsPageViews = systemSchema.table(
+  'analytics_page_views',
+  {
+    // Primary key - UUID for distributed systems compatibility
+    id: text('id')
+      .primaryKey()
+      .default(sql`gen_random_uuid()`),
+
+    // Event timestamp
+    timestamp: timestamp('timestamp', { withTimezone: true }).notNull().defaultNow(),
+
+    // Application identifier (supports multi-app deployments)
+    // Default 'default' enables direct INSERTs via system.page_views view without explicit app_name
+    appName: text('app_name').notNull().default('default'),
+
+    // Page information
+    pagePath: text('page_path').notNull(),
+    pageTitle: text('page_title'),
+
+    // Privacy-safe visitor identification (no cookies, no PII)
+    // SHA-256(date + IP + UA + salt) — rotates daily
+    visitorHash: text('visitor_hash').notNull(),
+
+    // Session identification
+    // SHA-256(visitorHash + time-window) — groups views into sessions
+    // Default gen_random_uuid() enables direct INSERTs via system.page_views view without explicit session_hash
+    sessionHash: text('session_hash')
+      .notNull()
+      .default(sql`gen_random_uuid()`),
+
+    // Whether this is the first page view in a session
+    isEntrance: boolean('is_entrance').notNull().default(false),
+
+    // Referrer information
+    referrerUrl: text('referrer_url'),
+    referrerDomain: text('referrer_domain'),
+
+    // UTM campaign parameters
+    utmSource: text('utm_source'),
+    utmMedium: text('utm_medium'),
+    utmCampaign: text('utm_campaign'),
+    utmContent: text('utm_content'),
+    utmTerm: text('utm_term'),
+
+    // Device information (parsed from User-Agent server-side)
+    deviceType: text('device_type'), // 'desktop' | 'mobile' | 'tablet'
+    browserName: text('browser_name'),
+    osName: text('os_name'),
+
+    // Visitor locale (from Accept-Language header)
+    language: text('language'),
+
+    // Screen dimensions (from tracking script)
+    screenWidth: smallint('screen_width'),
+    screenHeight: smallint('screen_height'),
+  },
+  (table) => [
+    // Primary time-series index (overview queries, date range filtering)
+    index('analytics_pv_app_timestamp_idx').on(table.appName, table.timestamp),
+
+    // Unique visitor counting
+    index('analytics_pv_app_visitor_timestamp_idx').on(
+      table.appName,
+      table.visitorHash,
+      table.timestamp
+    ),
+
+    // Per-page analytics (top pages queries)
+    index('analytics_pv_app_path_timestamp_idx').on(table.appName, table.pagePath, table.timestamp),
+
+    // Referrer analysis (traffic sources queries)
+    index('analytics_pv_app_referrer_idx').on(table.appName, table.referrerDomain),
+
+    // UTM campaign analysis
+    index('analytics_pv_app_utm_source_idx').on(table.appName, table.utmSource),
+
+    // Device breakdown queries
+    index('analytics_pv_app_device_idx').on(table.appName, table.deviceType),
+  ]
+)
+
+// Type exports for consumers
+export type AnalyticsPageView = typeof analyticsPageViews.$inferSelect
+export type NewAnalyticsPageView = typeof analyticsPageViews.$inferInsert

package/src/infrastructure/database/drizzle/schema/migration-audit.ts

@@ -0,0 +1,68 @@
+/**
+ * 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 { pgSchema, serial, integer, text, timestamp, jsonb } from 'drizzle-orm/pg-core'
+
+/**
+ * System Schema
+ *
+ * Dedicated PostgreSQL schema for internal Sovrium tables.
+ * Isolates system tables from user data tables.
+ */
+export const systemSchema = pgSchema('system')
+
+/**
+ * Migration History Table Schema
+ *
+ * Tracks all schema migrations with timestamps and checksums.
+ * Each migration is recorded with a version number and the complete schema snapshot.
+ */
+export const sovriumMigrationHistory = systemSchema.table('migration_history', {
+  id: serial('id').primaryKey(),
+  version: integer('version').notNull(),
+  checksum: text('checksum').notNull(),
+  schema: jsonb('schema'),
+  appliedAt: timestamp('applied_at').defaultNow(),
+  rolledBackAt: timestamp('rolled_back_at'),
+})
+
+/**
+ * Migration Log Table Schema
+ *
+ * Tracks migration operations including rollbacks with status and reason.
+ * Used for debugging and audit trail of schema changes.
+ */
+export const sovriumMigrationLog = systemSchema.table('migration_log', {
+  id: serial('id').primaryKey(),
+  operation: text('operation').notNull(),
+  fromVersion: integer('from_version'),
+  toVersion: integer('to_version'),
+  reason: text('reason'),
+  status: text('status').notNull(),
+  createdAt: timestamp('created_at').defaultNow(),
+})
+
+/**
+ * Schema Checksum Table Schema
+ *
+ * Singleton table storing current schema checksum for change detection.
+ * Uses a single row with id='singleton' to track the current state.
+ */
+export const sovriumSchemaChecksum = systemSchema.table('schema_checksum', {
+  id: text('id').primaryKey(),
+  checksum: text('checksum').notNull(),
+  schema: jsonb('schema').notNull(),
+  updatedAt: timestamp('updated_at').defaultNow(),
+})
+
+// Type exports for consumers
+export type SovriumMigrationHistory = typeof sovriumMigrationHistory.$inferSelect
+export type NewSovriumMigrationHistory = typeof sovriumMigrationHistory.$inferInsert
+export type SovriumMigrationLog = typeof sovriumMigrationLog.$inferSelect
+export type NewSovriumMigrationLog = typeof sovriumMigrationLog.$inferInsert
+export type SovriumSchemaChecksum = typeof sovriumSchemaChecksum.$inferSelect
+export type NewSovriumSchemaChecksum = typeof sovriumSchemaChecksum.$inferInsert

package/src/infrastructure/database/drizzle/schema/record-comments.ts

@@ -0,0 +1,79 @@
+/**
+ * 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 { text, timestamp, index } from 'drizzle-orm/pg-core'
+import { users } from '../../../auth/better-auth/schema'
+import { systemSchema } from './migration-audit'
+
+/**
+ * Record Comments Table Schema
+ *
+ * Enables users to add comments to records in any table, similar to Airtable/Notion.
+ * Comments are flat (no threading), chronological, and support @mentions.
+ *
+ * Features:
+ * - Authentication required: Comments must have a user_id (no anonymous comments)
+ * - Soft delete: deleted_at for restoration capability
+ * - @mentions: Stored as user IDs in content (e.g., @[user_123])
+ * - Table validation: Comments tied to specific table_id for validation
+ *
+ * Authorization:
+ * - Read: Same permissions as the record itself (if you can read the record, you can read comments)
+ * - Create: Any authenticated user who can read the record can comment
+ * - Update: Only comment author can edit their own comments
+ * - Delete: Comment author OR admins can delete comments
+ *
+ * Optimized for:
+ * - Fetching all comments for a record (most common query)
+ * - User activity lookups (all comments by a user)
+ * - Soft delete filtering (excluding deleted comments by default)
+ */
+export const recordComments = systemSchema.table(
+  'record_comments',
+  {
+    // Primary key - UUID for distributed systems compatibility
+    id: text('id').primaryKey(),
+
+    // Record identification
+    recordId: text('record_id').notNull(),
+    tableId: text('table_id').notNull(),
+
+    // User who created the comment (required - no anonymous comments)
+    userId: text('user_id')
+      .notNull()
+      .references(() => users.id, { onDelete: 'cascade' }),
+
+    // Comment content - supports @mentions as @[user_id] format
+    // Max length enforced at application layer
+    content: text('content').notNull(),
+
+    // Timestamps
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+
+    // Soft delete support
+    deletedAt: timestamp('deleted_at', { withTimezone: true }),
+  },
+  (table) => [
+    // Composite index for fetching all comments on a record (most common query)
+    // Supports: GET /api/tables/:tableId/records/:recordId/comments
+    // Ordered by createdAt for chronological display
+    index('record_comments_record_created_idx').on(table.tableId, table.recordId, table.createdAt),
+
+    // Composite index for user activity queries
+    // Supports: GET /api/users/:userId/comments
+    index('record_comments_user_created_idx').on(table.userId, table.createdAt),
+
+    // Index for soft delete filtering
+    // Supports: WHERE deleted_at IS NULL (default query behavior)
+    index('record_comments_deleted_at_idx').on(table.deletedAt),
+  ]
+)
+
+// Type exports for consumers
+export type RecordComment = typeof recordComments.$inferSelect
+export type NewRecordComment = typeof recordComments.$inferInsert

package/src/infrastructure/database/drizzle/schema.ts

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+
+export * from '../../auth/better-auth/schema'
+export * from './schema/migration-audit'
+export * from './schema/activity-log'
+export * from './schema/analytics-page-views'
+export * from './schema/record-comments'