@venizia/ignis-docs 0.2.0 → 0.2.1-1

package/content/references/base/dependency-injection.md

@@ -9,13 +9,13 @@ difficulty: advanced
 Technical reference for the DI system in IGNIS - managing resource lifecycles and dependency resolution.
 
 **Files:**
-- `packages/inversion/src/container.ts` - Base `Container` and `Binding` classes
-- `packages/inversion/src/registry.ts` - Base `MetadataRegistry`
-- `packages/inversion/src/metadata/injectors.ts` - Base `@inject` and `@injectable` decorators
+- `packages/inversion/src/modules/container/index.ts` - Base `Container` and `Binding` classes
+- `packages/inversion/src/modules/registry/index.ts` - Base `MetadataRegistry`
+- `packages/inversion/src/modules/metadata/injectors.ts` - Base `@inject` decorator
 - `packages/inversion/src/common/types.ts` - `BindingScopes`, `BindingValueTypes`, `BindingKeys`, `IProvider`
-- `packages/core/src/helpers/inversion/container.ts` - Extended `Container` with `ApplicationLogger`
-- `packages/core/src/helpers/inversion/registry.ts` - Extended `MetadataRegistry` (singleton, with model/repository/datasource mixins)
-- `packages/core/src/base/metadata/injectors.ts` - Core `@inject` and `@injectable` (wired to extended registry)
+- `packages/core-server/src/helpers/inversion/container.ts` - Extended `Container` with `ApplicationLogger`
+- `packages/core-server/src/helpers/inversion/registry.ts` - Extended `MetadataRegistry` (singleton, with model/repository/datasource mixins)
+- `packages/core-server/src/base/metadata/injectors.ts` - Core `@inject` (wired to extended registry)
 
 ## Quick Reference
 
@@ -24,7 +24,6 @@ Technical reference for the DI system in IGNIS - managing resource lifecycles an
 | **Container** | DI registry managing resource lifecycles | `bind()`, `get()`, `gets()`, `instantiate()`, `resolve()`, `findByTag()`, `isBound()`, `unbind()`, `clear()`, `reset()` |
 | **Binding** | Single registered dependency configuration | `toClass()`, `toValue()`, `toProvider()`, `setScope()`, `setTags()`, `getValue()`, `clearCache()` |
 | **@inject** | Decorator marking injection points | Applied to constructor parameters and class properties |
-| **@injectable** | Decorator marking a class as injectable | Stores scope and tag metadata |
 | **MetadataRegistry** | Stores decorator metadata | Singleton - base via `metadataRegistry` export, core via `MetadataRegistry.getInstance()` |
 | **BindingKeys** | Utility for building namespaced keys | `BindingKeys.build({ namespace, key })` |
 | **Boot System** | Automatic artifact discovery and binding | Integrates with Container via tags and bindings |
@@ -42,7 +41,7 @@ Before reading this document, you should understand:
 
 Heart of the DI system - registry managing all application resources.
 
-**File:** `packages/inversion/src/container.ts` (Base) & `packages/core/src/helpers/inversion/container.ts` (Extended)
+**File:** `packages/inversion/src/modules/container/index.ts` (Base) & `packages/core-server/src/helpers/inversion/container.ts` (Extended)
 
 The base `Container` extends `BaseHelper` (which provides `scope` and `identifier` properties). The core `Container` extends the base and adds a `Logger` instance.
 
@@ -74,7 +73,8 @@ const container = new Container({ scope: 'MyApp' }); // scope is optional, defau
 
 When `container.instantiate(MyClass)` is called:
 
-1. **Constructor injection** - Reads `@inject` metadata from the class by parameter index (the `Reflect`-stored array is already index-keyed, so there is no sort step), resolves each dependency from the container, and passes them as constructor arguments. If any index in range has no `@inject` metadata, `instantiate()` throws immediately rather than passing `undefined`.
+1. **Constructor injection** - Reads `@inject` metadata from the class by parameter index. The `Reflect`-stored array is already index-keyed, so there is no sort step; the container resolves each dependency and passes them as constructor arguments.
+   - If any index in range has no `@inject` metadata, `instantiate()` throws immediately rather than passing `undefined`.
 2. **Property injection** - After the instance is created, reads property metadata, resolves each dependency, and assigns them directly to the instance properties.
 
 ```typescript
@@ -91,22 +91,22 @@ class UserController {
 ```
 
 > [!IMPORTANT]
