@intelligo-dev/core 1.0.0-beta.1 → 1.0.0-beta.14

package/src/db/schema/identity.ts

@@ -0,0 +1,250 @@
+/**
+ * The user identity graph: a user's facts, episodic memories and audit
+ * trail, synthesized into one profile snapshot an agent session reads in
+ * one query.
+ *
+ *  - `user_facts`: the structured source of truth, queryable by category
+ *    and weighted by confidence and importance.
+ *  - `user_memories`: unstructured episodic recall via pgvector search.
+ *  - `user_profile_snapshots`: the cached synthesis, since voice agents
+ *    cannot rebuild the profile inside a turn's latency budget.
+ *  - `user_memory_audit`: append-only log of every write, so a user can see
+ *    where each fact came from.
+ */
+
+import {
+  pgTable,
+  primaryKey,
+  text,
+  timestamp,
+  integer,
+  index,
+  uniqueIndex,
+  jsonb,
+  doublePrecision,
+} from "drizzle-orm/pg-core";
+import { vector } from "drizzle-orm/pg-core/columns/vector_extension/vector";
+import { organization, users } from "./auth";
+
+/**
+ * A fact's category, the filter axis for synthesis and display. A closed
+ * list on purpose: a new category is a decision, not a free-form string.
+ */
+export const USER_FACT_CATEGORIES = [
+  "interest",
+  "skill",
+  "goal",
+  "constraint",
+  "trait",
+  "value",
+  "preference",
+  "context",
+  "background",
+] as const;
+
+export type UserFactCategory = (typeof USER_FACT_CATEGORIES)[number];
+
+/**
+ * How a fact entered the system. "explicit_user_input" facts are
+ * considered ground truth and survive conflict resolution against
+ * lower-confidence LLM extractions.
+ */
+export const USER_FACT_EXTRACTION_METHODS = [
+  "llm_extraction",
+  "explicit_user_input",
+  "inline_tool",
+  "onboarding_form",
+] as const;
+
+export type UserFactExtractionMethod =
+  (typeof USER_FACT_EXTRACTION_METHODS)[number];
+
+export const userFacts = pgTable(
+  "user_facts",
+  {
+    id: text("id").primaryKey(),
+    userId: text("user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    workspaceId: text("workspace_id")
+      .notNull()
+      .references(() => organization.id, { onDelete: "cascade" }),
+
+    category: text("category").$type<UserFactCategory>().notNull(),
+    key: text("key").notNull(),
+    value: jsonb("value").notNull(),
+    confidence: doublePrecision("confidence").notNull(),
+    importance: integer("importance").notNull().default(5),
+
+    sourceProduct: text("source_product"),
+    sourceSessionId: text("source_session_id"),
+    sourceMessageId: text("source_message_id"),
+    extractionMethod:
+      text("extraction_method").$type<UserFactExtractionMethod>(),
+
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    lastConfirmedAt: timestamp("last_confirmed_at"),
+    expiresAt: timestamp("expires_at"),
+  },
+  (table) => [
+    index("user_facts_user_idx").on(table.userId),
+    index("user_facts_workspace_idx").on(table.workspaceId),
+    index("user_facts_category_idx").on(table.workspaceId, table.category),
+    // Scoped to (user, workspace, category, key) so members of a shared
+    // workspace can hold the same fact key without collision.
+    uniqueIndex("user_facts_user_workspace_category_key_uniq").on(
+      table.userId,
+      table.workspaceId,
+      table.category,
+      table.key
+    ),
+  ]
+);
+
+export const USER_MEMORY_KINDS = [
+  "conversation_summary",
+  "event",
+  "insight",
+  "preference_statement",
+  "decision",
+  "struggle",
+  "success",
+] as const;
+
+export type UserMemoryKind = (typeof USER_MEMORY_KINDS)[number];
+
+export const userMemories = pgTable(
+  "user_memories",
+  {
+    id: text("id").primaryKey(),
+    userId: text("user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    workspaceId: text("workspace_id")
+      .notNull()
+      .references(() => organization.id, { onDelete: "cascade" }),
+
+    kind: text("kind").$type<UserMemoryKind>().notNull(),
+    content: text("content").notNull(),
+    embedding: vector({ dimensions: 1536 }),
+
+    sourceProduct: text("source_product"),
+    sourceSessionId: text("source_session_id"),
+    sourceMessageIds: text("source_message_ids").array(),
+
+    importance: integer("importance").notNull().default(5),
+    decayFactor: doublePrecision("decay_factor").notNull().default(1.0),
+    metadata: jsonb("metadata"),
+
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+  },
+  (table) => [
+    index("user_memories_user_idx").on(table.userId),
+    index("user_memories_workspace_idx").on(table.workspaceId),
+    index("user_memories_kind_idx").on(table.workspaceId, table.kind),
+    // The pgvector index is created in migration SQL: drizzle-orm cannot
+    // express it.
+  ]
+);
+
+export const SYNTHESIS_TRIGGER_REASONS = [
+  "fact_threshold",
+  "session_close",
+  "daily_cron",
+  "manual",
+] as const;
+
+export type SynthesisTriggerReason = (typeof SYNTHESIS_TRIGGER_REASONS)[number];
+
+export const userProfileSnapshots = pgTable(
+  "user_profile_snapshots",
+  {
+    userId: text("user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    workspaceId: text("workspace_id")
+      .notNull()
+      .references(() => organization.id, { onDelete: "cascade" }),
+    version: integer("version").notNull(),
+
+    summary: text("summary").notNull(),
+    summaryEn: text("summary_en"),
+    summaryMn: text("summary_mn"),
+
+    factsDigest: jsonb("facts_digest").notNull(),
+    activeGoals: jsonb("active_goals"),
+    personalitySignals: jsonb("personality_signals"),
+    relationshipNotes: jsonb("relationship_notes"),
+
+    synthesizedByModel: text("synthesized_by_model"),
+    synthesizedAt: timestamp("synthesized_at").notNull().defaultNow(),
+    nextSynthesisAt: timestamp("next_synthesis_at"),
+    triggerReason: text("trigger_reason").$type<SynthesisTriggerReason>(),
+  },
+  // One snapshot per user per workspace: a user in two workspaces gets two
+  // distinct profiles.
+  (table) => [
+    primaryKey({ columns: [table.userId, table.workspaceId] }),
+    index("user_profile_snapshots_workspace_idx").on(table.workspaceId),
+  ]
+);
+
+export const AUDIT_TARGET_KINDS = ["fact", "memory", "snapshot"] as const;
+export type AuditTargetKind = (typeof AUDIT_TARGET_KINDS)[number];
+
+export const AUDIT_ACTIONS = [
+  "create",
+  "update",
+  "delete",
+  "view",
+  "export",
+] as const;
+export type AuditAction = (typeof AUDIT_ACTIONS)[number];
+
+export const AUDIT_ACTOR_KINDS = [
+  "agent",
+  "user",
+  "system_job",
+  "admin",
+] as const;
+export type AuditActorKind = (typeof AUDIT_ACTOR_KINDS)[number];
+
+export const userMemoryAudit = pgTable(
+  "user_memory_audit",
+  {
+    id: text("id").primaryKey(),
+    userId: text("user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    workspaceId: text("workspace_id")
+      .notNull()
+      .references(() => organization.id, { onDelete: "cascade" }),
+
+    targetKind: text("target_kind").$type<AuditTargetKind>().notNull(),
+    targetId: text("target_id").notNull(),
+    action: text("action").$type<AuditAction>().notNull(),
+    actorKind: text("actor_kind").$type<AuditActorKind>().notNull(),
+    actorId: text("actor_id"),
+
+    beforeValue: jsonb("before_value"),
+    afterValue: jsonb("after_value"),
+    reason: text("reason"),
+
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+  },
+  (table) => [
+    index("user_memory_audit_user_idx").on(table.userId),
+    index("user_memory_audit_workspace_idx").on(table.workspaceId),
+    index("user_memory_audit_target_idx").on(table.targetKind, table.targetId),
+  ]
+);
+
+export type UserFact = typeof userFacts.$inferSelect;
+export type InsertUserFact = typeof userFacts.$inferInsert;
+export type UserMemory = typeof userMemories.$inferSelect;
+export type InsertUserMemory = typeof userMemories.$inferInsert;
+export type UserProfileSnapshot = typeof userProfileSnapshots.$inferSelect;
+export type InsertUserProfileSnapshot =
+  typeof userProfileSnapshots.$inferInsert;
+export type UserMemoryAuditRow = typeof userMemoryAudit.$inferSelect;
+export type InsertUserMemoryAudit = typeof userMemoryAudit.$inferInsert;

package/src/db/schema/index.ts

@@ -0,0 +1,12 @@
+// Better-Auth's tables, including organization, member and invitation.
+// Product code goes through the Better-Auth API rather than querying the
+// organization tables directly, so membership and role rules stay in one
+// place.
+export * from "./auth";
+export * from "./billing";
+export * from "./usage";
+export * from "./notifications";
+export * from "./feature-flags";
+export * from "./ai";
+export * from "./agents";
+export * from "./identity";

package/src/db/schema/notifications.ts

@@ -0,0 +1,31 @@
+import { pgTable, text, timestamp, boolean, index } from "drizzle-orm/pg-core";
+
+/**
+ * User-scoped, not workspace-scoped, so a user sees their notifications from
+ * every workspace in one place. `userId` references the users table by
+ * convention (no FK); `workspaceId` is null for user-level notifications.
+ */
+export const notifications = pgTable(
+  "notifications",
+  {
+    id: text("id")
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
+    userId: text("user_id").notNull(),
+    workspaceId: text("workspace_id"),
+    type: text("type").notNull(),
+    title: text("title").notNull(),
+    message: text("message").notNull(),
+    isRead: boolean("is_read").notNull().default(false),
+    metadata: text("metadata"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+  },
+  (table) => [
+    index("notifications_user_id_idx").on(table.userId),
+    index("notifications_user_id_is_read_idx").on(table.userId, table.isRead),
+    index("notifications_created_at_idx").on(table.createdAt),
+  ]
+);
+
+export type Notification = typeof notifications.$inferSelect;
+export type InsertNotification = typeof notifications.$inferInsert;

package/src/db/schema/usage.ts

@@ -0,0 +1,269 @@
+/**
+ * Token consumption per request and aggregated per period, which the quota
+ * engine checks before AI requests and records into after them.
+ */
+
+import {
+  pgTable,
+  text,
+  timestamp,
+  integer,
+  bigint,
+  real,
+  index,
+  unique,
+  jsonb,
+} from "drizzle-orm/pg-core";
+import { organization, users } from "./auth";
+
+/**
+ * One row per AI request: tokens, model and agent, for per-model and
+ * per-agent reporting.
+ */
+export const usageRecords = pgTable(
+  "usage_records",
+  {
+    id: text("id").primaryKey(),
+    workspaceId: text("workspace_id")
+      .notNull()
+      .references(() => organization.id, { onDelete: "cascade" }),
+    userId: text("user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    type: text("type").notNull(), // "ai_tokens", "api_call"
+    model: text("model"), // "gpt-4o", "gpt-4o-mini"
+    agent: text("agent"), // the product's agent slug
+    inputTokens: integer("input_tokens").notNull().default(0),
+    outputTokens: integer("output_tokens").notNull().default(0),
+    totalTokens: integer("total_tokens").notNull().default(0),
+    /**
+     * What the provider charged, in USD micros. Integer on purpose: float
+     * arithmetic accumulates sub-cent error over many records.
+     */
+    providerCostMicros: bigint("provider_cost_micros", { mode: "number" })
+      .notNull()
+      .default(0),
+    /** Snapshots of the rate and margin this charge was computed with. */
+    marginBp: integer("margin_bp").notNull().default(0),
+    usdRateMicros: bigint("usd_rate_micros", { mode: "number" })
+      .notNull()
+      .default(0),
+    /** Authoritative charge, in micros of `currency`. */
+    chargedMicros: bigint("charged_micros", { mode: "number" })
+      .notNull()
+      .default(0),
+    currency: text("currency").notNull().default("USD"),
+    /** Request correlation id for log tracing */
+    requestId: text("request_id"),
+    /**
+     * Owning execution (@intelligo-dev/executions). No FK: the executions
+     * table is owned by another package and this column is written by
+     * the settlement path, which may run before or after the execution
+     * row's terminal update.
+     */
+    executionId: text("execution_id"),
+    /** Conversation/chat id for grouping in usage dashboards */
+    conversationId: text("conversation_id"),
+    metadata: text("metadata"), // JSON string for additional data
+    recordedAt: timestamp("recorded_at").notNull().defaultNow(),
+  },
+  (table) => [
+    index("usage_records_workspace_id_idx").on(table.workspaceId),
+    index("usage_records_workspace_recorded_at_idx").on(
+      table.workspaceId,
+      table.recordedAt
+    ),
+    index("usage_records_workspace_type_idx").on(table.workspaceId, table.type),
+    index("usage_records_conversation_id_idx").on(table.conversationId),
+    index("usage_records_execution_id_idx").on(table.executionId),
+  ]
+);
+
+/**
+ * One row per workspace per billing period, incremented atomically, so a
+ * quota check is O(1) instead of a SUM over usage_records.
+ */
+export const monthlyUsage = pgTable(
+  "monthly_usage",
+  {
+    id: text("id").primaryKey(),
+    workspaceId: text("workspace_id")
+      .notNull()
+      .references(() => organization.id, { onDelete: "cascade" }),
+    periodStart: timestamp("period_start").notNull(),
+    periodEnd: timestamp("period_end").notNull(),
+    tokensUsed: integer("tokens_used").notNull().default(0),
+    /** The plan allowance spent this period, in micros of `currency`. */
+    allowanceUsedMicros: bigint("allowance_used_micros", { mode: "number" })
+      .notNull()
+      .default(0),
+    currency: text("currency").notNull().default("USD"),
+    requestCount: integer("request_count").notNull().default(0),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+  },
+  (table) => [
+    unique("monthly_usage_workspace_period_unique").on(
+      table.workspaceId,
+      table.periodStart
+    ),
+    index("monthly_usage_workspace_id_idx").on(table.workspaceId),
+  ]
+);
+
+/**
+ * One-time trial grant, one per workspace (unique constraint). Separate from
+ * purchased credits; used when the plan quota is exceeded or the credit
+ * balance is zero. Status: active → depleted, converted or expired.
+ */
+export const trialCredits = pgTable(
+  "trial_credits",
+  {
+    id: text("id").primaryKey(),
+    workspaceId: text("workspace_id")
+      .notNull()
+      .unique()
+      .references(() => organization.id, { onDelete: "cascade" }),
+    initialCredits: integer("initial_credits").notNull().default(100000),
+    creditsUsed: integer("credits_used").notNull().default(0),
+    creditsRemaining: integer("credits_remaining").notNull().default(100000),
+    /** The grant, in micros of `currency`. */
+    initialMicros: bigint("initial_micros", { mode: "number" })
+      .notNull()
+      .default(0),
+    usedMicros: bigint("used_micros", { mode: "number" }).notNull().default(0),
+    remainingMicros: bigint("remaining_micros", { mode: "number" })
+      .notNull()
+      .default(0),
+    currency: text("currency").notNull().default("USD"),
+    status: text("status").notNull().default("active"), // active|depleted|converted|expired
+    provisionedAt: timestamp("provisioned_at").notNull().defaultNow(),
+    trialEndDate: timestamp("trial_end_date"), // 14 days from provisioning
+    depletedAt: timestamp("depleted_at"),
+    convertedAt: timestamp("converted_at"),
+    createdByIp: text("created_by_ip"),
+    createdByEmail: text("created_by_email"),
+    /**
+     * Canonical form of createdByEmail for the per-email abuse check,
+     * stored so the count can use an index instead of a full-table scan.
+     */
+    normalizedEmail: text("normalized_email"),
+  },
+  (table) => [
+    index("trial_credits_expiry_idx").on(table.status, table.trialEndDate),
+    index("trial_credits_normalized_email_idx").on(table.normalizedEmail),
+  ]
+);
+
+/**
+ * One row per (workspace, endpoint, minute bucket). Each request upserts the
+ * row and atomically increments `count`, so N concurrent requests observe
+ * 1..N and exactly `limit` are admitted. Old buckets are deleted by the
+ * billing-maintenance job.
+ */
+export const rateLimitEntries = pgTable(
+  "rate_limit_entries",
+  {
+    id: text("id").primaryKey(),
+    workspaceId: text("workspace_id")
+      .notNull()
+      .references(() => organization.id, { onDelete: "cascade" }),
+    endpoint: text("endpoint").notNull().default("chat"),
+    requestedAt: timestamp("requested_at").notNull().defaultNow(),
+    /** Floored minute bucket for unique constraint enforcement */
+    minuteBucket: timestamp("minute_bucket").notNull(),
+    /** Requests observed in this bucket — incremented via upsert */
+    count: integer("count").notNull().default(1),
+  },
+  (table) => [
+    index("rate_limit_entries_window_idx").on(
+      table.workspaceId,
+      table.endpoint,
+      table.requestedAt
+    ),
+    unique("rate_limit_entries_unique_bucket_idx").on(
+      table.workspaceId,
+      table.endpoint,
+      table.minuteBucket
+    ),
+  ]
+);
+
+/**
+ * Sent quota and trial notifications. The unique constraint on
+ * (workspaceId, type, periodKey) keeps one notification from being sent
+ * twice in a billing period.
+ */
+export const notificationHistory = pgTable(
+  "notification_history",
+  {
+    id: text("id").primaryKey(),
+    workspaceId: text("workspace_id")
+      .notNull()
+      .references(() => organization.id, { onDelete: "cascade" }),
+    type: text("type").notNull(), // "quota_warning_80", "quota_warning_100", "trial_warning_20", "trial_depleted"
+    periodKey: text("period_key").notNull(), // "2026-02" for monthly, "trial" for one-time
+    sentAt: timestamp("sent_at").notNull().defaultNow(),
+    channel: text("channel").notNull().default("console"), // "console" | "email"
+    metadata: text("metadata"), // JSON string for additional context
+  },
+  (table) => [
+    unique("notification_history_dedup_unique").on(
+      table.workspaceId,
+      table.type,
+      table.periodKey
+    ),
+    index("notification_history_workspace_id_idx").on(table.workspaceId),
+  ]
+);
+
+/**
+ * Per-user, per-action usage counters, one row per user and workspace (not
+ * per period). Counters live in the `usage` JSONB map and increment
+ * atomically in SQL, so a quota check is O(1).
+ */
+export const userQuotas = pgTable(
+  "user_quotas",
+  {
+    id: text("id").primaryKey(),
+    userId: text("user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    workspaceId: text("workspace_id")
+      .notNull()
+      .references(() => organization.id, { onDelete: "cascade" }),
+    plan: text("plan").notNull().default("free"), // free | standard | pro
+    /**
+     * Per-action counters keyed by the product's own action slugs
+     * (`usage["chat"] = 42`), so a product adds a counter without a
+     * migration.
+     */
+    usage: jsonb("usage").notNull().default({}),
+    totalCostUsd: real("total_cost_usd").notNull().default(0),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+  },
+  (table) => [
+    index("user_quotas_user_id_idx").on(table.userId),
+    index("user_quotas_workspace_id_idx").on(table.workspaceId),
+    // Unique per (user, workspace), not per user: a user in a paid and a
+    // free workspace must not share one plan and one set of counters.
+    unique("user_quotas_user_workspace_unique").on(
+      table.userId,
+      table.workspaceId
+    ),
+  ]
+);
+
+export type UserQuota = typeof userQuotas.$inferSelect;
+export type InsertUserQuota = typeof userQuotas.$inferInsert;
+export type UsageRecord = typeof usageRecords.$inferSelect;
+export type InsertUsageRecord = typeof usageRecords.$inferInsert;
+export type MonthlyUsage = typeof monthlyUsage.$inferSelect;
+export type InsertMonthlyUsage = typeof monthlyUsage.$inferInsert;
+export type TrialCredit = typeof trialCredits.$inferSelect;
+export type InsertTrialCredit = typeof trialCredits.$inferInsert;
+export type RateLimitEntry = typeof rateLimitEntries.$inferSelect;
+export type InsertRateLimitEntry = typeof rateLimitEntries.$inferInsert;
+export type NotificationHistoryRecord = typeof notificationHistory.$inferSelect;
+export type InsertNotificationHistoryRecord =
+  typeof notificationHistory.$inferInsert;

package/src/db/validate.ts

@@ -0,0 +1,63 @@
+import { db } from "./client";
+import { sql } from "drizzle-orm";
+
+export interface DatabaseValidationResult {
+  isConnected: boolean;
+  tablesExist: boolean;
+  error?: string;
+}
+
+/** Checks that the database answers and the four auth tables exist. */
+export async function validateDatabaseConnection(): Promise<DatabaseValidationResult> {
+  try {
+    await db.execute(sql`SELECT 1`);
+
+    const result = await db.execute(sql`
+      SELECT COUNT(*) as table_count
+      FROM information_schema.tables
+      WHERE table_schema = 'public'
+      AND table_name IN ('users', 'sessions', 'accounts', 'verifications')
+    `);
+
+    const tableCount = Number(result.rows[0]?.table_count ?? 0);
+    const tablesExist = tableCount === 4;
+
+    return {
+      isConnected: true,
+      tablesExist,
+      error: tablesExist
+        ? undefined
+        : "Auth tables do not exist. Run 'intelligo migrate' to apply the framework's migration chain.",
+    };
+  } catch (error) {
+    return {
+      isConnected: false,
+      tablesExist: false,
+      error: error instanceof Error ? error.message : "Unknown database error",
+    };
+  }
+}
+
+/** Startup check: throws with setup instructions when validation fails. */
+export async function requireDatabaseConnection(): Promise<void> {
+  const result = await validateDatabaseConnection();
+
+  if (!result.isConnected) {
+    throw new Error(
+      `❌ Database connection failed: ${result.error}\n\n` +
+        `Make sure DATABASE_URL is configured in .env.local\n` +
+        `Example: DATABASE_URL=postgres://user:pass@host/db`
+    );
+  }
+
+  if (!result.tablesExist) {
+    throw new Error(
+      `❌ Database tables do not exist.\n\n` +
+        `Run the following commands to set up the database:\n` +
+        `  1. intelligo migrate   (applies the framework's migration chain)\n` +
+        `  2. drizzle-kit migrate (your own tables, if any)`
+    );
+  }
+
+  console.log("✓ Database connection validated");
+}

package/src/db/workspace-queries.ts

@@ -0,0 +1,64 @@
+/**
+ * Workspace scoping for tables with a `workspaceId` column. Every query on
+ * such a table filters by the workspace resolved from `requireWorkspace()`.
+ * Organization, member and invitation rows go through the Better-Auth API,
+ * which scopes them to the caller's session.
+ */
+
+import { eq, and, type SQL } from "drizzle-orm";
+import type { PgColumn } from "drizzle-orm/pg-core";
+
+/**
+ * Creates a workspace-scoped WHERE condition for any table with a workspaceId column.
+ * Use it in every custom Drizzle query to enforce workspace isolation.
+ *
+ * @param workspaceIdColumn - The workspaceId column from the table schema
+ * @param workspaceId - The active workspace ID from requireWorkspace()
+ * @returns SQL condition: workspaceId = ?
+ *
+ * @example
+ * ```typescript
+ * const { workspace } = await requireWorkspace();
+ * const conversations = await db
+ *   .select()
+ *   .from(conversationsTable)
+ *   .where(workspaceEq(conversationsTable.workspaceId, workspace.id));
+ * ```
+ */
+export function workspaceEq(
+  workspaceIdColumn: PgColumn,
+  workspaceId: string
+): SQL {
+  return eq(workspaceIdColumn, workspaceId);
+}
+
+/**
+ * Combines a workspace scope condition with additional WHERE conditions.
+ *
+ * @param workspaceIdColumn - The workspaceId column from the table schema
+ * @param workspaceId - The active workspace ID from requireWorkspace()
+ * @param additionalConditions - Extra WHERE conditions to AND together
+ * @returns Combined SQL condition: workspaceId = ? AND ...
+ *
+ * @example
+ * ```typescript
+ * const { workspace } = await requireWorkspace();
+ * const activeConversations = await db
+ *   .select()
+ *   .from(conversationsTable)
+ *   .where(
+ *     withWorkspaceFilter(
+ *       conversationsTable.workspaceId,
+ *       workspace.id,
+ *       eq(conversationsTable.status, "active")
+ *     )
+ *   );
+ * ```
+ */
+export function withWorkspaceFilter(
+  workspaceIdColumn: PgColumn,
+  workspaceId: string,
+  ...additionalConditions: SQL[]
+): SQL {
+  return and(eq(workspaceIdColumn, workspaceId), ...additionalConditions)!;
+}