@node-llm/orm 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.11.0] - 2026-02-07 (@node-llm/core)
+
+### Features
+
+- **Agent Class**: Declarative DSL for defining agents with static properties (model, instructions, tools, temperature, thinking, schema).
+- **ToolHalt Mechanism**: Early termination of agentic loops via `this.halt(result)` in Tool.execute().
+- **defineAgent()**: Inline agent definition without creating a class.
+- **Agent Inheritance**: Child agents inherit parent static properties.
+- **Instance Overrides**: Override static properties at instantiation (temperature, maxTokens, etc.).
+
+### Documentation
+
+- Comprehensive Agent documentation with examples for RAG, model routing, and multi-agent patterns.
+- Added doc tests for Agent, Tool, and ToolHalt patterns.
+
+## [0.5.0] - 2026-02-07 (@node-llm/orm)
+
+### Features
+
+- **AgentSession**: Persistent agent conversations following "Code Wins" principle.
+  - `createAgentSession()`: Create new session with metadata.
+  - `loadAgentSession()`: Resume session by ID with class validation.
+  - Agent class defines behavior (model, tools, instructions), database provides history.
+- **Idempotent Migrations**: Safe migration files for LlmAgentSession table.
+- **Custom Table Names**: Support for custom table name mapping.
+
+## [0.5.0] - 2026-02-07 (@node-llm/testing)
+
+### Features
+
+- **Agent Testing Support**:
+  - `mocker.callsTools()`: Mock responses that trigger multiple tool calls.
+  - `mocker.sequence()`: Return different responses for multi-turn agent conversations.
+  - `mocker.times(n)`: Limit mock matches with fallthrough behavior.
+- **Improved Matching**: First-match semantics enable `times()` fallthrough patterns.
+
 ## [1.10.0] - 2026-02-01 (@node-llm/core)
 
 ### Features
@@ -109,7 +145,7 @@ All notable changes to this project will be documented in this file.
   - Shifted from `db push` to professional **Prisma Migrate** workflow for safe, versioned schema updates.
   - Added repository-wide `prisma/migrations` folder for reproducible deployments.
   - New built-in scripts: `npm run db:migrate`, `npm run db:deploy`, and `npm run db:status`.