-> **Every constructor parameter of a container-instantiated class must carry `@inject`.** Mixing decorated and undecorated parameters is forbidden - `@inject` stores its metadata at the parameter's index, so an undecorated parameter leaves a hole in that array, and there is no channel through which the container could supply it anyway (it would resolve to `undefined`). `instantiate()` refuses the shape by class name and parameter index instead of silently dereferencing the hole:
+> **Every constructor parameter of a container-instantiated class must carry `@inject`.** Mixing decorated and undecorated parameters is forbidden. `@inject` stores its metadata at the parameter's index, so an undecorated parameter leaves a hole in that array. There is no channel through which the container could supply it anyway - it would resolve to `undefined`. `instantiate()` refuses the shape by class name and parameter index instead of silently dereferencing the hole:
 >
 > ```
 > [NoteController] Constructor parameter 0 has no @inject | Every parameter of a container-instantiated
 > class must be decorated - the container cannot supply an undecorated one
 > ```
 >
-> The check lives in `instantiate()`, not in the `@inject` decorator itself: parameter decorators run right-to-left, so when `@inject` on parameter 1 runs, parameter 0 has not been visited yet and nothing at that point can know whether it will end up decorated.
+> The check lives in `instantiate()`, not in the `@inject` decorator itself. Parameter decorators run right-to-left, so when `@inject` on parameter 1 runs, parameter 0 has not been visited yet - nothing at that point can know whether it will end up decorated.
 >
-> This does not apply to `@repository`-decorated classes whose constructor appears undecorated at index 0 - the `@repository` decorator programmatically writes that inject metadata (`registry.setInjectMetadata({ target, index: 0, ... })`) even though no literal `@inject` appears in source. See [Repositories](./repositories/).
+> This does not apply to `@repository`-decorated classes whose constructor appears undecorated at index 0. The `@repository` decorator programmatically writes that inject metadata (`registry.setInjectMetadata({ target, index: 0, ... })`), even though no literal `@inject` appears in source. See [Repositories](./repositories/).
 
 ## `Binding` Class
 
 A `Binding` represents a single registered dependency in the container. It provides a fluent API to configure *how* a dependency should be created and managed.
 
-**File:** `packages/inversion/src/container.ts`
+**File:** `packages/inversion/src/modules/container/index.ts`
 
 The `Binding` class extends `BaseHelper`.
 
@@ -206,7 +206,7 @@ This is also used internally by `container.get()` and `container.getBinding()` w
 
 The `@inject` decorator marks where dependencies should be injected - either on constructor parameters or class properties.
 
-**File:** `packages/inversion/src/metadata/injectors.ts` (base) & `packages/core/src/base/metadata/injectors.ts` (core wrapper)
+**File:** `packages/inversion/src/modules/metadata/injectors.ts` (base) & `packages/core-server/src/base/metadata/injectors.ts` (core wrapper)
 
 ### Signature
 
@@ -257,30 +257,14 @@ The `@venizia/ignis-inversion` package exports base decorators that use the modu
 
 **Always import from `@venizia/ignis` in application code:**
 ```typescript
-import { inject, injectable } from '@venizia/ignis';
+import { inject } from '@venizia/ignis';
 ```
 
-## `@injectable` Decorator
+## Registering a Class
 
-Marks a class as injectable and attaches optional metadata.
-
-**File:** `packages/inversion/src/metadata/injectors.ts` (base) & `packages/core/src/base/metadata/injectors.ts` (core wrapper)
-
-### Signature
-
-```typescript
-@injectable({ scope?: TBindingScope; tags?: Record<string, any> })
-```
-
-| Parameter | Type | Default | Description |
-| :--- | :--- | :--- | :--- |
-| `scope` | `'singleton' \| 'transient'` | - | Optional scope hint for the binding. |
-| `tags` | `Record<string, any>` | - | Optional metadata tags. |
-
-### Example
+No class decorator is needed to make a class injectable. A class becomes resolvable once a binding exists for it. That binding can come from boot auto-discovery, from a framework helper (`app.controller()`, `app.service()`, `@repository`), or explicitly from `container.bind()`. Scope is configured on the binding, never on the class:
 
 ```typescript
-@injectable({ scope: BindingScopes.SINGLETON })
 class UserService extends BaseService {
   constructor(
     @inject({ key: 'repositories.UserRepository' })
@@ -289,15 +273,19 @@ class UserService extends BaseService {
     super({ scope: UserService.name });
   }
 }
+
+app.bind({ key: 'services.UserService' })
+  .toClass(UserService)
+  .setScope(BindingScopes.SINGLETON); // default is TRANSIENT
 ```
 
 ## `MetadataRegistry`
 
