@venizia/ignis-docs 0.2.1-0 → 0.2.1-1

package/content/references/base/filter-system/use-cases.md

@@ -6,11 +6,11 @@ difficulty: intermediate
 
 # Use Case Gallery
 
-Runnable `filter` objects paired with the SQL `FilterBuilder` produces for them - copy the shape that's closest to what you need. For the operators themselves, start at the [Filter System Overview](./).
+Runnable `filter` objects, paired with the SQL `FilterBuilder` produces for them. Copy the shape closest to what you need. For the operators themselves, start at the [Filter System Overview](./).
 
 ## Soft delete
 
-The smallest real use case - `is`/`isn` against a nullable timestamp:
+Goal: return only non-deleted rows, or only deleted ones.
 
 ```typescript
 // Active (non-deleted) records
@@ -26,11 +26,13 @@ const deletedRecords = await repository.find({
 // SQL: SELECT * FROM "Record" WHERE "deleted_at" IS NOT NULL
 ```
 
-If every query on a model should exclude deleted rows, encode this once as `settings.defaultFilter` instead of repeating it at every call site - see [Default Filter](./default-filter).
+Notice: `is`/`isn` against a nullable timestamp is the whole pattern - no separate `deleted: boolean` column needed.
+
+If every query on a model should exclude deleted rows, encode this once as `settings.defaultFilter` instead of repeating it at every call site. See [Default Filter](./default-filter).
 
 ## E-commerce product search
 
-Range, list, and pattern operators combined with field selection and sorting:
+Goal: a price range, a minimum quantity, and a status, sorted and paged for a listing page.
 
 ```typescript
 const products = await productRepository.find({
@@ -58,9 +60,11 @@ const products = await productRepository.find({
 // LIMIT 24
 ```
 
+Notice: four `where` keys AND-compose automatically - no explicit `and` needed for a flat condition list.
+
 ## Admin dashboard: recent users
 
-`gte` for a rolling window, `nin` to exclude states, `isn` for presence:
+Goal: users created in the last 30 days, excluding banned or suspended accounts, with a verified email.
 
 ```typescript
 const thirtyDaysAgo = new Date();
@@ -89,9 +93,11 @@ const recentUsers = await userRepository.find({
 // LIMIT 50
 ```
 
+Notice: `nin` on `status` silently drops any row where `status` is `NULL`. See [Tips & Edge Cases](./tips) before relying on this for a nullable column.
+
 ## Multi-tenant isolation at the call site
 
-`settings.defaultFilter` (see [Default Filter](./default-filter)) is the model-level way to enforce a tenant scope. A helper that injects `tenantId` at every call site is the call-site alternative - useful when tenant isolation is a caller concern rather than a per-model constant:
+`settings.defaultFilter` (see [Default Filter](./default-filter)) is the model-level way to enforce a tenant scope. The alternative below is a helper that injects `tenantId` at every call site instead. Use it when tenant isolation is a caller concern, not a per-model constant.
 
 ```typescript
 const getTenantProducts = (tenantId: string, filter: TFilter<TProductSchema>) =>
@@ -115,11 +121,11 @@ await getTenantProducts('tenant-abc', {
 // LIMIT 20
 ```
 
-Unlike `defaultFilter`'s narrowing merge, this is a plain object spread - `tenantId`/`deletedAt` simply overwrite same-named keys from `filter.where` because they're spread last.
+Notice: this is a plain object spread, not `mergeFilter`'s narrowing merge - `tenantId`/`deletedAt` overwrite same-named keys from `filter.where` because they're spread last.
 
 ## Task management: priority tags
 
-`nin` plus an array `overlaps` operator, with a relation include:
+Goal: open tasks assigned to the current user that carry an urgent or high-priority tag, with the parent project loaded.
 
 ```typescript
 const priorityTasks = await taskRepository.find({
@@ -146,9 +152,11 @@ const priorityTasks = await taskRepository.find({
 // SELECT * FROM "Project" WHERE "id" IN (...)
 ```
 
+Notice: `include` runs as a separate query, not a SQL `JOIN` - see [Relations & Includes](../repositories/relations).
+
 ## Date range queries
 
-`between` for a closed window, `gte` for a rolling one:
+Goal: a closed window (a specific week) versus a rolling window (the last 7 days).
 
 ```typescript
 const startOfWeek = new Date('2024-12-29');
@@ -184,9 +192,11 @@ const recentOrders = await orderRepository.find({
 // ORDER BY "total" DESC LIMIT 100
 ```
 
+Notice: `between` needs exactly two elements - `FilterBuilder` throws on any other array length.
+
 ## Inventory low-stock alert
 
