fix: update README adapter example, add ROADMAP note and changeset

- README: Update ObjectQL adapter example to show correct factory-based
  DBAdapterInstance pattern instead of raw adapter object
- ROADMAP: Add v3.x migration note documenting the bug fix
- Changeset: Add patch changeset for @objectstack/plugin-auth

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

.changeset/fix-auth-error-handling.md

@@ -0,0 +1,9 @@
+---
+"@objectstack/plugin-auth": patch
+---
+
+fix: AuthPlugin error handling & database adapter config
+
+- `AuthManager.handleRequest()` now inspects `response.status >= 500` and logs the error body via `console.error`, since better-auth catches internal errors and returns 500 Responses without throwing.
+- `AuthPlugin.registerAuthRoutes()` also logs 500+ responses via `ctx.logger.error` for structured plugin logging.
+- `createDatabaseConfig()` now wraps the ObjectQL adapter as a `DBAdapterInstance` factory function so better-auth's `getBaseAdapter()` correctly recognises it (via `typeof database === "function"` check) instead of falling through to the Kysely adapter path.

ROADMAP.md

@@ -329,6 +329,7 @@ business/custom objects, aligning with industry best practices (e.g., ServiceNow
 **Migration (v3.x → v4.0):**
 - v3.x: The `SystemObjectName` constants now emit `sys_`-prefixed names. Implementations using `StorageNameMapping.resolveTableName()` can set `tableName` to preserve legacy physical table names during the transition.
 - v3.x: The `@objectstack/plugin-auth` ObjectQL adapter now includes `AUTH_MODEL_TO_PROTOCOL` mapping to translate better-auth's hardcoded model names (`user`, `session`, `account`, `verification`) to protocol names (`sys_user`, `sys_session`, `sys_account`, `sys_verification`). Custom adapters must adopt the same mapping.
+- v3.x: **Bug fix** — `AuthManager.createDatabaseConfig()` now wraps the ObjectQL adapter as a `DBAdapterInstance` factory function (`(options) => DBAdapter`). Previously the raw adapter object was passed, which fell through to the Kysely adapter path and failed silently. `AuthManager.handleRequest()` and `AuthPlugin.registerAuthRoutes()` now inspect `response.status >= 500` and log the error body, since better-auth catches internal errors and returns 500 Responses without throwing.
 - v4.0: Legacy un-prefixed aliases will be fully removed.
 
 ---

packages/plugins/plugin-auth/README.md

@@ -232,13 +232,22 @@ const adapter = createObjectQLAdapter(dataEngine);
 // Mapping: { user: 'sys_user', session: 'sys_session', account: 'sys_account', verification: 'sys_verification' }
 console.log(AUTH_MODEL_TO_PROTOCOL);
 
-// Better-auth uses this adapter for all database operations
+// better-auth requires a DBAdapterInstance (factory function), not a raw adapter object.
+// Passing a plain object falls through to the Kysely adapter path and fails silently.
+// Wrap the adapter in a factory function:
 const auth = betterAuth({
-  database: adapter,
+  database: (options) => ({
+    id: 'objectql',
+    ...adapter,
+    transaction: async (cb) => cb(adapter),
+  }),
   // ... other config
 });
 ```
 
+> **Note:** `AuthManager` handles this wrapping automatically when you provide a `dataEngine`.
+> You only need the factory pattern above when using `createObjectQLAdapter()` directly.
+
 ## Development
 
 ```bash