-The `MetadataRegistry` stores and retrieves all metadata attached by decorators (`@inject`, `@injectable`, `@controller`, `@model`, etc.).
+The `MetadataRegistry` stores and retrieves all metadata attached by decorators (`@inject`, `@controller`, `@model`, etc.).
 
 ### Base MetadataRegistry
 
-**File:** `packages/inversion/src/registry.ts`
+**File:** `packages/inversion/src/modules/registry/index.ts`
 
 A singleton exported as `metadataRegistry`. Extends `BaseHelper`.
 
@@ -315,12 +303,10 @@ A singleton exported as `metadataRegistry`. Extends `BaseHelper`.
 | `setPropertyMetadata({ target, propertyName, metadata })` | Stores property injection metadata (`IPropertyMetadata`). |
 | `getPropertiesMetadata({ target })` | Returns a `Map<string \| symbol, IPropertyMetadata>` for all injected properties. |
 | `getPropertyMetadata({ target, propertyName })` | Returns property metadata for a specific property. |
-| `setInjectableMetadata({ target, metadata })` | Stores `@injectable` metadata on a class. |
-| `getInjectableMetadata({ target })` | Returns `@injectable` metadata for a class. |
 
 ### Core MetadataRegistry
 
-**File:** `packages/core/src/helpers/inversion/registry.ts`
+**File:** `packages/core-server/src/helpers/inversion/registry.ts`
 
 Extends the base with controller, repository, model, and datasource metadata support via mixins. Accessed as a singleton via `MetadataRegistry.getInstance()`.
 
@@ -333,12 +319,11 @@ Additional capabilities include:
 
 ### Metadata Keys
 
-Defined in `packages/inversion/src/common/keys.ts`:
+Defined in `packages/inversion/src/modules/metadata/common/constants.ts`:
 
 ```typescript
 MetadataKeys.PROPERTIES  = Symbol.for('ignis:properties')
 MetadataKeys.INJECT      = Symbol.for('ignis:inject')
-MetadataKeys.INJECTABLE  = Symbol.for('ignis:injectable')
 ```
 
 ### Key Types
@@ -355,11 +340,6 @@ interface IPropertyMetadata {
   isOptional?: boolean;
   [key: string]: any;
 }
-
-interface IInjectableMetadata {
-  scope?: TBindingScope;
-  tags?: Record<string, any>;
-}
 ```
 
 ## Boot System Integration
@@ -436,7 +416,6 @@ The boot system integrates into the application lifecycle:
 app.bind({ key: 'controllers.UserController' }).toClass(UserController);
 
 // 4. Later, when UserController is instantiated:
-@injectable()
 class UserController {
   constructor(
     @inject({ key: 'services.UserService' })

package/content/references/base/filter-system/application-usage.md

@@ -6,48 +6,25 @@ difficulty: intermediate
 
 # Using Filters in Your Application
 
-How filters flow through the application layers.
-
-
-## Architecture Overview
+A `filter` starts as a JSON-encoded query string on an HTTP request and ends as a Drizzle query. Here is where to hook into each layer in between.
 
 ```
