@venizia/ignis-docs 0.0.8-3 → 0.1.0

package/{wiki/references/base/middleware.md → content/references/base/middlewares.md}

@@ -1,19 +1,19 @@
 ---
-title: Middleware Reference
+title: Middlewares Reference
 description: Technical reference for built-in middlewares in IGNIS
 difficulty: intermediate
-lastUpdated: 2026-03-15
+lastUpdated: 2026-06-14
 ---
 
-# Middleware Reference
+# Middlewares Reference
 
-IGNIS provides built-in middleware functions and a provider-based middleware class for handling common HTTP concerns: error handling, request logging, 404 responses, and favicon serving. These are registered automatically by `BaseApplication` during startup.
+IGNIS provides built-in middleware functions and a provider-based middleware class for handling common HTTP concerns: error handling, request logging, 404 responses, and favicon serving. These are registered automatically by `BaseApplication` during startup - you do not import or wire them manually.
 
 **Files:**
-- `packages/core/src/base/middlewares/app-error.middleware.ts`
-- `packages/core/src/base/middlewares/not-found.middleware.ts`
-- `packages/core/src/base/middlewares/request-spy.middleware.ts`
-- `packages/core/src/base/middlewares/emoji-favicon.middleware.ts`
+- `packages/core/src/base/middlewares/app-error/app-error.middleware.ts`
+- `packages/core/src/base/middlewares/not-found/not-found.middleware.ts`
+- `packages/core/src/base/middlewares/request-spy/request-spy.middleware.ts`
+- `packages/core/src/base/middlewares/emoji-favicon/emoji-favicon.middleware.ts`
 
 ## Prerequisites
 
@@ -64,6 +64,8 @@ After `registerDefaultMiddlewares()`, the application calls user-defined `static
 
 Global error handler registered via `server.onError()`. Handles ZodError validation errors, PostgreSQL constraint violations, and generic errors.
 
+**Not exported from `@venizia/ignis`** - registered automatically by `BaseApplication`.
+
 ### Signature
 
 ```typescript