-Nested `or`/`and` groups plus a JSON path presence check:
+Goal: active products at or under a reorder threshold, flagged critical below 5 units or fast-moving stock at 10 or fewer.
 
 ```typescript
 const lowStockProducts = await productRepository.find({
@@ -218,9 +228,11 @@ const lowStockProducts = await productRepository.find({
 // ORDER BY "quantity" ASC
 ```
 
+Notice: `or` nests an `and` group one level deep - `FilterBuilder` recurses through logical groups, so nesting depth is not limited to one.
+
 ## Complex authorization filter
 
-A `where` builder branching on role, composed with the caller's own scope - the `or` group only appears for non-admins:
+Goal: an admin sees everything; everyone else sees only what they own, what is public, or what is shared with them.
 
 ```typescript
 const getAuthorizedFilter = (user: User): TWhere<TDocumentSchema> => {
@@ -255,9 +267,11 @@ const documents = await documentRepository.find({
 // ORDER BY "updated_at" DESC LIMIT 100
 ```
 
+Notice: a plain TypeScript function builds the `where`, branching on role. A filter is a normal object, not a DSL with its own control flow.
+
 ## Full-text search with metadata
 
-Conditional `where` assembly - each filter argument adds a key only if the caller supplied it:
+Goal: assemble a `where` clause from optional caller input, adding a key only when the caller supplied it.
 
 ```typescript
 const searchProducts = async (
@@ -295,9 +309,11 @@ const searchProducts = async (
 // ORDER BY "rating" DESC, "created_at" DESC LIMIT 50
 ```
 
+Notice: `ilike` reaches into a JSON path (`'metadata.keywords'`) the same way it reaches a top-level column.
+
 ## Everything at once
 
-Every operator family, a JSON path, a three-way `or`, and a scoped relation include in one filter - the ceiling of what a single `TFilter` can express:
+Every operator family, a JSON path, a three-way `or`, and a scoped relation include - all in one filter. This is the ceiling of what a single `TFilter` can express.
 
 ```typescript
 const massiveFilter: TFilter<TProductSchema> = {
@@ -363,6 +379,8 @@ const products = await productRepository.find({ filter: massiveFilter });
 // SELECT * FROM "Review" WHERE "product_id" IN (...) AND "rating" >= 4 ORDER BY "created_at" DESC LIMIT 5
 ```
 
+Notice: `'metadata.priority': { gte: 3 }` gets the numeric `CASE` cast because the operand is a number. `'metadata.isNewArrival': true` does not, because it compares as text. See [Tips & Edge Cases](./tips) for the full casting rule.
+
 ## See also
 
 - [Filter System Overview](./) - the `filter` shape and every `where` operator family
@@ -372,5 +390,5 @@ const products = await productRepository.find({ filter: massiveFilter });
 
 **Files:**
 
-- [`packages/core/src/connectors/postgres/repositories/dialect/filter.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/repositories/dialect/filter.ts) - `FilterBuilder`, translates `TFilter` to Drizzle/SQL
-- [`packages/core/src/connectors/postgres/repositories/dialect/query.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/repositories/dialect/query.ts) - `PostgresQueryOperators.FNS`, per-operator SQL builders
+- [`packages/core-server/src/connectors/relational/repositories/dialect/filter.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/relational/repositories/dialect/filter.ts) - `FilterBuilder`, translates `TFilter` to Drizzle/SQL
+- [`packages/core-server/src/connectors/postgres/repositories/dialect/query.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/repositories/dialect/query.ts) - `PostgresQueryOperators.FNS`, per-operator SQL builders

package/content/references/base/grpc-controllers.md

@@ -11,13 +11,13 @@ Technical reference for gRPC controller classes -- the foundation for building g
 IGNIS gRPC controllers follow the same patterns as REST controllers (decorator-based routing, `binding()` method, DI integration) while bridging to ConnectRPC's universal handler system. REST and gRPC controllers coexist in the same application, sharing the same DI container, middleware pipeline, and lifecycle.
 
 **Files:**
-- `packages/core/src/base/controllers/grpc/abstract.ts`
-- `packages/core/src/base/controllers/grpc/base.ts`
-- `packages/core/src/base/controllers/grpc/adapter.ts`
-- `packages/core/src/base/controllers/grpc/common/types.ts`
-- `packages/core/src/base/metadata/routes/rpc.ts`
-- `packages/core/src/components/controller/grpc/grpc.component.ts`
-- `packages/core/src/components/controller/grpc/common/types.ts`
+- `packages/core-server/src/base/controllers/grpc/abstract.ts`
+- `packages/core-server/src/base/controllers/grpc/base.ts`
+- `packages/core-server/src/base/controllers/grpc/adapter.ts`
+- `packages/core-server/src/base/controllers/grpc/common/types.ts`
+- `packages/core-server/src/base/metadata/routes/rpc.ts`
+- `packages/core-server/src/components/controller/grpc/grpc.component.ts`
+- `packages/core-server/src/components/controller/grpc/common/types.ts`
 
 ## Quick Reference
 