-+-----------------------------------------------------------------+
-|                        HTTP Request                              |
-|   GET /products?filter={"where":{"status":"active"},"limit":10} |
-+--------------------------------+--------------------------------+
-                                 |
-                                 v
-+-----------------------------------------------------------------+
-|                     Controller Layer                             |
-|   - Validates filter via Zod schema                              |
-|   - Parses JSON string -> Filter object                          |
-|   - Passes to service/repository                                 |
-+-----------------------------------------------------------------+
-                                 |
-                                 v
-+-----------------------------------------------------------------+
-|                     Service Layer (Optional)                     |
-|   - Business logic, authorization                                |
-|   - May modify filter before passing                             |
-+-----------------------------------------------------------------+
-                                 |
-                                 v
-+-----------------------------------------------------------------+
-|                     Repository Layer                             |
-|   - applyDefaultFilter() merges the @model default filter         |
-|   - FilterBuilder transforms Filter -> Drizzle query options     |
-|   - Executes query via Drizzle ORM                               |
-|   - Returns typed results                                        |
-+-----------------------------------------------------------------+
+HTTP Request         GET /products?filter={"where":{"status":"active"},"limit":10}
+      |
+      v
+Controller Layer      Validates via Zod (FilterSchema), parses JSON string -> Filter object
+      |
+      v
+Service Layer          Optional - business logic, authorization, may edit the filter
+      |
+      v
+Repository Layer       applyDefaultFilter() merges the @model default filter,
+                        FilterBuilder converts Filter -> Drizzle query options, executes
 ```
 
+## Generate a CRUD controller from an entity
 
-## Controller Layer
-
-### Using ControllerFactory (Recommended)
-
-The `ControllerFactory` automatically handles filter parsing and validation:
+For a standard `GET`/`POST`/`PATCH`/`DELETE` resource, generate the controller instead of writing filter parsing by hand. `ControllerFactory.defineCrudController` builds it from an entity and a repository binding:
 
 ```typescript
 // src/controllers/product.controller.ts