@@ -82,11 +84,14 @@ function appErrorHandler(opts: {
 
 #### 1. ZodError (Validation Errors)
 
-When `error.name === 'ZodError'`, returns HTTP `422 Unprocessable Entity`:
+When `error.name === 'ZodError'`, returns HTTP `422 Unprocessable Entity`.
+
+Top-level `message`/`messageCode` come from the first failing issue - its `params.code` if the schema set one, otherwise its raw Zod code. The full per-field list stays under `details.cause`.
 
 ```json
 {
-  "message": "ValidationError",
+  "message": "Invalid email address",
+  "messageCode": "user.email.invalid",
   "statusCode": 422,
   "requestId": "abc-123",
   "details": {
@@ -96,7 +101,7 @@ When `error.name === 'ZodError'`, returns HTTP `422 Unprocessable Entity`:
     "cause": [
       {
         "path": "email",
-        "message": "Invalid email",
+        "message": "Invalid email address",
         "code": "invalid_string",
         "expected": "string",
         "received": "undefined"
@@ -106,22 +111,36 @@ When `error.name === 'ZodError'`, returns HTTP `422 Unprocessable Entity`:
 }
 ```
 
+To emit a stable, domain-specific `messageCode`, attach `params.code` to a custom check:
+
+```typescript
+z.string().refine(isEmail, {
+  message: 'Invalid email address',
+  params: { code: 'user.email.invalid' }
+});
+// produces "messageCode": "user.email.invalid"
+```
+
+> [!NOTE]
+> When `error.message` cannot be parsed as the expected Zod issue array (a malformed or unrecognized `ZodError`), no issue-derived `messageCode` exists - the response still carries one, resolved to `MessageCode.DEFAULT` (`"core.system_error"`) via `MessageCode.resolve(undefined)`. No error response from this middleware is ever missing `messageCode`.
+
 #### 2. PostgreSQL Constraint Violations
 
-Database errors with recognized SQLSTATE codes return HTTP `400 Bad Request` instead of 500:
+Database errors in SQLSTATE class `22` (data exception), `23` (integrity constraint), and `44` (WITH CHECK OPTION violation) are detected by class and returned as HTTP `400 Bad Request`. A known code uses its specific message; any other in-class code uses `"Invalid database request"` as a fallback.
+
+| Class | Codes with a specific message |
+|-------|-------------------------------|
+| `23` Integrity | `23505` unique, `23503` foreign key, `23502` not null, `23514` check, `23P01` exclusion, `23000` integrity, `23001` restrict |
+| `22` Data exception | `22001` string too long, `22003` numeric range, `22004` null not allowed, `22007` datetime format, `22008` datetime overflow, `22009` tz displacement, `22011` substring, `22012` division by zero, `22023` invalid parameter, `22025` invalid escape, `22026` length mismatch, `22030` duplicate JSON key, `22032` invalid JSON, `22P01` floating-point, `22P02` invalid text, `22P03` invalid binary, `22P05` untranslatable char |
+| `44` View check | `44000` WITH CHECK OPTION violation |
 
-| SQLSTATE Code | Error Type |
-|--------------|------------|
-| `23505` | Unique constraint violation |
-| `23503` | Foreign key constraint violation |
-| `23502` | Not null constraint violation |
-| `23514` | Check constraint violation |
-| `23P01` | Exclusion constraint violation |
-| `22P02` | Invalid text representation |
-| `22003` | Numeric value out of range |
-| `22001` | String data too long |
+:::tip Transient conflicts return 409, not 400/500
+Class `40` (`40001` serialization failure, `40P01` deadlock) is transient/retryable and returns **409 Conflict** with `messageCode: "database.conflict"` and a safe "please retry" message - the client can safely retry the same request. Programming/infra classes (`42` syntax, `53` resources, `0A`, `25`, `28`) remain 500.
+:::
 
-The error response includes detail, table, and constraint information when available from the database error's `cause` property.
+:::warning Production sanitizes database internals
+In **production** the message is the base message only - `Detail:`/`Table:`/`Constraint:` are stripped (they echo row values and schema names), and `details.stack`/`details.cause` are omitted. Codes outside class 22/23/44 (e.g. `42703` undefined column) and connection failures return a generic `"Internal Server Error"`, so SQL, schema names, and connection host/port never leak.
+:::
 
 #### 3. Generic Errors
 
@@ -132,6 +151,7 @@ All other errors use the `statusCode` property from the error if present, otherw
 ```json
 {
   "message": "Error message",
+  "messageCode": "core.system_error",
   "statusCode": 500,
   "requestId": "abc-123",
   "details": {
@@ -149,6 +169,7 @@ When `rootKey` is provided (e.g., `rootKey: 'error'`), the response is wrapped:
 {
   "error": {
     "message": "Error message",
+    "messageCode": "core.system_error",
     "statusCode": 500,
     "requestId": "abc-123",
     "details": { ... }
@@ -158,11 +179,38 @@ When `rootKey` is provided (e.g., `rootKey: 'error'`), the response is wrapped:
 
 **Production behavior:** `stack` and `cause` fields are omitted when `NODE_ENV` is `'production'`.
 
+### Custom Errors
+
+Throw any error with a `statusCode` property and the handler picks it up:
+
+```typescript
+class NotFoundError extends Error {
+  statusCode = 404;
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'NotFoundError';
+  }
+}
+
+// In a controller
+@get({ configs: GetUserConfig })
+async getUser(c: TRouteContext) {
+  const user = await this.userRepository.findById(id);
+  if (!user) {
+    throw new NotFoundError(`User ${id} not found`);
+  }
+  return c.json(user, HTTP.ResultCodes.RS_2.Ok);
+}
+```
+
 
 ## notFoundHandler
 
 Returns a JSON 404 response when no route matches. Registered via `server.notFound()`.
 
+**Not exported from `@venizia/ignis`** - registered automatically by `BaseApplication`.
+
 ### Signature
 
 ```typescript
@@ -194,6 +242,8 @@ The handler logs the 404 at error level with the request ID, path, and full URL.
 
 A provider-based middleware class that logs incoming request details and outgoing response timing. It extends `BaseHelper` and implements `IProvider<MiddlewareHandler>`.
 
+**Not exported from `@venizia/ignis`** - registered automatically via `RequestTrackerComponent` by `BaseApplication`.
+
 ### Class Definition
 
 ```typescript
@@ -256,11 +306,37 @@ Returns `null` if no `Content-Type` header or `Content-Length` is `0`/missing. T
 
 The middleware resolves the client IP from the connection info or falls back to `x-real-ip` / `x-forwarded-for` headers. If neither is available, it throws HTTP 400 `'Malformed Connection Info'`.
 
+### Accessing the Request ID
+
+`RequestSpyMiddleware.REQUEST_ID_KEY` is `'requestId'` - since the middleware class itself is not exported from `@venizia/ignis`, read the context variable by that key:
+
+```typescript
+import { get, jsonResponse, TRouteContext } from '@venizia/ignis';
+import { z } from '@hono/zod-openapi';
+import { HTTP } from '@venizia/ignis-helpers';
+
+const ExampleConfig = {
+  method: HTTP.Methods.GET,
+  path: '/example',
+  responses: jsonResponse({
+    schema: z.object({ requestId: z.string() }),
+  }),
+} as const;
+
+@get({ configs: ExampleConfig })
+async example(c: TRouteContext) {
+  const requestId = c.get('requestId');
+  return c.json({ requestId }, HTTP.ResultCodes.RS_2.Ok);
+}
+```
+
 
 ## emojiFavicon
 
 A simple middleware that serves an emoji as an SVG favicon on `/favicon.ico`.
 
+**Not exported from `@venizia/ignis`** - registered automatically by `BaseApplication`.
+
 ### Signature
 
 ```typescript
@@ -295,7 +371,7 @@ interface IApplicationConfigs {
 
 ## User-Defined Middlewares
 
-The `setupMiddlewares()` abstract method on `AbstractApplication` is called after `initialize()` and before the server starts. Use this hook to register additional Hono middlewares:
+The `setupMiddlewares()` abstract method on `AbstractApplication` is called after `initialize()` and before the server starts. Use this hook to register additional Hono middlewares via `this.getServer()`:
 
 ```typescript
 export class MyApplication extends BaseApplication {
@@ -307,6 +383,9 @@ export class MyApplication extends BaseApplication {
 
     // Body limit
     server.use(bodyLimit({ maxSize: 1024 * 1024 })); // 1MB
+
+    // Route-specific
+    server.use('/api/admin/*', adminAuthMiddleware());
   }
 }
 ```
@@ -336,6 +415,105 @@ interface IBaseMiddlewareOptions {
 ```
 
 
+## Creating Custom Middleware
+
+IGNIS uses Hono's middleware system. Create custom middleware using the `createMiddleware` factory from `hono/factory`.
+
+### Basic Middleware
+
+```typescript
+import { createMiddleware } from 'hono/factory';
+import type { MiddlewareHandler } from 'hono';
+
+export const myMiddleware = (): MiddlewareHandler => {
+  return createMiddleware(async (context, next) => {
+    // Before request handling
+    console.log('Before:', context.req.path);
+
+    await next();
+
+    // After request handling
+    console.log('After:', context.req.path);
+  });
+};
+```
+
+### Middleware with Options
+
+```typescript
+interface MyMiddlewareOptions {
+  enabled: boolean;
+  prefix?: string;
+}
+
+export const myMiddleware = (opts: MyMiddlewareOptions): MiddlewareHandler => {
+  const { enabled, prefix = 'LOG' } = opts;
+
+  return createMiddleware(async (context, next) => {
+    if (enabled) {
+      console.log(`[${prefix}]`, context.req.path);
+    }
+    await next();
+  });
+};
+```
+
+### Provider-Based Middleware
+
+For middleware requiring dependency injection, implement `IProvider<MiddlewareHandler>`:
+
+```typescript
+import { BaseHelper } from '@venizia/ignis-helpers';
+import { IProvider } from '@venizia/ignis-inversion';
+import { createMiddleware } from 'hono/factory';
+import type { MiddlewareHandler } from 'hono';
+
+export class MyMiddleware extends BaseHelper implements IProvider<MiddlewareHandler> {
+  constructor() {
+    super({ scope: MyMiddleware.name });
+  }
+
+  value(): MiddlewareHandler {
+    return createMiddleware(async (context, next) => {
+      this.logger.info('Processing request:', context.req.path);
+      await next();
+    });
+  }
+}
+```
+
+Register it with `.toProvider()` (the same pattern `RequestTrackerComponent` uses for `RequestSpyMiddleware`), then use the resolved handler inside `setupMiddlewares()` - `get()` returns the produced `MiddlewareHandler` because the container calls `value()` for provider bindings:
+
+```typescript
+export class MyApplication extends BaseApplication {
+  preConfigure() {
+    this.bind({ key: 'middlewares.MyMiddleware' })
+      .toProvider(MyMiddleware)
+      .setScope(BindingScopes.SINGLETON);
+  }
+
+  async setupMiddlewares() {
+    const myMiddleware = this.get<MiddlewareHandler>({ key: 'middlewares.MyMiddleware' });
+    this.getServer().use(myMiddleware);
+  }
+}
+```
+
+
+## Performance Considerations
+
+### Request Spy in Production
+
+`RequestSpyMiddleware` logs every request. IGNIS automatically skips body logging in production (`NODE_ENV === 'production'`), but the middleware still runs. For ultra-high-traffic workloads consider sampling strategies or externalizing log aggregation.
+
+### Error Logging Volume
+
+Error handlers log every error. For high error rates, consider:
+- Sampling (log 1 in N errors)
+- Error aggregation services (Sentry, Rollbar)
+- Rate-limited logging
+
+
 ## See Also
 
 - **Related References:**
@@ -345,3 +523,6 @@ interface IBaseMiddlewareOptions {
 
 - **Guides:**
   - [Application Guide](/guides/core-concepts/application/)
+
+- **External Resources:**
+  - [Hono Middleware Documentation](https://hono.dev/docs/guides/middleware)

package/{wiki → content}/references/base/models.md

@@ -6,24 +6,31 @@ difficulty: intermediate
 
 # Deep Dive: Models and Enrichers
 
-Technical reference for model architecture and schema enrichers in Ignis.
+Technical reference for model architecture and schema enrichers in IGNIS.
+
+> [!IMPORTANT] Base vs. Connectors
+> The engine-neutral root `AbstractEntity` (`packages/core/src/base/models/base.ts`) has no Drizzle, no `pgTable`, and no `drizzle-zod` - just a `name`, an abstract `getSchema()`, a `getIdType(): TIdSchemaType` method (default `'string'`), and `toObject()`/`toJSON()`. Everything described below - the Drizzle-backed `BaseEntity`, `drizzle-zod` schema generation, and all schema enrichers - belongs to the **PostgreSQL connector**'s `BasePostgresEntity`, not the neutral base. See [Connectors](./connectors) for the full base-vs-connectors architecture.
 
 **Files:**
-- `packages/core/src/base/models/base.ts`
-- `packages/core/src/base/models/enrichers/*.ts`
+- `packages/core/src/base/models/base.ts` (neutral `AbstractEntity`)
+- `packages/core/src/connectors/postgres/models/base.ts` (PostgreSQL `BasePostgresEntity`)
+- `packages/core/src/connectors/postgres/models/enrichers/*.ts`
 
 ## Quick Reference
 
 | Component | Purpose | Key Features |
 |-----------|---------|--------------|
-| **BaseEntity** | Wraps Drizzle schema | Schema encapsulation, Zod generation, `toObject()`/`toJSON()` |
+| **BasePostgresEntity** (alias: `BaseEntity`) | Wraps Drizzle schema | Schema encapsulation, Zod generation, `toObject()`/`toJSON()` |
 | **Schema Enrichers** | Add common columns to tables | `generateIdColumnDefs()`, `generateTzColumnDefs()`, etc. |
 
-## `BaseEntity` Class
+## `BasePostgresEntity` Class (alias: `BaseEntity`)
+
+PostgreSQL connector's entity class, wrapping a Drizzle ORM schema. Extends the neutral `AbstractEntity`.
 
-Fundamental building block wrapping a Drizzle ORM schema.
+**File:** `packages/core/src/connectors/postgres/models/base.ts`
 
-**File:** `packages/core/src/base/models/base.ts`
+> [!TIP] Naming
+> `BasePostgresEntity` is the canonical, engine-carrying name. `BaseEntity` is a compatibility alias re-exporting the same class from `connectors/postgres/models/index.ts` (`export { BasePostgresEntity as BaseEntity } from './base'`) - both resolve to identical runtime behavior. Code samples on this page use `BaseEntity` since it remains the most common import today.
 
 ### Purpose
 
@@ -68,13 +75,13 @@ The `@model` decorator marks a class as a database entity and configures its beh
 | `settings.hiddenProperties` | `string[]` | Array of property names to exclude from all repository query results |
 | `settings.defaultFilter` | `TFilter` | Filter automatically applied to all repository queries (see [Default Filter](/references/base/filter-system/default-filter)) |
 | `settings.defaultLimit` | `number` | Default row limit applied when a query omits `limit`. Must be a positive integer (validated at decoration time). Falls back to the global `DEFAULT_LIMIT` (10). See [Pagination](/references/base/filter-system/fields-order-pagination#default-limit) |
-| `settings.authorize` | `IModelAuthorizeSettings` | Authorization settings — declares the model's authorization principal (see [Authorization](/extensions/components/authorization/usage#model-based-resource-references)) |
+| `settings.authorize` | `IModelAuthorizeSettings` | Authorization settings - declares the model's authorization principal (see [Authorization](/extensions/components/authorization/usage#model-based-resource-references)) |
 | `settings.authorize.principal` | `string` | The authorization subject name for this model. Auto-populates `AUTHORIZATION_SUBJECT` static property |
 
 #### `@model` Behavior
 
 When the `@model` decorator is applied:
-1. If `settings.defaultLimit` is provided, it is validated to be a positive integer — otherwise the decorator throws at decoration (boot) time
+1. If `settings.defaultLimit` is provided, it is validated to be a positive integer - otherwise the decorator throws at decoration (boot) time
 2. If `settings.authorize.principal` is provided and `AUTHORIZATION_SUBJECT` is not already defined on the class, it auto-populates `AUTHORIZATION_SUBJECT` with the principal value
 3. The model is registered in the `MetadataRegistry` model registry, keyed by table name (resolved as: `metadata.tableName` > `static TABLE_NAME` > class name)
 4. The static `relations` property is stored as a resolver (not immediately resolved) to avoid circular dependency issues between models
@@ -126,11 +133,11 @@ export class User extends BaseEntity<typeof User.schema> {
 
 ```typescript
 // Repository query - password/secret NOT included
-const user = await userRepo.findById({ id: '123' });
+const user = await userRepository.findById({ id: '123' });
 // user = { id: '123', email: 'john@example.com' }
 
 // Direct connector query - ALL fields included
-const connector = userRepo.getConnector();
+const connector = userRepository.getConnector();
 const [fullUser] = await connector
   .select()
   .from(User.schema)
@@ -178,11 +185,11 @@ Use `shouldSkipDefaultFilter: true` to bypass:
 
 ```typescript
 // Normal query - includes default filter
-await postRepo.find({ filter: {} });
+await postRepository.find({ filter: {} });
 // WHERE isDeleted = false LIMIT 100
 
 // Admin query - bypass default filter
-await postRepo.find({
+await postRepository.find({
   filter: {},
   options: { shouldSkipDefaultFilter: true }
 });
@@ -271,7 +278,7 @@ interface IEntity<Schema extends TTableSchemaWithId = TTableSchemaWithId> {
 |--------|-------------|
 | `getSchema({ type })` | Get Zod schema for validation (`'select'`, `'create'`, `'update'`) |
 | `toObject()` | Convert to plain object (shallow spread of `this`) |
-| `toJSON()` | Delegates to `toObject()` — returns a plain object (used by `JSON.stringify`) |
+| `toJSON()` | Delegates to `toObject()` - returns a plain object (used by `JSON.stringify`) |
 
 ### `getSchema` Method
 
@@ -307,12 +314,11 @@ The `schemaFactory` is a static lazy singleton created via `drizzle-zod`'s `crea
 ### Class Definition
 
 ```typescript
-export class BaseEntity<Schema extends TTableSchemaWithId = TTableSchemaWithId>
-  extends BaseHelper
+export class BasePostgresEntity<Schema extends TTableSchemaWithId = TTableSchemaWithId>
+  extends AbstractEntity
   implements IEntity<Schema>
 {
-  // Instance properties
-  name: string;
+  // Instance property (name, toObject(), toJSON() are inherited from AbstractEntity)
   schema: Schema;
 
   // Static properties - override in subclass
@@ -325,23 +331,27 @@ export class BaseEntity<Schema extends TTableSchemaWithId = TTableSchemaWithId>
   // Performance optimization: avoids creating new factory per entity
   private static _schemaFactory?: ReturnType<typeof createSchemaFactory>;
   protected static get schemaFactory(): ReturnType<typeof createSchemaFactory> {
-    return (BaseEntity._schemaFactory ??= createSchemaFactory());
+    return (BasePostgresEntity._schemaFactory ??= createSchemaFactory());
   }
 
   // Constructor supports both patterns
   constructor(opts?: { name?: string; schema?: Schema }) {
-    const ctor = new.target as typeof BaseEntity;
+    const ctor = new.target as typeof BasePostgresEntity;
     // Resolution order: opts.name > static TABLE_NAME > class name
     const name = opts?.name ?? ctor.TABLE_NAME ?? ctor.name;
 
-    super({ scope: name });
+    super({ name });
 
-    this.name = name;
     this.schema = opts?.schema || (ctor.schema as Schema);
   }
 
+  // Maps the pgTable id column's Drizzle dataType to 'number' or 'string'
+  override getIdType(): TIdSchemaType {
+    return getIdType({ entity: this.schema }) === 'number' ? 'number' : 'string';
+  }
+
   getSchema(opts: { type: TSchemaType }) {
-    const factory = BaseEntity.schemaFactory;  // Uses static singleton
+    const factory = BasePostgresEntity.schemaFactory;  // Uses static singleton
     switch (opts.type) {
       case SchemaTypes.CREATE:
         return factory.createInsertSchema(this.schema);
@@ -355,14 +365,6 @@ export class BaseEntity<Schema extends TTableSchemaWithId = TTableSchemaWithId>
         });
     }
   }
-
-  toObject() {
-    return { ...this };
-  }
-
-  toJSON() {
-    return this.toObject();
-  }
 }
 ```
 
@@ -441,11 +443,11 @@ From `@venizia/ignis-helpers`, enables lazy resolution to avoid circular depende
 type TValueOrResolver<T> = T | TResolver<T>;  // T or () => T
 ```
 
-Used for `relations` on `BaseEntity` — store a function that returns the relations array, resolved lazily when `DataSource.buildSchema()` is called.
+Used for `relations` on `BaseEntity` - store a function that returns the relations array, resolved lazily when `DataSource.buildSchema()` is called.
 
 ## Schema Enrichers
 
-Enrichers are helper functions located in `packages/core/src/base/models/enrichers/` that return an object of Drizzle ORM column definitions. They are designed to be spread into a `pgTable` definition to quickly add common, standardized fields to your models.
+Enrichers are helper functions located in `packages/core/src/connectors/postgres/models/enrichers/` that return an object of Drizzle ORM column definitions. They are designed to be spread into a `pgTable` definition to quickly add common, standardized fields to your models.
 
 ### Available Enrichers
 
@@ -456,7 +458,7 @@ Enrichers are helper functions located in `packages/core/src/base/models/enriche
 | **`generateUserAuditColumnDefs`** | `enrichUserAudit` | Adds `createdBy` and `modifiedBy` columns to track user audit information. |
 | **`generatePrincipalColumnDefs`** | `enrichPrincipal` | Adds polymorphic principal columns (`{discriminator}Id` and `{discriminator}Type`). |
 | **`generateDataTypeColumnDefs`** | `enrichDataTypes` | Adds generic data type columns (`dataType`, `nValue`, `tValue`, `bValue`, `jValue`, `boValue`) for flexible data storage. |
-| **`extraUserColumns`** | — | Adds common user fields (`realm`, `status`, `type`, `activatedAt`, `lastLoginAt`, `parentId`). Imported from `@venizia/ignis` (part of auth component). |
+| **`extraUserColumns`** | - | Adds common user fields (`realm`, `status`, `type`, `activatedAt`, `lastLoginAt`, `parentId`). Imported from `@venizia/ignis` (part of auth component). |
 
 Each `generate*` function returns column definition objects for spreading into `pgTable`. The `enrich*` convenience wrappers accept an existing `TColumnDefinitions` object as the first argument and merge the generated columns into it.
 
@@ -488,7 +490,7 @@ export const myTable = pgTable('MyTable', {
 
 Adds a primary key `id` column with support for string UUID, integer, or big integer types with full TypeScript type inference.
 
-**File:** `packages/core/src/base/models/enrichers/id.enricher.ts`
+**File:** `packages/core/src/connectors/postgres/models/enrichers/id.enricher.ts`
 
 #### Signature
 
@@ -688,7 +690,7 @@ const columns = enrichId(
 
 Adds timestamp columns for tracking entity creation, modification, and soft deletion.
 
-**File:** `packages/core/src/base/models/enrichers/tz.enricher.ts`
+**File:** `packages/core/src/connectors/postgres/models/enrichers/tz.enricher.ts`
 
 #### Signature
 
@@ -722,7 +724,7 @@ The `modified` and `deleted` options use a discriminated union pattern:
 | Column | Type | Constraints | Default | Description |
 |--------|------|-------------|---------|-------------|
 | `createdAt` | `timestamp` | `NOT NULL` | `now()` | When the record was created (always included) |
-| `modifiedAt` | `timestamp` | `NOT NULL` | `now()`, auto-updates via `$onUpdate(() => new Date())` | When the record was last modified (optional, enabled by default) |
+| `modifiedAt` | `timestamp` | `NOT NULL` | `now()`, auto-updates via `$onUpdate(() => new Date().toISOString())` | When the record was last modified (optional, enabled by default) |
 | `deletedAt` | `timestamp` | nullable | `null` | When the record was soft-deleted (optional, **disabled by default**) |
 
 #### Usage Examples
@@ -831,8 +833,10 @@ await db.update(myTable)
 The enricher provides **conditional TypeScript type inference** based on the options:
 
 ```typescript
+type TIsoTimestampColumn = ReturnType<typeof isoTimestamp>; // custom ISO 8601 timestamp column
+
 type TTzEnricherResult<Opts extends TTzEnricherOptions | undefined = undefined> = {
-  createdAt: NotNull<HasDefault<PgTimestampBuilderInitial<string>>>;
+  createdAt: NotNull<HasDefault<TIsoTimestampColumn>>;
 } & (/* modifiedAt included unless opts.modified.enable === false */)
   & (/* deletedAt included only when opts.deleted.enable === true */);
 ```
@@ -854,7 +858,7 @@ Merges timestamp columns into an existing column definitions object.
 
 Adds `createdBy` and `modifiedBy` columns to track which user created or modified a record.
 
-**File:** `packages/core/src/base/models/enrichers/user-audit.enricher.ts`
+**File:** `packages/core/src/connectors/postgres/models/enrichers/user-audit.enricher.ts`
 
 #### Signature
 
@@ -888,8 +892,8 @@ type TUserAuditEnricherOptions = {
 
 The enricher uses Hono's `contextStorage` (via `tryGetContext()`) to automatically retrieve the current user ID from the request context at insert/update time:
 
-- **`createdBy`**: Set via `$default()` — only populated on record creation
-- **`modifiedBy`**: Set via both `$default()` and `$onUpdate()` — populated on creation and updated on every modification
+- **`createdBy`**: Set via `$default()` - only populated on record creation
+- **`modifiedBy`**: Set via both `$default()` and `$onUpdate()` - populated on creation and updated on every modification
 
 The user ID is read from the `Authentication.AUDIT_USER_ID` key in the Hono context.
 
@@ -1023,7 +1027,7 @@ Merges user audit columns into an existing column definitions object with proper
 
 Adds polymorphic principal columns for associating a record with different entity types. This is the polymorphic association pattern where a row can belong to different parent types (e.g., a comment can belong to a Post, User, or Product).
 
-**File:** `packages/core/src/base/models/enrichers/principal.enricher.ts`
+**File:** `packages/core/src/connectors/postgres/models/enrichers/principal.enricher.ts`
 
 #### Signature
 
@@ -1142,7 +1146,7 @@ Merges principal columns into an existing column definitions object.
 
 Adds polymorphic data storage columns for entities that need to store values of different types in a single table. This is useful for key-value stores, settings tables, or any schema where a row's value type is determined at runtime.
 
-**File:** `packages/core/src/base/models/enrichers/data-type.enricher.ts`
+**File:** `packages/core/src/connectors/postgres/models/enrichers/data-type.enricher.ts`
 
 #### Signature
 
@@ -1215,7 +1219,7 @@ export const settingTable = pgTable('Setting', {
 // Generates columns with SQL defaults:
 // data_type text DEFAULT 'text'
 // t_value text DEFAULT ''
-// nValue, bValue, jValue, boValue — no defaults
+// nValue, bValue, jValue, boValue - no defaults
 ```
 
 **Key-value store pattern:**
@@ -1276,7 +1280,7 @@ Generates a Zod schema for path parameters containing an `id` field, suitable fo
 #### Signature
 
 ```typescript
-idParamsSchema(opts?: { idType: string }): z.ZodObject<{ id: z.ZodNumber | z.ZodString }>
+idParamsSchema(opts?: { idType: TIdSchemaType }): z.ZodObject<{ id: z.ZodNumber | z.ZodString }>
 ```
 
 | `idType` | Default | Zod Type | Examples |
@@ -1479,13 +1483,23 @@ try {
 
 ### `getIdType`
 
-Utility function to determine the data type of an entity's `id` column at runtime:
+There are two distinct `getIdType`s in the framework - don't confuse them:
+
+| | Neutral instance method | PostgreSQL utility function |
+|---|---|---|
+| **Location** | `AbstractEntity.getIdType()` (`packages/core/src/base/models/base.ts`) | `getIdType()` (`packages/core/src/connectors/postgres/models/common/types.ts`) |
+| **Signature** | `getIdType(): TIdSchemaType` | `getIdType<T extends TTableSchemaWithId>(opts: { entity: T }): string` |
+| **Purpose** | Neutral capability every engine's entity implements - returns `'string'` \| `'number'` at the entity level. Used by `idParamsSchema` to build the right Zod schema for path parameters. | PostgreSQL-specific: inspects a Drizzle table schema's `id` column and returns its `dataType` (e.g., `'number'`, `'string'`), or `'unknown'` if not determinable |
 
 ```typescript
-getIdType<T extends TTableSchemaWithId>(opts: { entity: T }): string
-```
+// Neutral - instance method every AbstractEntity subclass exposes (default 'string', BasePostgresEntity overrides based on the column)
+const entity = new User();
+entity.getIdType(); // 'string' | 'number'
 
-Returns the `dataType` property of the entity's `id` column (e.g., `'number'`, `'string'`), or `'unknown'` if not determinable.
+// PostgreSQL connector - standalone utility inspecting a raw Drizzle schema
+import { getIdType } from '@venizia/ignis/postgres';
+getIdType({ entity: User.schema }); // 'string' | 'number' | 'unknown'
+```
 
 ## See Also