@@ -35,7 +35,7 @@ IGNIS gRPC controllers follow the same patterns as REST controllers (decorator-b
 | **@rpc** | Generic method decorator (requires explicit `method` in configs) |
 
 > [!WARNING]
-> **Current version supports unary RPCs only.** The `@serverStream`, `@clientStream`, and `@bidiStream` decorators still exist and set metadata correctly, but `BaseGrpcController.registerRoute()` will throw a clear error at boot time if a non-unary RPC is registered. This is because the Connect protocol over HTTP/1.1 cannot support streaming. The decorators are preserved for forward compatibility.
+> **Current version supports unary RPCs only.** The `@serverStream`, `@clientStream`, and `@bidiStream` decorators still exist and set metadata correctly. But `BaseGrpcController.registerRoute()` throws a clear error at boot time if a non-unary RPC is registered - the Connect protocol over HTTP/1.1 cannot support streaming. The decorators are preserved for forward compatibility.
 
 ## Prerequisites
 
@@ -57,7 +57,7 @@ bun add @connectrpc/connect-web
 ```
 
 > [!NOTE]
-> `@connectrpc/connect` is an **optional** peer dependency of `@venizia/ignis` - it is only loaded at runtime when a gRPC controller is configured, via `createRequire` from the application's `node_modules`. If it is missing, `GrpcRequestAdapter.build()` throws a clear error at startup via `validateModule()`. `@bufbuild/protobuf` is required by your generated protobuf code (e.g. `create()`), not by the framework itself.
+> `@connectrpc/connect` is an **optional** peer dependency of `@venizia/ignis`. It is only loaded at runtime when a gRPC controller is configured, via `createRequire` from the application's `node_modules`. If it is missing, `GrpcRequestAdapter.build()` throws a clear error at startup via `ModuleUtility.assertInstalled()`. A compiled binary has no `node_modules` to resolve against and must pass the peer through `IGrpcComponentConfig.module` - see [Peer Dependency Loading](#peer-dependency-loading). `@bufbuild/protobuf` is required by your generated protobuf code (e.g. `create()`), not by the framework itself.
 
 ### Protobuf Code Generation
 
@@ -229,7 +229,7 @@ The `configure()` method on `AbstractGrpcController` is idempotent (guarded by `
 
 ## RPC Decorators
 
-All RPC decorators live in `packages/core/src/base/metadata/routes/rpc.ts`. They register metadata in the `MetadataRegistry`, which is read during `configure()`.
+All RPC decorators live in `packages/core-server/src/base/metadata/routes/rpc.ts`. They register metadata in the `MetadataRegistry`, which is read during `configure()`.
 
 ### `@rpc` -- Generic
 
@@ -415,7 +415,7 @@ Internal bridge between IGNIS gRPC controllers and ConnectRPC's universal handle
 
 ### Architecture
 
-The adapter solves a key challenge: ConnectRPC handlers have their own `(request, context) => response` signature, but IGNIS controllers need access to the Hono `Context` for middleware, auth, and request-scoped state. The adapter uses `AsyncLocalStorage` to provide request-scoped context isolation, ensuring concurrent requests never share state.
+The adapter solves a key challenge: ConnectRPC handlers have their own `(request, context) => response` signature. IGNIS controllers, though, need access to the Hono `Context` for middleware, auth, and request-scoped state. The adapter uses `AsyncLocalStorage` to provide request-scoped context isolation, ensuring concurrent requests never share state.
 
 ```
 Hono Request
@@ -429,7 +429,7 @@ Hono Request
 
 ### Static `build()` Method
 
-The only public API. Validates peer deps via `validateModule()`, creates the adapter, and returns the middleware + registered paths:
+The only public API. Validates peer deps via `ModuleUtility.assertInstalled()`, creates the adapter, and returns the middleware + registered paths:
 
 ```typescript
 static async build(opts: {
@@ -462,12 +462,27 @@ The optional `interceptors` array is passed to ConnectRPC's `createConnectRouter
 
 ### Peer Dependency Loading
 
-The adapter loads ConnectRPC modules at runtime using `createRequire` from the application's `node_modules`:
+The adapter needs two entry points:
 
 - `@connectrpc/connect` -- for `createConnectRouter`
 - `@connectrpc/connect/protocol` -- for `universalServerRequestFromFetch` and `universalServerResponseToFetch`
 
-This approach supports single-file builds where the peer deps may not be resolvable via standard `import`.
+By default it loads both at runtime using `createRequire` from the application's `node_modules`. That keeps the specifier invisible to `Bun.build`, so a consumer who never uses gRPC is not forced to install the peer.
+
+**A compiled application must pass `module`.** A `bun build --compile` binary ships without `node_modules`, so `createRequire` has nothing to resolve against. Hand the peer over through the component options instead - the static import is what embeds it in the binary:
+
+```typescript
+import * as connect from '@connectrpc/connect';
+import * as protocol from '@connectrpc/connect/protocol';
+
+this.bind({ key: GrpcBindingKeys.GRPC_COMPONENT_OPTIONS }).toValue({
+  module: { connect, protocol },
+});
+```
+
+`GrpcComponent` assigns the module to each controller before `configure()`, and the adapter skips both `assertInstalled` and `createRequire` when it is present.
+
+`ModuleUtility.register` does not work here. The adapter resolves the specifier itself, so the registry never reaches it.
 
 ### Error Handling
 
@@ -477,7 +492,7 @@ On handler errors, the adapter returns a JSON response with:
 - `grpc-message` header: URL-encoded error message
 - Body: JSON `{ message, code }`
 
-The adapter uses a duck-type check on `error.code` to preserve gRPC status codes from ConnectRPC errors without importing `ConnectError` directly, avoiding tight coupling to the peer dependency.
+The adapter uses a duck-type check on `error.code` to preserve gRPC status codes from ConnectRPC errors, without importing `ConnectError` directly. That avoids tight coupling to the peer dependency.
 
 ## `GrpcComponent`
 
@@ -488,9 +503,30 @@ Auto-discovers and configures gRPC controllers during the application lifecycle.
 ```typescript
 interface IGrpcComponentConfig {
   interceptors?: unknown[];
+  module?: IConnectRpcModule;
 }
 ```
 
+| Option | Type | Default | Meaning |
+|---|---|---|---|
+| `interceptors` | `unknown[]` | none | ConnectRPC interceptors, passed to `createConnectRouter` for every gRPC controller. An empty list passes nothing |
+| `module` | `IConnectRpcModule` | none | The ConnectRPC peer, as `{ connect, protocol }`. Required for a compiled binary - see [Peer Dependency Loading](#peer-dependency-loading) |
+
+Both options are component-wide. `GrpcComponent` assigns them to every gRPC controller it discovers, before calling `configure()`:
+
+```typescript
+import type { Interceptor } from '@connectrpc/connect';
+
+const logging: Interceptor = next => async request => {
+  const response = await next(request);
+  return response;
+};
+
+this.bind({ key: GrpcBindingKeys.GRPC_COMPONENT_OPTIONS }).toValue({
+  interceptors: [logging],
+});
+```
+
 The component registers a default (empty) config binding under the key `'@app/grpc/options'` (`GrpcBindingKeys.GRPC_COMPONENT_OPTIONS`).
 
 ### Behavior
@@ -623,7 +659,7 @@ export class Application extends BaseApplication {
 ```
 
 > [!WARNING]
-> If `transports` does not include `ControllerTransports.GRPC`, gRPC controllers are still registered in the DI container but the `GrpcComponent` is never mounted -- their `configure()` is never called and no routes are served.
+> If `transports` does not include `ControllerTransports.GRPC`, gRPC controllers are still registered in the DI container. But the `GrpcComponent` is never mounted -- their `configure()` is never called and no routes are served.
 
 ### Dual Transport
 
@@ -639,7 +675,7 @@ preConfigure() {
 }
 ```
 
-REST controllers are handled by the `RestComponent` (active when transports includes `ControllerTransports.REST`, which is the default); gRPC controllers are handled by the `GrpcComponent` (active when transport is enabled). They share the same DI container and lifecycle.
+REST controllers are handled by the `RestComponent`, active when `transports` includes `ControllerTransports.REST` (the default). gRPC controllers are handled by the `GrpcComponent`, active when that transport is enabled. They share the same DI container and lifecycle.
 
 ## Complete Example
 

package/content/references/base/index.md

@@ -9,7 +9,7 @@ Core classes that power every IGNIS application - from the Application entry poi
 
 | Class | Purpose | Extends |
 |-------|---------|---------|
-| `BaseApplication` | Application entry point, DI container | `AbstractApplication` |
+| `BaseApplication` | Application entry point, DI container | `ServerApplication` -> `RestApplication` -> `AbstractApplication` |
 | `BaseRestController` | REST/HTTP route handlers | `AbstractRestController` |
 | `BaseGrpcController` | gRPC route handlers (ConnectRPC) | `AbstractGrpcController` |
 | `BaseService` | Business logic layer | - |
@@ -79,8 +79,10 @@ Core classes that power every IGNIS application - from the Application entry poi
 ## Class Hierarchy
 
 ```
-AbstractApplication
-└── BaseApplication ──────► Your Application
+AbstractApplication (browser-pure, @venizia/ignis-kernel)
+└── RestApplication (browser-pure, owns the router)
+    └── ServerApplication (opens the socket)
+        └── BaseApplication ──────► Your Application
 
 AbstractRepository (engine-neutral, src/base)
 ├── PostgresBaseRepository (connectors/postgres)

package/content/references/base/middlewares.md

@@ -10,10 +10,10 @@ lastUpdated: 2026-06-14
 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/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`
+- `packages/core-server/src/base/middlewares/app-error/app-error.middleware.ts`
+- `packages/core-server/src/base/middlewares/not-found/not-found.middleware.ts`
+- `packages/core-server/src/base/middlewares/request-spy/request-spy.middleware.ts`
+- `packages/core-server/src/base/middlewares/emoji-favicon/emoji-favicon.middleware.ts`
 
 ## Prerequisites
 
@@ -86,7 +86,7 @@ class AppErrorMiddleware extends BaseHelper implements IProvider<ErrorHandler> {
 
 When `error.name === 'ZodError'`, returns HTTP `422 Unprocessable Entity`.
 
-`message` and `normalized.code` come from the first failing issue - `message` is that issue's message, `normalized.code` is its `params.code` if the schema set one, otherwise its raw Zod code. The full per-field list stays under `details.cause`. `normalized.args` is always `{}` - a Zod issue carries no interpolation values.
+`message` and `normalized.code` come from the first failing issue. `message` is that issue's message; `normalized.code` is its `params.code` if the schema set one, otherwise its raw Zod code. The full per-field list stays under `details.cause`. `normalized.args` is always `{}` - a Zod issue carries no interpolation values.
 
 ```json
 {
@@ -126,11 +126,11 @@ z.string().refine(isEmail, {
 ```
 
 > [!NOTE]
-> When `error.message` cannot be parsed as the expected Zod issue array (a malformed or unrecognized `ZodError`), no issue-derived code exists - `normalized.code` still resolves to `MessageCode.DEFAULT` (`"core.system_error"`) via `MessageCode.resolve(undefined)`. No error response from this middleware is ever missing `normalized.code`.
+> When `error.message` cannot be parsed as the expected Zod issue array (a malformed or unrecognized `ZodError`), no issue-derived code exists. `normalized.code` still resolves to `MessageCode.DEFAULT` (`"core.system_error"`) via `MessageCode.resolve(undefined)`. No error response from this middleware is ever missing `normalized.code`.
 
 #### 2. PostgreSQL Constraint Violations
 
-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.
+Database errors in SQLSTATE class `22` (data exception), `23` (integrity constraint), and `44` (WITH CHECK OPTION violation) are detected by class. They return 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 |
 |-------|-------------------------------|
@@ -139,7 +139,7 @@ Database errors in SQLSTATE class `22` (data exception), `23` (integrity constra
 | `44` View check | `44000` WITH CHECK OPTION violation |
 
 :::tip Transient conflicts return 409, not 400/500
-Class `40` (`40001` serialization failure, `40P01` deadlock) is transient/retryable and returns **409 Conflict** with `normalized.code: "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.
+Class `40` (`40001` serialization failure, `40P01` deadlock) is transient/retryable. It returns **409 Conflict** with `normalized.code: "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.
 :::
 
 :::warning Production sanitizes database internals
@@ -249,7 +249,8 @@ function notFoundHandler(opts: {
 }
 ```
 
-The handler logs the 404 at error level with the request ID, path, and full URL.
+The handler logs the 404 at warn level with the request ID, path, and full URL. An unrouted path is a
+client mistake, not a server fault - alerting tuned to error level should not fire on it.
 
 
 ## RequestSpyMiddleware
@@ -496,7 +497,7 @@ export class MyMiddleware extends BaseHelper implements IProvider<MiddlewareHand
 }
 ```
 
-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:
+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 {

package/content/references/base/models-reference.md

@@ -10,10 +10,10 @@ Exhaustive reference for the `@model` decorator, the entity class hierarchy, and
 
 **Files:**
 
-- [`packages/core/src/base/models/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/models/base.ts) - neutral `AbstractEntity`
-- [`packages/core/src/connectors/postgres/models/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/models/base.ts) - PostgreSQL entity (`BaseRelationalEntity`, aliases `BaseEntity`/`BasePostgresEntity`)
-- [`packages/core/src/base/metadata/persistents.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/metadata/persistents.ts) - `@model` decorator
-- [`packages/core/src/connectors/postgres/models/enrichers`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/models/enrichers) - schema enrichers
+- [`packages/core-server/src/base/models/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/models/base.ts) - neutral `AbstractEntity`
+- [`packages/core-server/src/connectors/postgres/models/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/models/base.ts) - PostgreSQL entity (`BaseRelationalEntity`, aliases `BaseEntity`/`BasePostgresEntity`)
+- [`packages/core-server/src/base/metadata/persistents.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/metadata/persistents.ts) - `@model` decorator
+- [`packages/core-server/src/connectors/postgres/models/enrichers`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/models/enrichers) - schema enrichers
 
 ## `AbstractEntity` (neutral) vs. `BaseEntity` (connector)
 
@@ -23,7 +23,7 @@ IGNIS separates the engine-neutral entity root from the connector-specific imple
 - **Minimal surface.** It carries only a `name`, an abstract `getSchema()`, a `getIdType(): TIdSchemaType` method (default `'string'`), and `toObject()`/`toJSON()`.
 - **Everything else is connector-owned.** The Drizzle-backed entity, `drizzle-zod` schema generation, and all schema enrichers belong to the PostgreSQL connector, not the neutral base. See [Connectors](/references/base/connectors) for the full base-vs-connector architecture.
 
-`Source ->` [`packages/core/src/base/models/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/models/base.ts)
+`Source ->` [`packages/core-server/src/base/models/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/models/base.ts)
 
 ```typescript
 export abstract class AbstractEntity<Schema = unknown> extends BaseHelper {
@@ -57,7 +57,7 @@ export abstract class AbstractEntity<Schema = unknown> extends BaseHelper {
 
 Marks a class as a database entity and configures its behavior.
 
-`Source ->` [`packages/core/src/base/metadata/persistents.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/metadata/persistents.ts)
+`Source ->` [`packages/core-server/src/base/metadata/persistents.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/metadata/persistents.ts)
 
 ```typescript
 @model({
@@ -102,7 +102,7 @@ When the `@model` decorator is applied:
 
 PostgreSQL connector entity class, wrapping a Drizzle ORM schema. Extends the neutral `AbstractEntity`.
 
-`Source ->` [`packages/core/src/connectors/postgres/models/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/models/base.ts)
+`Source ->` [`packages/core-server/src/connectors/postgres/models/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/models/base.ts)
 
 ### Purpose
 
@@ -418,7 +418,7 @@ export const myTable = pgTable('MyTable', {
 
 Adds a primary key `id` column with full TypeScript type inference.
 
-`Source ->` [`packages/core/src/connectors/postgres/models/enrichers/id.enricher.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/models/enrichers/id.enricher.ts)
+`Source ->` [`packages/core-server/src/connectors/postgres/models/enrichers/id.enricher.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/models/enrichers/id.enricher.ts)
 
 ```typescript
 generateIdColumnDefs<Opts extends TIdEnricherOptions | undefined>(opts?: Opts): TIdColumnDef<Opts>
@@ -466,7 +466,7 @@ enrichId(baseColumns: TColumnDefinitions, opts?: TIdEnricherOptions): TColumnDef
 
 Adds timestamp columns for creation, modification, and soft deletion.
 
-`Source ->` [`packages/core/src/connectors/postgres/models/enrichers/tz.enricher.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/models/enrichers/tz.enricher.ts)
+`Source ->` [`packages/core-server/src/connectors/postgres/models/enrichers/tz.enricher.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/models/enrichers/tz.enricher.ts)
 
 ```typescript
 generateTzColumnDefs<Opts extends TTzEnricherOptions | undefined>(opts?: Opts): TTzEnricherResult<Opts>
@@ -540,7 +540,7 @@ await db.update(myTable).set({ deletedAt: null }).where(eq(myTable.id, id));
 
 Adds `createdBy` and `modifiedBy` columns tracking which user created or modified a record.
 
-`Source ->` [`packages/core/src/connectors/postgres/models/enrichers/user-audit.enricher.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/models/enrichers/user-audit.enricher.ts)
+`Source ->` [`packages/core-server/src/connectors/postgres/models/enrichers/user-audit.enricher.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/models/enrichers/user-audit.enricher.ts)
 
 ```typescript
 generateUserAuditColumnDefs(opts?: TUserAuditEnricherOptions): {
@@ -571,7 +571,7 @@ Defaults:
 
 **How it works**
 
-- **Retrieval.** The enricher uses Hono's `contextStorage` (via `tryGetContext()`) to retrieve the current user ID at insert/update time, reading it from the `Authentication.AUDIT_USER_ID` key.
+- **Retrieval.** The enricher reads the request context from `RequestContextRegistry` at insert/update time, then takes the user ID off the `Authentication.AUDIT_USER_ID` key. An application installs the resolver over that registry when it registers its default middlewares, backed by Hono's `contextStorage`. A host that installs none - a browser Worker - has no request context at all, which is the `allowAnonymous` case below.
 - **`createdBy`.** Set via `$default()` - creation only.
 - **`modifiedBy`.** Set via both `$default()` and `$onUpdate()` - creation and every modification.
 
@@ -610,7 +610,7 @@ enrichUserAudit<ColumnDefinitions extends TColumnDefinitions>(
 
 Adds polymorphic principal columns for associating a record with different entity types (a comment can belong to a Post, User, or Product).
 
-`Source ->` [`packages/core/src/connectors/postgres/models/enrichers/principal.enricher.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/models/enrichers/principal.enricher.ts)
+`Source ->` [`packages/core-server/src/connectors/postgres/models/enrichers/principal.enricher.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/models/enrichers/principal.enricher.ts)
 
 ```typescript
 generatePrincipalColumnDefs<
@@ -666,7 +666,7 @@ enrichPrincipal<ColumnDefinitions extends TColumnDefinitions>(
 
 Adds polymorphic data storage columns for entities that store values of different types in a single table (key-value stores, settings tables).
 
-`Source ->` [`packages/core/src/connectors/postgres/models/enrichers/data-type.enricher.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/models/enrichers/data-type.enricher.ts)
+`Source ->` [`packages/core-server/src/connectors/postgres/models/enrichers/data-type.enricher.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/models/enrichers/data-type.enricher.ts)
 
 ```typescript
 generateDataTypeColumnDefs(opts?: TDataTypeEnricherOptions): {
@@ -731,7 +731,7 @@ enrichDataTypes(baseSchema: TColumnDefinitions, opts?: TDataTypeEnricherOptions)
 
 ## Key types
 
-`Source ->` [`packages/core/src/connectors/postgres/models/common`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/models/common)
+`Source ->` [`packages/core-server/src/connectors/postgres/models/common`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/models/common)
 
 ### `TTableSchemaWithId`
 
@@ -756,7 +756,7 @@ type TTableInsert<T extends TTableSchemaWithId> = T['$inferInsert'];
 
 Configuration for entity relationships.
 
-`Source ->` [`packages/core/src/connectors/postgres/repositories/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/repositories/common/types.ts)
+`Source ->` [`packages/core-server/src/connectors/postgres/repositories/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/repositories/common/types.ts)
 
 ```typescript
 type TRelationConfig = {
@@ -781,7 +781,7 @@ Used for `relations` on `BaseEntity` - store a function that returns the relatio
 
 ## Schema utilities
 
-`Source ->` [`packages/core/src/base/models/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/models/common/types.ts)
+`Source ->` [`packages/core-server/src/base/models/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/models/common/types.ts)
 
 ### `idParamsSchema`
 
@@ -862,7 +862,7 @@ There are two distinct `getIdType`s in the framework - do not confuse them.
 
 | | Neutral instance method | PostgreSQL utility function |
 |---|---|---|
-| Location | `AbstractEntity.getIdType()` ([`base/models/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/models/base.ts)) | `getIdType()` ([`connectors/postgres/models/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/models/common/types.ts)) |
+| Location | `AbstractEntity.getIdType()` ([`base/models/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/models/base.ts)) | `getIdType()` ([`connectors/postgres/models/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/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`, or `'unknown'` if not determinable |
 

package/content/references/base/models.md

@@ -32,7 +32,8 @@ A `@repository` binds this model to a datasource, and the datasource auto-discov
 - **Registration.** The `@model` decorator registers the class in the framework's metadata registry, keyed by table name (resolved as `tableName` > static `TABLE_NAME` > class name).
 - **Validation at decoration time.** It validates `settings.defaultLimit` and, when you declare an authorization principal, copies it onto the static `AUTHORIZATION_SUBJECT` property.
 - **Plain Drizzle schema.** The static `schema` is a plain Drizzle `pgTable`. Enrichers such as `generateIdColumnDefs` return column definitions you spread into that table, so common columns (id, timestamps, audit, principal) stay standardized across models.
-- **Zod on demand.** `BaseEntity` generates Zod schemas from the Drizzle schema via `getSchema({ type })` - `'select'`, `'create'`, and `'update'` variants for validating query results, inserts, and updates. The generator is a shared lazy singleton, so there is no per-entity cost.
+- **Zod on demand.** `BaseEntity` generates Zod schemas from the Drizzle schema via `getSchema({ type })` - `'select'`, `'create'`, and `'update'` variants for validating query results, inserts, and updates.
+  - The generator is a shared lazy singleton, so there is no per-entity cost.
 
 **Two layers**
 
@@ -149,5 +150,5 @@ See [Authorization](/extensions/components/authorization/usage#model-based-resou
 
 **Files:**
 
-- [`packages/core/src/base/models/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/models/base.ts) - neutral `AbstractEntity`
-- [`packages/core/src/connectors/postgres/models/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/models/base.ts) - PostgreSQL `BaseEntity`
+- [`packages/core-server/src/base/models/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/models/base.ts) - neutral `AbstractEntity`
+- [`packages/core-server/src/connectors/postgres/models/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/models/base.ts) - PostgreSQL `BaseEntity`

package/content/references/base/providers.md

@@ -10,7 +10,7 @@ lastUpdated: 2026-03-15
 Providers implement the Factory pattern in IGNIS, allowing you to create and configure instances dynamically at runtime based on configuration or context. Unlike services that contain business logic, providers are factories that produce values, instances, or functions.
 
 **Files:**
-- `packages/core/src/base/providers/base.ts`
+- `packages/core-server/src/base/providers/base.ts`
 
 ## Prerequisites
 
@@ -229,7 +229,7 @@ export class LoggerProvider extends BaseProvider<ILogger> {
 }
 ```
 
-Register the provider with `.toProvider()` - consumers then `get()` the **produced value**, not the provider instance (the container instantiates the provider and calls `value(container)` for you):
+Register the provider with `.toProvider()`. Consumers then `get()` the **produced value**, not the provider instance - the container instantiates the provider and calls `value(container)` for you:
 
 ```typescript
 // In your application (e.g. preConfigure)
@@ -327,7 +327,7 @@ graph TD
 
 1. **Registered via `.toProvider()`**: Providers are bound explicitly (`bind({ key }).toProvider(MyProvider)`), not auto-scanned
 2. **`value()` Called by the Container**: `container.get({ key })` instantiates the provider and calls `value(container)` - consumers receive the produced value, never the provider instance
-3. **Singleton Scope Caches the Produced Value**: With `.setScope(BindingScopes.SINGLETON)`, the container caches the result of `value()` and returns it on subsequent `get()` calls; with the default transient scope, `value()` runs on every `get()`
+3. **Singleton Scope Caches the Produced Value**: With `.setScope(BindingScopes.SINGLETON)`, the container caches the result of `value()` and returns it on subsequent `get()` calls. With the default transient scope, `value()` runs on every `get()`
 4. **Factory vs Instance**: Providers can return:
    - Direct instances (created each time `value()` is called)
    - Factory functions (deferred creation)
@@ -350,7 +350,7 @@ app.bind({ key: 'providers.Database' }).toProvider(DatabaseProvider);
 
 ### Example 1: Mail Transport Provider
 
-From `packages/core/src/components/mail/providers/mail-transporter.provider.ts`:
+From `packages/core-server/src/components/mail/providers/mail-transporter.provider.ts`:
 
 ```typescript
 export type TGetMailTransportFn = (options: TMailOptions) => IMailTransport;
@@ -419,7 +419,7 @@ this.application.bind({ key: MailKeys.MAIL_TRANSPORT_INSTANCE }).toValue(mailTra
 
 ### Example 2: Queue Executor Provider
 
-From `packages/core/src/components/mail/providers/mail-queue-executor.provider.ts`:
+From `packages/core-server/src/components/mail/providers/mail-queue-executor.provider.ts`:
 
 ```typescript
 export type TGetMailQueueExecutorFn = (config: IMailQueueExecutorConfig) => IMailQueueExecutor;
@@ -472,7 +472,7 @@ export class MailQueueExecutorProvider extends BaseProvider<TGetMailQueueExecuto
 Providers can also produce middleware. `RequestSpyMiddleware` is a real-world example that implements `IProvider<MiddlewareHandler>` directly (extending `BaseHelper`, not `BaseProvider`):
 
 ```typescript
-// From packages/core/src/base/middlewares/request-spy/request-spy.middleware.ts
+// From packages/core-server/src/base/middlewares/request-spy/request-spy.middleware.ts
 export class RequestSpyMiddleware extends BaseHelper implements IProvider<MiddlewareHandler> {
   static readonly REQUEST_ID_KEY = 'requestId';
 
@@ -509,7 +509,7 @@ export class RequestSpyMiddleware extends BaseHelper implements IProvider<Middle
 
 See [Middlewares](./middlewares.md) for the full implementation (IP resolution, body-parsing rules, and production log redaction).
 
-Note that `RequestSpyMiddleware.value()` does not accept a `container` parameter -- the `IProvider<T>` interface defines `value(container: Container): T`, but implementations may ignore the parameter when they don't need container access. In practice, `RequestSpyMiddleware` is registered via `RequestTrackerComponent`, which binds it as a provider in the DI container and resolves it automatically.
+Note that `RequestSpyMiddleware.value()` does not accept a `container` parameter. The `IProvider<T>` interface defines `value(container: Container): T`, but implementations may ignore the parameter when they don't need container access. In practice, `RequestSpyMiddleware` is registered via `RequestTrackerComponent`, which binds it as a provider in the DI container and resolves it automatically.
 
 
 ## Common Patterns
@@ -545,7 +545,7 @@ export class S3StorageProvider extends BaseProvider<S3Storage> {
 
 ### Pattern 2: Lazy Singleton
 
-Create instance only once, lazily (or simply bind with `.setScope(BindingScopes.SINGLETON)` and let the container cache the produced value):
+Create instance only once, lazily (or bind with `.setScope(BindingScopes.SINGLETON)` and let the container cache the produced value):
 
 ```typescript
 export class DatabaseConnectionProvider extends BaseProvider<DatabaseConnection> {