@@ -77,10 +54,7 @@ const _Controller = ControllerFactory.defineCrudController({
 export class ProductController extends _Controller {
   constructor(
     @inject({
-      key: BindingKeys.build({
-        namespace: BindingNamespaces.REPOSITORY,
-        key: ProductRepository.name,
-      }),
+      key: BindingKeys.build({ namespace: BindingNamespaces.REPOSITORY, key: ProductRepository.name }),
     })
     repository: ProductRepository,
   ) {
@@ -89,20 +63,43 @@ export class ProductController extends _Controller {
 }
 ```
 
-**Generated Endpoints:**
+This generates every filter-bearing endpoint the resource needs:
+
+| Method | Endpoint | Query param |
+|---|---|---|
+| GET | `/products` | `filter` |
+| GET | `/products/{id}` | `filter` (`where` is ignored - the id is the condition) |
+| GET | `/products/find-one` | `filter` |
+| GET | `/products/count` | `where` |
+
+Set `isStrict.requestSchema: true` to make these query params Zod-required; set `isStrict.path: true` to reject trailing-slash variants of the route. Write endpoints (`POST /`, `PATCH /{id}`, `DELETE /{id}`, ...) come from the same factory call and take no filter.
+
+## Map a request query string to a parsed filter
+
+`FilterSchema` and `WhereSchema` both accept a JSON string or a plain object, so the same schema validates a Hono query param (always a string) and a filter built in code:
+
+| Request | Parsed filter |
+|---|---|
+| `GET /products?filter={"where":{"status":"active"}}` | `{ where: { status: 'active' } }` |
+| `GET /products?filter={"limit":10,"skip":20}` | `{ limit: 10, skip: 20 }` |
+| `GET /products?filter={"where":{"price":{"gte":100,"lte":500}},"order":["price ASC"]}` | `{ where: { price: { gte: 100, lte: 500 } }, order: ['price ASC'] }` |
+| `GET /products/count?where={"role":"admin"}` | `{ role: 'admin' }` |
+
+`WhereSchema` is independent of `FilterSchema` - it backs the `count` endpoint, which takes `where` directly rather than a full filter.
 
-| Method | Endpoint | Filter Location |
-|--------|----------|-----------------|
-| GET | `/products` | Query param: `?filter={...}` |
-| GET | `/products/{id}` | Query param: `?filter={...}` (for includes) |
-| GET | `/products/find-one` | Query param: `?filter={...}` |
-| GET | `/products/count` | Query param: `?where={...}` |
+## Write a custom route that accepts a filter
 
-### Custom Controller with Manual Filter Handling
+For a route outside the generated CRUD set, use `FilterQuerySchema` - the same query shape the generated `find` route takes:
 
 ```typescript
 import { z } from '@hono/zod-openapi';
-import { BaseRestController, controller, FilterSchema, inject, jsonResponse } from '@venizia/ignis';
+import {
+  BaseRestController,
+  controller,
+  FilterQuerySchema,
+  inject,
+  jsonResponse,
+} from '@venizia/ignis';
 
 @controller({ path: '/products' })
 export class ProductController extends BaseRestController {
@@ -118,12 +115,10 @@ export class ProductController extends BaseRestController {
       configs: {
         path: '/search',
         method: 'get',
-        request: {
-          query: z.object({ filter: FilterSchema }),
-        },
+        request: { query: FilterQuerySchema },
         responses: jsonResponse({ schema: z.array(z.object({ id: z.string() })) }),
       },
-      handler: async (context) => {
+      handler: async context => {
         const { filter = {} } = context.req.valid('query');
         const results = await this._productRepository.find({ filter });
         return context.json(results);
@@ -133,25 +128,29 @@ export class ProductController extends BaseRestController {
 }
 ```
 
+### The two query shapes
 
-## Filter Schema Validation
+Reach for these instead of rebuilding the same object at every route.
 
-The `FilterSchema` (Zod) accepts both object and JSON string formats:
+| Schema | Query shape | Use it for |
+|---|---|---|
+| `FilterQuerySchema` | `{ filter?: TFilter }` | Any route that takes a full filter |
+| `WhereQuerySchema` | `{ where?: TWhere }` | Any route that takes conditions and no pagination |
 
-```typescript
-// Object format (from parsed query params)
-{ where: { status: 'active' }, limit: 10 }
+Both are plain Zod objects, so a route that takes more than one parameter extends rather than rebuilds:
 
-// JSON string format (from URL query string)
-'{"where":{"status":"active"},"limit":10}'
+```typescript
+request: { query: WhereQuerySchema.extend({ q: z.string().max(255).optional() }) },
 ```
 
-The `WhereSchema` also accepts both formats independently, useful for the `count` endpoint which takes `where` directly.
+Neither needs an extra `.optional()`. `FilterSchema` already carries one, so `FilterSchema.optional()` is the same schema written longer, and a trailing `.partial()` on a single optional key does nothing.
 
+> [!NOTE]
+> The generated `updateBy` and `deleteBy` routes deliberately do not use `WhereQuerySchema`. They require `where`, because a missing one rewrites or deletes every row in the table.
 
-## Service Layer
+## Rewrite a filter before it reaches the repository
 
-Services can modify filters before passing to repositories:
+Add a service between the controller and the repository when a constraint is a caller or session concern rather than a per-model constant - a tenant ID pulled from the request context, for example. Use [Default Filter](./default-filter) instead when the constraint applies to every caller of the model:
 
 ```typescript
 @service()
@@ -161,83 +160,56 @@ export class ProductService {
     private _productRepository: ProductRepository,
   ) {}
 
-  async findProducts(filter: TFilter<TProductSchema> = {}) {
-    // Merge user filter with soft-delete condition
-    const enhancedFilter: TFilter<TProductSchema> = {
-      ...filter,
-      where: {
-        ...filter.where,
-        deletedAt: { is: null },
-      },
-    };
-
-    return this._productRepository.find({ filter: enhancedFilter });
-  }
-
-  async findProductsForTenant(
-    tenantId: string,
-    filter: TFilter<TProductSchema> = {},
-  ) {
-    const isolatedFilter: TFilter<TProductSchema> = {
-      ...filter,
-      where: {
-        ...filter.where,
-        tenantId,
-      },
-    };
-
-    return this._productRepository.find({ filter: isolatedFilter });
+  async findProductsForTenant(tenantId: string, filter: TFilter<TProductSchema> = {}) {
+    return this._productRepository.find({
+      filter: { ...filter, where: { ...filter.where, tenantId } },
+    });
   }
 }
 ```
 
+## Build a filter query string from a client
 
-## HTTP Request Examples
+Encode the filter as JSON and pass it as the `filter` query param, whichever HTTP client you use:
 
 **cURL:**
 ```bash
-# Simple filter
-curl "http://localhost:3000/products?filter=%7B%22where%22%3A%7B%22status%22%3A%22active%22%7D%2C%22limit%22%3A10%7D"
-
-# Decoded filter: {"where":{"status":"active"},"limit":10}
-
-# Complex filter with URL encoding
 curl -G "http://localhost:3000/products" \
   --data-urlencode 'filter={"where":{"price":{"gte":100,"lte":500},"tags":{"contains":["featured"]}},"order":["price ASC"],"limit":20}'
 ```
 
-**JavaScript/TypeScript:**
+**Fetch/Axios:**
 ```typescript
-// Using fetch
-const filter = {
-  where: { status: 'active', price: { lte: 100 } },
-  order: ['createdAt DESC'],
-  limit: 10,
-};
-
-const response = await fetch(
-  `/api/products?filter=${encodeURIComponent(JSON.stringify(filter))}`
-);
-
-// Using axios
-const response = await axios.get('/api/products', {
-  params: { filter: JSON.stringify(filter) },
-});
+const filter = { where: { status: 'active', price: { lte: 100 } }, order: ['createdAt DESC'], limit: 10 };
+
+// fetch
+const response = await fetch(`/api/products?filter=${encodeURIComponent(JSON.stringify(filter))}`);
+
+// axios
+const response = await axios.get('/api/products', { params: { filter: JSON.stringify(filter) } });
 ```
 
+## Debug what a filter compiles to
 
-## Debugging Filters
+Call `buildQuery` to compile a filter into Drizzle query options without executing it - the fastest way to check what a filter actually resolves to:
 
 ```typescript
-// Enable logging to see generated SQL
-const result = await repository.find({
-  filter: complexFilter,
-  options: {
-    log: { use: true, level: 'debug' },
-  },
-});
-
-// Or use buildQuery to inspect without executing
 const queryOptions = repository.buildQuery({ filter: complexFilter });
 console.log('Generated query options:', queryOptions);
 ```
+
+`options.log` also traces repository calls, but only on the write path (`create`/`updateById`/`updateAll`/`deleteById`/`deleteAll`) - `find`/`findOne`/`findById`/`count` never read it. See [Advanced Repository Features -> Log option](../repositories/advanced.md#log-option) for the write-side form.
+
+## See also
+
+- [Filter System Overview](./) - the `filter` shape and every `where` operator family
+- [Default Filter](./default-filter) - `shouldSkipDefaultFilter`, and the model-level alternative to the service-layer rewrite above
+- [Use Case Gallery](./use-cases) - more filter shapes with their generated SQL
+- [Advanced Repository Features](../repositories/advanced.md) - transactions, locking, and the full `log`/`lock` options
+
+**Files:**
+
+- [`packages/kernel/src/base/controllers/factory/controller.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/kernel/src/base/controllers/factory/controller.ts) - `ControllerFactory.defineCrudController`
+- [`packages/kernel/src/base/repositories/query-schemas/index.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/kernel/src/base/repositories/query-schemas/index.ts) - `FilterSchema`, `WhereSchema`, `FilterQuerySchema`, `WhereQuerySchema`
+- [`packages/filter/src/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/filter/src/common/types.ts) - `TFilter`, `TInclusion`
+- [`packages/connectors/src/relational/core/repositories/core/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/connectors/src/relational/core/repositories/core/base.ts) - `RelationalBaseRepository.buildQuery`

package/content/references/base/filter-system/array-operators.md

@@ -23,44 +23,34 @@ Find rows where the array column contains **all** specified elements.
 // Schema: tags varchar(100)[]
 // Data: Product A has ['electronics', 'featured', 'sale']
 
-// Find products with BOTH 'electronics' AND 'featured'
 { where: { tags: { contains: ['electronics', 'featured'] } } }
 // SQL: "tags"::text[] @> ARRAY['electronics', 'featured']::text[]
-
-// Single element (can pass single value or array)
-{ where: { tags: { contains: ['featured'] } } }
-{ where: { tags: { contains: 'featured' } } }  // Also works
-// Matches: ['featured'], ['featured', 'sale'], ['a', 'featured', 'b']
 ```
 
+> [!NOTE]
+> A single value is wrapped in an array automatically: `{ contains: 'featured' }` is treated as `{ contains: ['featured'] }`.
+
 
 ## containedBy (<@)
 
 Find rows where **all** array elements are within the specified set.
 
 ```typescript
-// Find products where ALL tags are in the allowed list
 { where: { tags: { containedBy: ['sale', 'featured', 'new', 'popular'] } } }
 // SQL: "tags"::text[] <@ ARRAY['sale', 'featured', 'new', 'popular']::text[]
-
-// Product A ['featured', 'sale'] -> matches (all in list)
-// Product B ['featured', 'clearance'] -> no match ('clearance' not in list)
-// Product C [] -> matches (empty is subset of everything)
 ```
 
+> [!NOTE]
+> An empty array is a subset of every set, so `tags: []` always matches `containedBy`.
+
 
 ## overlaps (&&)
 
 Find rows where the arrays share at least one common element.
 
 ```typescript
-// Find products with 'premium' OR 'sale' tag
 { where: { tags: { overlaps: ['premium', 'sale'] } } }
 // SQL: "tags"::text[] && ARRAY['premium', 'sale']::text[]
-
-// Product A ['featured', 'sale'] -> matches (has 'sale')
-// Product B ['premium', 'luxury'] -> matches (has 'premium')
-// Product C ['new', 'featured'] -> no match (no overlap)
 ```
 
 
@@ -84,52 +74,41 @@ Find rows where the arrays share at least one common element.
 | "Must have AT LEAST ONE of these tags" | `overlaps` |
 
 
-## Empty Array Behavior
-
-| Operator | SQL Generated | Behavior |
-|----------|---------------|----------|
-| `contains: []` | `WHERE true` | Returns **ALL** rows |
-| `containedBy: []` | `WHERE "col" = '{}'` | Returns only rows with **empty arrays** |
-| `overlaps: []` | `WHERE false` | Returns **NO** rows |
-
-> [!NOTE]
-> Single values are automatically wrapped in an array: `{ contains: 'value' }` is treated as `{ contains: ['value'] }`.
-
-
 ## Type Handling
 
-**String Arrays** (`varchar[]`, `text[]`, `char[]`):
+The element type of the array column decides the cast in the generated SQL.
+
 ```typescript
+// String arrays (varchar[], text[], char[]) - both sides cast to text[]
 { where: { tags: { contains: ['a', 'b'] } } }
 // SQL: "tags"::text[] @> ARRAY['a', 'b']::text[]
-```
 
-Both the column and the array literal are cast to `text[]` for compatibility.
-
-**Numeric Arrays** (`integer[]`, `numeric[]`):
-```typescript
+// Numeric arrays (integer[], numeric[]) - no cast needed
 { where: { scores: { contains: [100, 200] } } }
 // SQL: "scores" @> ARRAY[100, 200]
-```
 
-No casting needed for numeric arrays.
-
-**Boolean Arrays**:
-```typescript
+// Boolean arrays - no cast needed
 { where: { flags: { contains: [true, false] } } }
 // SQL: "flags" @> ARRAY[true, false]
 ```
 
 
+## Empty Array Behavior
+
+| Operator | SQL generated | Behavior |
+|----------|---------------|----------|
+| `contains: []` | `WHERE true` | Returns **ALL** rows |
+| `containedBy: []` | `WHERE "col" = '{}'` | Returns only rows with **empty arrays** |
+| `overlaps: []` | `WHERE false` | Returns **NO** rows |
+
+
 ## Security: Parameterized Values
 
-Every element of `contains`/`containedBy`/`overlaps` is bound as a query parameter -- only the operator token (`@>`/`<@`/`&&`) is raw SQL. See [The Hardening Round](../../../changelogs/2026-07-13-hardening-round) for the prior injection this closed.
+Every element of `contains`/`containedBy`/`overlaps` is bound as a query parameter - only the operator token (`@>`/`<@`/`&&`) is raw SQL. See [The Hardening Round](../../../changelogs/2026-07-13-hardening-round) for the prior injection this closed.
 
 
 ## Defining Array Columns
 
-In your Drizzle schema:
-
 ```typescript
 import { pgTable, text, varchar, integer } from 'drizzle-orm/pg-core';
 
@@ -137,9 +116,20 @@ export const productTable = pgTable('Product', {
   id: text('id').primaryKey(),
   name: text('name').notNull(),
 
-  // Array columns
   tags: varchar('tags', { length: 100 }).array(),      // varchar(100)[]
   categories: text('categories').array(),              // text[]
   scores: integer('scores').array(),                   // integer[]
 });
 ```
+
+## See also
+
+- [Filter System Overview](./) - the `filter` shape and the full `where` operator table
+- [List Operators](./list-operators) - `in`/`nin` match scalar values against an array, the operators these are not to be confused with
+- [Quick Reference](./quick-reference) - every operator, one line each
+
+**Files:**
+
+- [`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`, `buildPgArrayComparison`
+- [`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/filter/src/common/operators.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/filter/src/common/operators.ts) - `QueryOperators` constants