-  - Comprehensive [Database Migration Guide](https://node-llm.eshaiju.com/orm/migrations) for application scaling.
+  - Comprehensive [Database Migration Guide](https://nodellm.dev/orm/migrations) for application scaling.
 
 ## [1.6.2] - 2026-01-21 (@node-llm/core)
 
@@ -211,7 +247,7 @@ All notable changes to this project will be documented in this file.
   - `onToolCallStart`: Triggered when a tool call begins
   - `onToolCallEnd`: Triggered when a tool call completes successfully
   - `onToolCallError`: Triggered when a tool call fails
-- **Security Documentation**: New comprehensive [Security & Compliance](https://node-llm.eshaiju.com/advanced/security.html) guide covering:
+- **Security Documentation**: New comprehensive [Security & Compliance](https://nodellm.dev/advanced/security.html) guide covering:
   - Smart Context Isolation
   - Content Policy Hooks
   - Tool Execution Policies

package/README.md

@@ -7,7 +7,7 @@
 
 > Database persistence layer for NodeLLM. Automatically tracks chats, messages, tool calls, and API requests.
 
-**[Read the Full Documentation](https://node-llm.eshaiju.com/orm/prisma)** | **[View Example App](https://github.com/node-llm/node-llm/tree/main/examples/applications/hr-chatbot-rag)**
+**[Read the Full Documentation](https://nodellm.dev/orm/prisma)** | **[View Example App](https://github.com/node-llm/node-llm/tree/main/examples/applications/hr-chatbot-rag)**
 
 ## Features
 
@@ -123,14 +123,15 @@ console.log(messages); // [{ role: 'user', content: '...' }, { role: 'assistant'
 
 ## Architecture
 
-The ORM tracks four core entities:
+The ORM tracks five core entities:
 
-| Model           | Purpose              | Example                                    |
-| --------------- | -------------------- | ------------------------------------------ |
-| **LlmChat**     | Session container    | Holds model, provider, system instructions |
-| **LlmMessage**  | Conversation history | User queries and assistant responses       |
-| **LlmToolCall** | Tool executions      | Function calls made by the assistant       |
-| **LlmRequest**  | API metrics          | Token usage, latency, cost per API call    |
+| Model               | Purpose              | Example                                    |
+| ------------------- | -------------------- | ------------------------------------------ |
+| **LlmAgentSession** | Agent persistence    | Links Agent class to Chat (v0.5.0+)        |
+| **LlmChat**         | Session container    | Holds model, provider, system instructions |
+| **LlmMessage**      | Conversation history | User queries and assistant responses       |
+| **LlmToolCall**     | Tool executions      | Function calls made by the assistant       |
+| **LlmRequest**      | API metrics          | Token usage, latency, cost per API call    |
 
 ### Data Flow
 
@@ -152,6 +153,91 @@ Chat.ask()
 Return Response
 ```
 
+## Agent Sessions (v0.5.0+)
+
+For **stateful agents** with persistence, use `AgentSession`. This follows the "Code Wins" principle:
+
+- **Model, Tools, Instructions** → from Agent class (code)
+- **Message History** → from database
+
+### Define an Agent (in @node-llm/core)
+
+```typescript
+import { Agent, Tool, z } from "@node-llm/core";
+
+class LookupOrderTool extends Tool {
+  static definition = {
+    name: "lookup_order",
+    description: "Look up order status",
+    parameters: z.object({ orderId: z.string() })
+  };
+  async execute({ orderId }) {
+    return { status: "shipped", eta: "Tomorrow" };
+  }
+}
+
+class SupportAgent extends Agent {
+  static model = "gpt-4.1";
+  static instructions = "You are a helpful support agent.";
+  static tools = [LookupOrderTool];
+}
+```
+
+### Create & Resume Sessions
+
+```typescript
+import { createAgentSession, loadAgentSession } from "@node-llm/orm/prisma";
+
+// Create a new persistent session
+const session = await createAgentSession(prisma, llm, SupportAgent, {
+  metadata: { userId: "user_123", ticketId: "TKT-456" }
+});
+
+await session.ask("Where is my order #789?");
+console.log(session.id); // "sess_abc123" - save this!
+
+// Resume later (even after code upgrades)
+const session = await loadAgentSession(prisma, llm, SupportAgent, "sess_abc123");
+await session.ask("Can you cancel it?");
+```
+
+### Code Wins Principle
+
+When you deploy a code change (new model, updated tools), resumed sessions use the **new configuration**:
+
+| Aspect       | Source      | Why                             |
+| ------------ | ----------- | ------------------------------- |
+| Model        | Agent class | Immediate upgrades              |
+| Tools        | Agent class | Only code can execute functions |
+| Instructions | Agent class | Deploy prompt fixes immediately |
+| History      | Database    | Sacred, never modified          |
+
+### Schema Addition
+
+Add `LlmAgentSession` to your Prisma schema:
+
+```prisma
+model LlmAgentSession {
+  id         String   @id @default(uuid())
+  agentClass String   // For validation (e.g., 'SupportAgent')
+  chatId     String   @unique
+  metadata   Json?    // Session context (userId, ticketId)
+  createdAt  DateTime @default(now())
+  updatedAt  DateTime @updatedAt
+
+  chat       LlmChat  @relation(fields: [chatId], references: [id], onDelete: Cascade)
+
+  @@index([agentClass])
+  @@index([createdAt])
+}
+
+// Add relation to LlmChat
+model LlmChat {
+  // ... existing fields
+  agentSession LlmAgentSession?
+}
+```
+
 ## Advanced Usage
 
 ### Streaming Responses

package/bin/cli.js

@@ -63,21 +63,55 @@ function sync() {
     "thoughtSignature"
   ];
 
+  // Check for AgentSession model (v0.5.0+)
+  const hasAgentSession =
+    userSchema.includes("LlmAgentSession") || userSchema.includes("AgentSession");
+
   const missingFields = requiredFields.filter((field) => !userSchema.includes(field));
 
-  if (missingFields.length === 0) {
-    console.log("✓ Schema is already up to date with @node-llm/orm v0.2.0 features.");
+  if (missingFields.length === 0 && hasAgentSession) {
+    console.log("✓ Schema is already up to date with @node-llm/orm v0.5.0 features.");
     return;
   }
 
-  console.log("🛠  Syncing missing fields for Extended Thinking support...");
-  console.log(`\nDetected missing fields: ${missingFields.join(", ")}`);
+  if (missingFields.length > 0) {
+    console.log("🛠  Syncing missing fields for Extended Thinking support...");
+    console.log(`\nDetected missing fields: ${missingFields.join(", ")}`);
+  }
+
+  if (!hasAgentSession) {
+    console.log("\n🤖 Missing AgentSession support (v0.5.0+)");
+    console.log(
+      "   AgentSession enables persistent agent conversations with the 'Code Wins' pattern."
+    );
+    console.log("\n   To add AgentSession, copy the migration from:");
+    console.log("   node_modules/@node-llm/orm/migrations/add_agent_session.sql");
+    console.log("\n   Or add this to your schema.prisma:");
+    console.log(`
+model LlmAgentSession {
+  id         String   @id @default(uuid())
+  agentClass String
+  chatId     String   @unique
+  metadata   Json?
+  createdAt  DateTime @default(now())
+  updatedAt  DateTime @updatedAt
+
+  chat       LlmChat  @relation(fields: [chatId], references: [id], onDelete: Cascade)
+
+  @@index([agentClass])
+  @@index([createdAt])
+}
+
+// Also add to LlmChat:
+// agentSession LlmAgentSession?
+`);
+  }
 
   console.log("\nTo update your schema safely, follow the Reference Schema at:");
   console.log("https://github.com/node-llm/node-llm/blob/main/packages/orm/schema.prisma");
 
   console.log("\nOr run this to generate a versioned migration:");
-  console.log("  npx prisma migrate dev --name add_reasoning_support");
+  console.log("  npx prisma migrate dev --name add_agent_session");
 }
 
 function main() {
@@ -103,7 +137,7 @@ function main() {
       console.log("  npx @node-llm/orm sync     # Check for missing ORM fields");
       console.log("  npx @node-llm/orm migrate  # Rails-style migration helper");
       console.log("\nFor enterprise patterns, see:");
-      console.log("  https://node-llm.eshaiju.com/orm/migrations");
+      console.log("  https://nodellm.dev/orm/migrations");
   }
 }
 

package/dist/adapters/prisma/AgentSession.d.ts

@@ -0,0 +1,140 @@
+import { ChatOptions, AskOptions, NodeLLMCore, Agent, AgentConfig, Message, ChatChunk, Usage } from "@node-llm/core";
+/**
+ * Record structure for the LLM Agent Session table.
+ */
+export interface AgentSessionRecord {
+    id: string;
+    agentClass: string;
+    chatId: string;
+    metadata?: Record<string, unknown> | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Record structure for the LLM Message table.
+ */
+export interface MessageRecord {
+    id: string;
+    chatId: string;
+    role: string;
+    content: string | null;
+    contentRaw?: string | null;
+    thinkingText?: string | null;
+    thinkingSignature?: string | null;
+    thinkingTokens?: number | null;
+    inputTokens?: number | null;
+    outputTokens?: number | null;
+    modelId?: string | null;
+    provider?: string | null;
+    createdAt: Date;
+}
+/**
+ * Table name customization.
+ */
+export interface TableNames {
+    agentSession?: string;
+    chat?: string;
+    message?: string;
+    toolCall?: string;
+    request?: string;
+}
+type AgentClass<T extends Agent = Agent> = (new (overrides?: Partial<AgentConfig & ChatOptions>) => T) & {
+    name: string;
+    model?: string;
+    instructions?: string;
+    tools?: unknown[];
+};
+/**
+ * AgentSession - Wraps an Agent instance with persistence capabilities.
+ *
+ * Follows "Code Wins" sovereignty:
+ * - Model, Tools, Instructions come from the Agent class (code)
+ * - Message history comes from the database
+ *
+ * @example
+ * ```typescript
+ * // Create a new session
+ * const session = await createAgentSession(prisma, llm, SupportAgent, {
+ *   metadata: { userId: "123" }
+ * });
+ *
+ * // Resume a session
+ * const session = await loadAgentSession(prisma, llm, SupportAgent, "sess_abc");
+ *
+ * // Agent behavior is always defined in code
+ * const result = await session.ask("Hello");
+ * ```
+ */
+export declare class AgentSession<T extends Agent = Agent> {
+    private prisma;
+    private llm;
+    private AgentClass;
+    private record;
+    private agent;
+    private currentMessageId;
+    private tableNames;
+    private debug;
+    constructor(prisma: any, llm: NodeLLMCore, AgentClass: AgentClass<T>, record: AgentSessionRecord, tableNames?: TableNames, agent?: T, debug?: boolean);
+    private log;
+    /** Agent instance (for direct access if needed) */
+    get instance(): T;
+    /** Session ID for persistence */
+    get id(): string;
+    /** Underlying chat ID */
+    get chatId(): string;
+    /** Session metadata */
+    get metadata(): Record<string, unknown> | null | undefined;
+    /** Agent class name */
+    get agentClass(): string;
+    /** Model ID used by the agent */
+    get modelId(): string;
+    /** Cumulative usage for this session (from agent memory) */
+    get totalUsage(): Usage;
+    /** Current in-memory message history */
+    get history(): readonly Message[];
+    /**
+     * Helper to get a typed Prisma model by its dynamic name.
+     */
+    private getModel;
+    /**
+     * Send a message and persist the conversation.
+     */
+    ask(input: string, options?: AskOptions): Promise<MessageRecord>;
+    /**
+     * Stream a response and persist the conversation.
+     */
+    askStream(input: string, options?: AskOptions): AsyncGenerator<ChatChunk, MessageRecord, undefined>;
+    /**
+     * Returns the current full message history for this session.
+     */
+    messages(): Promise<MessageRecord[]>;
+    /**
+     * Delete the entire session and its history.
+     */
+    delete(): Promise<void>;
+}
+/**
+ * Options for creating a new agent session.
+ */
+export interface CreateAgentSessionOptions {
+    metadata?: Record<string, unknown>;
+    tableNames?: TableNames;
+    debug?: boolean;
+}
+/**
+ * Creates a new agent session and its persistent chat record.
+ */
+export declare function createAgentSession<T extends Agent>(prisma: any, llm: NodeLLMCore, AgentClass: AgentClass<T>, options?: CreateAgentSessionOptions): Promise<AgentSession<T>>;
+/**
+ * Options for loading an existing agent session.
+ */
+export interface LoadAgentSessionOptions {
+    tableNames?: TableNames;
+    debug?: boolean;
+}
+/**
+ * Loads an existing agent session and re-instantiates the agent with history.
+ */
+export declare function loadAgentSession<T extends Agent>(prisma: any, llm: NodeLLMCore, AgentClass: AgentClass<T>, sessionId: string, options?: LoadAgentSessionOptions): Promise<AgentSession<T> | null>;
+export {};
+//# sourceMappingURL=AgentSession.d.ts.map

package/dist/adapters/prisma/AgentSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentSession.d.ts","sourceRoot":"","sources":["../../../src/adapters/prisma/AgentSession.ts"],"names":[],"mappings":"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"}

package/dist/adapters/prisma/AgentSession.js

@@ -0,0 +1,284 @@
+/**
+ * AgentSession - Wraps an Agent instance with persistence capabilities.
+ *
+ * Follows "Code Wins" sovereignty:
+ * - Model, Tools, Instructions come from the Agent class (code)
+ * - Message history comes from the database
+ *
+ * @example
+ * ```typescript
+ * // Create a new session
+ * const session = await createAgentSession(prisma, llm, SupportAgent, {
+ *   metadata: { userId: "123" }
+ * });
+ *
+ * // Resume a session
+ * const session = await loadAgentSession(prisma, llm, SupportAgent, "sess_abc");
+ *
+ * // Agent behavior is always defined in code
+ * const result = await session.ask("Hello");
+ * ```
+ */
+export class AgentSession {
+    prisma;
+    llm;
+    AgentClass;
+    record;
+    agent;
+    currentMessageId = null;
+    tableNames;
+    debug;
+    constructor(prisma, llm, AgentClass, record, tableNames, agent = new AgentClass({
+        llm
+    }), debug = false) {
+        this.prisma = prisma;
+        this.llm = llm;
+        this.AgentClass = AgentClass;
+        this.record = record;
+        this.agent = agent;
+        this.debug = debug;
+        this.tableNames = {
+            agentSession: tableNames?.agentSession || "llmAgentSession",
+            chat: tableNames?.chat || "llmChat",
+            message: tableNames?.message || "llmMessage",
+            toolCall: tableNames?.toolCall || "llmToolCall",
+            request: tableNames?.request || "llmRequest"
+        };
+    }
+    log(...args) {
+        if (this.debug) {
+            console.log(`[@node-llm/orm]`, ...args);
+        }
+    }
+    /** Agent instance (for direct access if needed) */
+    get instance() {
+        return this.agent;
+    }
+    /** Session ID for persistence */
+    get id() {
+        return this.record.id;
+    }
+    /** Underlying chat ID */
+    get chatId() {
+        return this.record.chatId;
+    }
+    /** Session metadata */
+    get metadata() {
+        return this.record.metadata;
+    }
+    /** Agent class name */
+    get agentClass() {
+        return this.record.agentClass;
+    }
+    /** Model ID used by the agent */
+    get modelId() {
+        return this.agent.modelId;
+    }
+    /** Cumulative usage for this session (from agent memory) */
+    get totalUsage() {
+        return this.agent.totalUsage;
+    }
+    /** Current in-memory message history */
+    get history() {
+        return this.agent.history;
+    }
+    /**
+     * Helper to get a typed Prisma model by its dynamic name.
+     */
+    getModel(name) {
+        return getTable(this.prisma, name);
+    }
+    /**
+     * Send a message and persist the conversation.
+     */
+    async ask(input, options = {}) {
+        const model = this.getModel(this.tableNames.message);
+        // Persist user message
+        await model.create({
+            data: { chatId: this.chatId, role: "user", content: input }
+        });
+        // Create placeholder for assistant message
+        const assistantMessage = await model.create({
+            data: { chatId: this.chatId, role: "assistant", content: null }
+        });
+        this.currentMessageId = assistantMessage.id;
+        try {
+            // Get response from agent (uses code-defined config + injected history)
+            const response = await this.agent.ask(input, options);
+            // Update assistant message with response
+            return await model.update({
+                where: { id: assistantMessage.id },
+                data: {
+                    content: response.content,
+                    contentRaw: JSON.stringify(response.meta),
+                    inputTokens: response.usage?.input_tokens || 0,
+                    outputTokens: response.usage?.output_tokens || 0,
+                    thinkingText: response.thinking?.text || null,
+                    thinkingSignature: response.thinking?.signature || null,
+                    thinkingTokens: response.thinking?.tokens || null,
+                    modelId: response.model || null,
+                    provider: response.provider || null
+                }
+            });
+        }
+        catch (error) {
+            // Clean up placeholder on error
+            await model.delete({ where: { id: assistantMessage.id } });
+            throw error;
+        }
+    }
+    /**
+     * Stream a response and persist the conversation.
+     */
+    async *askStream(input, options = {}) {
+        const model = this.getModel(this.tableNames.message);
+        // Persist user message
+        await model.create({
+            data: { chatId: this.chatId, role: "user", content: input }
+        });
+        // Create placeholder for assistant message
+        const assistantMessage = await model.create({
+            data: { chatId: this.chatId, role: "assistant", content: null }
+        });
+        this.currentMessageId = assistantMessage.id;
+        try {
+            const stream = this.agent.stream(input, options);
+            let fullContent = "";
+            let lastChunk = null;
+            for await (const chunk of stream) {
+                fullContent += chunk.content;
+                lastChunk = chunk;
+                yield chunk;
+            }
+            // Final update with accumulated result
+            return await model.update({
+                where: { id: assistantMessage.id },
+                data: {
+                    content: fullContent,
+                    inputTokens: lastChunk?.usage?.input_tokens || 0,
+                    outputTokens: lastChunk?.usage?.output_tokens || 0,
+                    thinkingText: lastChunk?.thinking?.text || null,
+                    thinkingSignature: lastChunk?.thinking?.signature || null,
+                    thinkingTokens: lastChunk?.thinking?.tokens || null,
+                    modelId: lastChunk?.metadata?.model || null,
+                    provider: lastChunk?.metadata?.provider || null
+                }
+            });
+        }
+        catch (error) {
+            await model.delete({ where: { id: assistantMessage.id } });
+            throw error;
+        }
+    }
+    /**
+     * Returns the current full message history for this session.
+     */
+    async messages() {
+        const model = this.getModel(this.tableNames.message);
+        return await model.findMany({
+            where: { chatId: this.chatId },
+            orderBy: { createdAt: "asc" }
+        });
+    }
+    /**
+     * Delete the entire session and its history.
+     */
+    async delete() {
+        const chatTable = this.getModel(this.tableNames.chat);
+        await chatTable.delete({ where: { id: this.chatId } });
+        // AgentSession record is deleted via Cascade from LlmChat
+    }
+}
+/**
+ * Creates a new agent session and its persistent chat record.
+ */
+export async function createAgentSession(prisma, llm, AgentClass, options = {}) {
+    const tableNames = {
+        agentSession: options.tableNames?.agentSession || "llmAgentSession",
+        chat: options.tableNames?.chat || "llmChat",
+        message: options.tableNames?.message || "llmMessage"
+    };
+    if (options.debug) {
+        console.log(`[@node-llm/orm] createAgentSession: agentClass=${AgentClass.name}`);
+    }
+    // 1. Create underlying LlmChat record
+    const chatTable = getTable(prisma, tableNames.chat);
+    const chatRecord = (await chatTable.create({
+        data: {
+            model: AgentClass.model || null,
+            provider: null,
+            instructions: AgentClass.instructions || null,
+            metadata: null // Runtime metadata goes in Chat, session context in AgentSession
+        }
+    }));
+    // 2. Create AgentSession record
+    const sessionTable = getTable(prisma, tableNames.agentSession);
+    const sessionRecord = (await sessionTable.create({
+        data: {
+            agentClass: AgentClass.name,
+            chatId: chatRecord.id,
+            metadata: options.metadata || null
+        }
+    }));
+    return new AgentSession(prisma, llm, AgentClass, sessionRecord, options.tableNames, undefined, options.debug);
+}
+/**
+ * Loads an existing agent session and re-instantiates the agent with history.
+ */
+export async function loadAgentSession(prisma, llm, AgentClass, sessionId, options = {}) {
+    const tableNames = {
+        agentSession: options.tableNames?.agentSession || "llmAgentSession",
+        chat: options.tableNames?.chat || "llmChat",
+        message: options.tableNames?.message || "llmMessage"
+    };
+    if (options.debug) {
+        console.log(`[@node-llm/orm] loadAgentSession: id=${sessionId}`);
+    }
+    // 1. Find session record
+    const sessionTable = getTable(prisma, tableNames.agentSession);
+    const sessionRecord = (await sessionTable.findUnique({
+        where: { id: sessionId }
+    }));
+    if (!sessionRecord) {
+        return null;
+    }
+    // 1.5. Validate Agent Class (Code Wins Sovereignty)
+    if (sessionRecord.agentClass !== AgentClass.name) {
+        throw new Error(`Agent class mismatch: Session "${sessionId}" was created for "${sessionRecord.agentClass}", but is being loaded with "${AgentClass.name}".`);
+    }
+    // 2. Load message history
+    const messageTable = getTable(prisma, tableNames.message);
+    const messages = (await messageTable.findMany({
+        where: { chatId: sessionRecord.chatId },
+        orderBy: { createdAt: "asc" }
+    }));
+    // 3. Convert DB messages to NodeLLM Message format
+    const history = messages.map((m) => ({
+        role: m.role,
+        content: m.content || ""
+    }));
+    // 4. Instantiate agent with injected history and LLM
+    // "Code Wins" - model, tools, instructions come from AgentClass
+    const agent = new AgentClass({
+        llm,
+        messages: history
+    });
+    return new AgentSession(prisma, llm, AgentClass, sessionRecord, options.tableNames, agent, options.debug);
+}
+/**
+ * Dynamic helper to access Prisma models by name.
+ * Handles both case-sensitive and case-insensitive lookups for flexibility.
+ */
+function getTable(prisma, tableName) {
+    const p = prisma;
+    // 1. Direct match
+    const table = p[tableName];
+    if (table)
+        return table;
+    // 2. Case-insensitive match
+    const keys = Object.keys(prisma).filter((k) => !k.startsWith("$") && !k.startsWith("_"));
+    const match = keys.find((k) => k.toLowerCase() === tableName.toLowerCase());
+    if (match && p[match])
+        return p[match];
+    throw new Error(`[@node-llm/orm] Prisma table "${tableName}" not found. Available tables: ${keys.join(", ")}`);
+}