@appweaver/cli 1.1.5 → 1.2.0

package/generate/generate-schema.js

@@ -21,6 +21,14 @@ const utils_1 = require("../utils");
 async function generateSchema(models, schemaPath, clientPath, quiet = false) {
     const cwd = process.cwd();
     try {
+        const relationErrors = validateRelations(models);
+        if (relationErrors.length > 0) {
+            for (const relationError of relationErrors) {
+                console.error(relationError);
+            }
+            console.error('Schema generation failed due to inconsistent relation definitions.');
+            return 2;
+        }
         await (0, utils_1.ensureDirExists)(node_path_1.default.join(cwd, schemaPath));
         const prismaModels = {};
         const prismaEnums = {};
@@ -80,37 +88,67 @@ async function generateSchema(models, schemaPath, clientPath, quiet = false) {
                     continue;
                 }
                 const relationConfig = modelSchema?.config.relations?.[relation.name];
+                if (!relationConfig) {
+                    // Skip auto-generated back reference fields added by other models
+                    continue;
+                }
                 const referencedName = relation.type
                     .replaceAll('[]', '')
                     .replaceAll('?', '');
                 const referencedModel = prismaModels[referencedName];
-                const mappedField = referencedModel.relations.find((r) => r.name === relationConfig?.mappedBy);
+                const mappedField = referencedModel.relations.find((r) => r.name === relationConfig.mappedBy);
                 if (mappedField?.type.startsWith('Int')) {
                     continue;
                 }
                 if (mappedField && mappedField.attributes?.length) {
-                    // Ensure that mapped fields have the same reference name
+                    // Ensure that mapped fields have the same reference name. The name of
+                    // the relation is replaced while any foreign key configuration on the
+                    // owning side is preserved.
                     const relationAttribute = mappedField.attributes[0];
                     const relationParts = relationAttribute.split('"');
                     const referenceName = relation.attributes?.[0].split('"')[1];
                     relationParts.splice(1, 1, `${referenceName}`);
-                    if (relationConfig?.unique) {
-                        mappedField.attributes[0] = `@relation("${referenceName}")`;
-                    }
-                    else {
-                        mappedField.attributes[0] = relationParts.join('"');
-                    }
+                    mappedField.attributes[0] = relationParts.join('"');
                 }
                 else {
-                    // For unmapped relations add a default relation field using the same
-                    // reference name
-                    const refName = (0, common_1.uncapitalize)((0, common_1.plural)(name));
-                    if (!referencedModel.relations.some((r) => r.name === refName)) {
-                        referencedModel.relations.push({
-                            name: (0, common_1.uncapitalize)((0, common_1.plural)(name)),
-                            type: `${name}[]`,
-                            attributes: relation.attributes
-                        });
+                    // For unmapped relations add a default back reference field matching
+                    // the relation type, using the same reference name
+                    const referenceName = relation.attributes?.[0].split('"')[1];
+                    const owner = (0, common_1.isRelationOwner)(relationConfig);
+                    if (relationConfig.type === 'manyToMany' || owner) {
+                        // Inverse of a manyToMany relation or of an owning side: for
+                        // oneToOne a single optional field, otherwise a list field
+                        const single = relationConfig.type === 'oneToOne';
+                        const refName = single
+                            ? (0, common_1.uncapitalize)(name)
+                            : (0, common_1.uncapitalize)((0, common_1.plural)(name));
+                        if (!referencedModel.relations.some((r) => r.name === refName)) {
+                            referencedModel.relations.push({
+                                name: refName,
+                                type: single ? `${name}?` : `${name}[]`,
+                                attributes: [`@relation("${referenceName}")`]
+                            });
+                        }
+                    }
+                    else {
+                        // A non-owning side declared alone: the referenced model holds the
+                        // foreign key column
+                        const refName = (0, common_1.uncapitalize)(name);
+                        const refFieldName = `${refName}Id`;
+                        if (!referencedModel.relations.some((r) => r.name === refName)) {
+                            referencedModel.relations.push({
+                                name: refName,
+                                type: `${name}?`,
+                                attributes: [
+                                    `@relation("${referenceName}", fields: [${refFieldName}], references: [id])`
+                                ]
+                            });
+                            referencedModel.relations.push({
+                                name: refFieldName,
+                                type: 'Int?',
+                                attributes: relationConfig.type === 'oneToOne' ? ['@unique'] : []
+                            });
+                        }
                     }
                 }
             }
@@ -339,6 +377,59 @@ function createScalarSchema(name, modelName, scalar) {
         attributes
     };
 }
+/**
+ * Validates the consistency of every bidirectional relation pair linked through
+ * `mappedBy`. Both sides must declare the same relation type, reference each
+ * other's model, and for `oneToOne` and `oneToMany` relations exactly one side
+ * must be the owner. Single-sided relations (where the mapped field does not
+ * exist) are left to the back reference generation and are not validated.
+ *
+ * @param {Record<string, ResourceModel>} models - All resource models keyed by name.
+ * @return {string[]} A list of human-readable error messages, empty when all
+ * relation pairs are consistent.
+ */
+function validateRelations(models) {
+    const errors = [];
+    const visited = new Set();
+    for (const [name, model] of Object.entries(models)) {
+        const relations = model.config?.relations ?? {};
+        for (const [fieldName, relation] of Object.entries(relations)) {
+            if (!relation.mappedBy) {
+                continue;
+            }
+            const mapped = models[relation.model]?.config?.relations?.[relation.mappedBy];
+            if (!mapped) {
+                continue;
+            }
+            const relationLabel = `${name}.${fieldName}`;
+            const mappedLabel = `${relation.model}.${relation.mappedBy}`;
+            // Each pair is reachable from both of its sides, so report it only once
+            const pairKey = [relationLabel, mappedLabel].sort().join('|');
+            if (visited.has(pairKey)) {
+                continue;
+            }
+            visited.add(pairKey);
+            if (mapped.model !== name) {
+                errors.push(`Relation '${relationLabel}' is mapped by '${mappedLabel}', which references model '${mapped.model}' instead of '${name}'.`);
+                continue;
+            }
+            if (mapped.type !== relation.type) {
+                errors.push(`Relation type mismatch: '${relationLabel}' is declared as '${relation.type}' but '${mappedLabel}' is declared as '${mapped.type}'.`);
+                continue;
+            }
+            if (relation.type !== 'manyToMany') {
+                const ownerCount = [relation, mapped].filter(common_1.isRelationOwner).length;
+                if (ownerCount === 0) {
+                    errors.push(`Relation owner missing: neither '${relationLabel}' nor '${mappedLabel}' declares 'owner: true' for the '${relation.type}' relation.`);
+                }
+                else if (ownerCount === 2) {
+                    errors.push(`Relation owner conflict: both '${relationLabel}' and '${mappedLabel}' declare 'owner: true' for the '${relation.type}' relation.`);
+                }
+            }
+        }
+    }
+    return errors;
+}
 function createRelationsSchema(modelName, relations = {}) {
     const fields = [];
     for (const [name, relation] of Object.entries(relations)) {
@@ -351,13 +442,20 @@ function createRelationSchema(name, modelName, relation) {
     const relationName = `${modelName}${(0, common_1.capitalize)(name)}${relation.model}`;
     const relationFieldName = `${name}Id`;
     const relationSuffix = relation.required === false ? '?' : '';
-    const type = relation.array
-        ? `${relation.model}[]`
-        : `${relation.model}${relationSuffix}`;
-    if (relation.array) {
-        attributes.push(`@relation("${relationName}")`);
+    const array = (0, common_1.isRelationArray)(relation);
+    const owner = (0, common_1.isRelationOwner)(relation);
+    let type;
+    if (array) {
+        type = `${relation.model}[]`;
+    }
+    else if (owner) {
+        type = `${relation.model}${relationSuffix}`;
     }
     else {
+        // The inverse side of a oneToOne relation must be optional in Prisma
+        type = `${relation.model}?`;
+    }
+    if (owner) {
         const referentialActions = [];
         if (relation.onDelete) {
             referentialActions.push(`onDelete: ${(0, common_1.capitalize)(relation.onDelete)}`);
@@ -368,6 +466,9 @@ function createRelationSchema(name, modelName, relation) {
         const referentialConfig = referentialActions.length > 0 ? `, ${referentialActions.join(', ')}` : '';
         attributes.push(`@relation("${relationName}", fields: [${relationFieldName}], references: [id]${referentialConfig})`);
     }
+    else {
+        attributes.push(`@relation("${relationName}")`);
+    }
     const relationFields = [
         {
             name,
@@ -375,11 +476,11 @@ function createRelationSchema(name, modelName, relation) {
             attributes
         }
     ];
-    if (!relation.array && relation.owner) {
+    if (owner) {
         relationFields.push({
             name: relationFieldName,
             type: `Int${relationSuffix}`,
-            attributes: relation.unique === true ? ['@unique'] : []
+            attributes: relation.type === 'oneToOne' ? ['@unique'] : []
         });
     }
     return relationFields;

package/generate/generate-types.js

@@ -24,23 +24,45 @@ async function generateTypes(models, typesPath, quiet = false) {
     try {
         await (0, utils_1.ensureDirExists)(node_path_1.default.join(cwd, typesPath));
         const resourceModels = {};
+        // The generated type names of every model, in the order they are emitted,
+        // so each model group can be written out followed by its own query type
+        const modelTypeNames = {};
         for (const [name, schema] of Object.entries(models)) {
             if (schema.config.generateTypes === false) {
                 continue;
             }
-            resourceModels[name] = transformUnsafeTypes(schema.readModel);
-            resourceModels[`${name}Single`] = transformUnsafeTypes(schema.readOneModel);
-            resourceModels[`${name}Multiple`] = transformUnsafeTypes(schema.readManyModel);
-            resourceModels[`${name}Create`] = transformUnsafeTypes(schema.createOneModel);
-            resourceModels[`${name}Update`] = transformUnsafeTypes(schema.updateOneModel);
+            const modelSchemas = [
+                [name, schema.readModel],
+                [`${name}Single`, schema.readOneModel],
+                [`${name}Multiple`, schema.readManyModel],
+                [`${name}Create`, schema.createOneModel],
+                [`${name}Update`, schema.updateOneModel],
+                [`${name}RelationCreate`, schema.relationCreateModel],
+                [`${name}RelationUpdate`, schema.relationUpdateModel],
+                [`${name}RelationInput`, schema.relationInputModel]
+            ];
+            for (const [typeName, typeSchema] of modelSchemas) {
+                resourceModels[typeName] = transformUnsafeTypes(typeSchema);
+            }
+            modelTypeNames[name] = modelSchemas.map(([typeName]) => typeName);
         }
         const module = typebox_1.Type.Module(resourceModels);
         const typesContent = [
             `// Generated by Appweaver. Please do not edit this file manually.`,
             ``
         ];
-        for (const name of Object.keys(resourceModels)) {
-            typesContent.push(generateTypeScriptType(module, name), ``);
+        if (Object.keys(modelTypeNames).length > 0) {
+            typesContent.push(`import { AggregateSelect, QueryFilter, QuerySort } from '@appweaver/common';`, ``);
+        }
+        for (const [name, typeNames] of Object.entries(modelTypeNames)) {
+            for (const typeName of typeNames) {
+                typesContent.push(generateTypeScriptType(module, typeName), ``);
+            }
+            typesContent.push(`export type ${name}Query = QueryFilter<${name}>;`, ``);
+            // The sort type is built from the query output model, so it only offers
+            // the relations included in a query response and their count fields
+            typesContent.push(`export type ${name}Sort = QuerySort<${name}Multiple>;`, ``);
+            typesContent.push(`export type ${name}Aggregate = AggregateSelect<${name}>;`, ``);
         }
         const outputPath = node_path_1.default.join(cwd, typesPath);
         const prettierConfig = await prettier_1.default.resolveConfig(outputPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appweaver/cli",
-  "version": "1.1.5",
+  "version": "1.2.0",
   "description": "Appweaver - the backend framework for AI-first development (@cli)",
   "author": "Luka Matosevic",
   "license": "MIT",

package/skill/GUIDELINES.md

@@ -73,7 +73,7 @@ export default createModel({
     enabled: { type: 'boolean', default: true }
   },
   relations: {
-    category: { model: 'Category', mappedBy: 'products', owner: true, output: { type: 'always' } }
+    category: { model: 'Category', type: 'oneToMany', mappedBy: 'products', owner: true, output: { type: 'always' } }
   },
   files: {
     photo: { mimeType: 'image/*', maxSize: '2 MB' }

package/skill/SKILL.md

@@ -103,6 +103,12 @@ bun weaver migration new init
 bun run seed
 ```
 
+**Install scripts:** npm 12+ blocks dependency install scripts by default. The scaffolded `package.json` ships an
+`allowScripts` field (Bun: `trustedDependencies`) covering the packages Appweaver needs to build. Without it,
+`npm install` skips the native builds and `weaver generate` fails. To approve a newly added dependency, run
+`npm install-scripts approve <pkg>`; it writes the entry to the root `package.json`. Note that a `package.json`
+`allowScripts` field makes npm ignore `.npmrc` `allow-scripts` entirely.
+
 ### Creating and starting the application server
 
 The main entrypoint to the application. This function creates an application object and initializes all resources and
@@ -203,6 +209,7 @@ export default createModel({
   relations: {
     category: {
       model: 'Category',
+      type: 'oneToMany',
       mappedBy: 'products',
       owner: true,
       output: {
@@ -355,6 +362,84 @@ export default createAuthService({
 });
 ```
 
+#### Querying resources with filters
+
+The `filter` argument of the `query`, `aggregate`, and `export` service methods (and of the matching `POST /query`,
+`POST /aggregate`, `POST /export` routes) mirrors the WHERE part of a database query. It combines `_`-prefixed operators
+with plain value shorthands and nests through relations:
+
+- **Logical**: `_and`, `_or`, `_not`, `_nor` — take a filter object (each entry becomes one condition) or a list of
+  filter objects.
+- **Comparison**: `_eq`, `_ne`, `_gt`, `_gte`, `_lt`, `_lte`, `_in`, `_nin`, `_between`, `_like`, `_ilike`, `_starts`,
+  `_ends`, `_contains`, `_exists`, `_not`. Operators combined in one object must all match.
+- **List fields**: `_has`, `_hasSome`, `_hasEvery`, `_isEmpty`.
+- **Relations**: `_some`, `_every`, `_none` for list relations, `_exists` for any relation.
+- **Shorthands**: a bare value matches by equality, a list by inclusion, a two-value list on a numeric or date field as
+  an inclusive range, and a bare value or list on a relation matches by id.
+
+```ts
+import { injectService } from '@appweaver/core';
+import { UserQuery } from '@/types/generated';
+
+const filter: UserQuery = {
+  _and: {
+    firstName: { _eq: 'John', _exists: true },
+    avatar: { _or: { title: { _eq: 'Avatar' }, description: { _like: '%avatar%' } } }
+  },
+  _or: [{ firstName: { _like: 'Jo%' } }, { lastName: 'Doe' }],
+  roles: { _some: { name: { _contains: 'Admin' } } }
+};
+
+const users = await injectService('User').query(filter, 1, 50, '-createdAt,id');
+```
+
+Filters are typed by `QueryFilter<T>` from `@appweaver/common`, and `weaver generate` emits a
+`<Model>Query = QueryFilter<Model>` alias per model. Over HTTP, they are validated against a generated per-model
+`<Model>QueryFilter` JSON schema, which strips unknown and hidden fields.
+
+### Sorting
+
+The `sort` argument of `query` and `export`, and the `sort` property of the `POST /query` and `POST /export` bodies,
+accept either a comma-separated field list, where a `-` prefix sorts descending, or an object of `asc` and `desc` field
+directions. Both sort by a field of an included to-one relation and by the record count of a to-many relation:
+
+```ts
+await injectService('Post').query({}, 1, 50, '-author.createdAt,tagsCount,id');
+await injectService('Post').query({}, 1, 50, {
+  author: { createdAt: 'desc' },
+  tagsCount: 'asc',
+  id: 'asc'
+});
+```
+
+A hidden, virtual, or array scalar field, a field of a to-many relation, or a relation the action does not include is
+rejected with a `400` error. Sort inputs are typed by `QuerySort<T>` from `@appweaver/common`, with a `<Model>Sort`
+alias emitted per model, and validated over HTTP against a generated `<Model>QuerySort` JSON schema. The default is
+`-createdAt,id`. See [resources.md](./references/resources.md) for the full rules.
+
+### Aggregating
+
+The required `select` argument of `aggregate` (and of the `POST /aggregate` body) holds the operators to apply per
+field. Only the numeric fields (`count`, `sum`, `avg`, `min`, `max`, `first`, `last`), the date fields (all but `sum`
+and `avg`), and the numeric `id` and audit fields of the model can be aggregated:
+
+```ts
+await injectService('Post').aggregate({}, {
+  counter: { count: true, sum: true, avg: true, first: true, last: true },
+  publishedAt: { min: true, max: true }
+}, 'createdAt', '2026-01-01T00:00:00.000Z', '2026-01-08T00:00:00.000Z');
+```
+
+`first` and `last` take the value held by the earliest and the latest record of a period, ordered by the aggregated
+`dateField` (ties broken by `id`). The database cannot aggregate them, so each period requesting them costs up to two
+additional queries, skipped for the periods holding no record.
+
+Any other field (string, boolean, enum, JSON, array, hidden, virtual, or a relation), an operator its type does not
+support, an empty selection, or a `dateField` that is not a date field is rejected with a `400` error. Selections are
+typed by `AggregateSelect<T>` from `@appweaver/common`, with a `<Model>Aggregate` alias emitted per model, and
+validated over HTTP against a generated `<Model>AggregateSelect` JSON schema. The response stays untyped JSON, since
+its shape follows the selection.
+
 ### Registering a custom route
 
 Use `registerRoute` to register a custom [Fastify route](https://fastify.dev/docs/latest/Reference/Routes/) handler. The
@@ -572,6 +657,27 @@ npm run e2e   # e2e tests
 Test files must use the **`.test.ts`** extension. Place unit tests in `test/unit/` and end-to-end tests in `test/e2e/`,
 naming each file after its module. Add or update tests whenever a feature is added or existing behaviour changes.
 
+The e2e setup and teardown are wired automatically, but **each e2e test file must register the per-file database reset
+itself**, after the hook that stops the application:
+
+```ts
+import { resetTestData } from './support/reset';
+
+describe('My e2e test', () => {
+  let app: Application;
+
+  beforeAll(async () => {
+    app = await createApp({ autoStartServer: false });
+  });
+
+  afterAll(async () => {
+    await app.stop();
+  });
+
+  afterAll(resetTestData, 10_000);
+});
+```
+
 ### Format code
 
 ```sh

package/skill/references/client.md

@@ -49,9 +49,9 @@ Reads an OpenAPI v3 schema and generates TypeScript types and a typed client cla
 
 **Arguments:**
 
-| Argument       | Description                                                                                                                          |
-|----------------|--------------------------------------------------------------------------------------------------------------------------------------|
-| `<schemaPath>` | Path to the OpenAPI schema. Accepts a file path or URL (`http://`, `https://`, `file://`). JSON and YAML formats are both supported. |
+| Argument       | Description                                                                                                                                                                                                                |
+|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `<schemaPath>` | Path to the OpenAPI schema. Accepts a relative or absolute file path (including a Windows drive path such as `C:\api\openapi.json`) or a URL (`http://`, `https://`, `file://`). JSON and YAML formats are both supported. |
 
 **Options:**
 
@@ -313,15 +313,20 @@ Exposes CRUD and file operations for a single resource endpoint.
 // Find a single record
 const post = await client.post.find(1);
 
-// Query with filters and pagination
+// Query with filters, sorting and pagination. The sort accepts a comma-separated
+// field list ('-createdAt,id') or an object of field directions
 const result = await client.post.query({
   filter: { published: true },
-  sort: [{ field: 'createdAt', direction: 'desc' }],
-  page: { offset: 0, limit: 20 }
+  sort: { author: { lastName: 'asc' }, createdAt: 'desc' },
+  page: 1,
+  size: 20
 });
 
-// Aggregate
-const stats = await client.post.aggregate({ count: true });
+// Aggregate. The select holds the operators to apply per numeric or date field
+const stats = await client.post.aggregate({
+  select: { counter: { count: true, sum: true }, createdAt: { min: true } },
+  dateField: 'createdAt'
+});
 
 // Create
 const newPost = await client.post.create({ title: 'Hello', body: '...' });

package/skill/references/resources.md

@@ -248,6 +248,7 @@ const config = {
   relations: {
     category: {
       model: 'Category',
+      type: 'oneToMany',
       mappedBy: 'products',
       owner: true,
       output: {
@@ -256,8 +257,8 @@ const config = {
     },
     reviews: {
       model: 'Review',
+      type: 'oneToMany',
       mappedBy: 'product',
-      array: true,
       output: {
         type: 'single',
         count: true
@@ -273,8 +274,8 @@ const config = {
   relations: {
     products: {
       model: 'Product',
+      type: 'oneToMany',
       mappedBy: 'category',
-      array: true,
       output: {
         type: 'single'
       }
@@ -289,6 +290,7 @@ const config = {
   relations: {
     product: {
       model: 'Product',
+      type: 'oneToMany',
       mappedBy: 'reviews',
       owner: true,
       input: {
@@ -299,30 +301,29 @@ const config = {
 };
 ```
 
-| Property            | Type              | Default      | Description                                                              |
-|---------------------|-------------------|--------------|--------------------------------------------------------------------------|
-| `model`             | string            | **required** | Target model name.                                                       |
-| `owner`             | boolean           | `false`      | This side owns the foreign key (only one side should be owner).          |
-| `mappedBy`          | string            | -            | Name of the inverse relation on the target model.                        |
-| `array`             | boolean           | `false`      | One-to-many value or many-to-many relation.                              |
-| `unique`            | boolean           | `false`      | One-to-one relation (unique foreign key).                                |
-| `required`          | boolean           | `true`       | Whether the relation is required (nullable foreign key if not required). |
-| `minItems`          | number            | -            | Minimum items for array relations.                                       |
-| `createIfNotExists` | boolean           | `false`      | Auto-create related record if it doesn't exist.                          |
-| `orphanRemoval`     | boolean           | `false`      | Delete orphaned records when parent is deleted.                          |
-| `onDelete`          | ReferentialAction | -            | Foreign key action on delete.                                            |
-| `onUpdate`          | ReferentialAction | -            | Foreign key action on update.                                            |
-| `input`             | RelationInput     | -            | Input DTO configuration.                                                 |
-| `output`            | RelationOutput    | -            | Output DTO configuration.                                                |
+| Property        | Type                                            | Default      | Description                                                              |
+|-----------------|-------------------------------------------------|--------------|--------------------------------------------------------------------------|
+| `model`         | string                                          | **required** | Target model name.                                                       |
+| `type`          | `'oneToOne'` \| `'oneToMany'` \| `'manyToMany'` | **required** | Relation cardinality between the two models.                             |
+| `owner`         | boolean                                         | `false`      | This side owns the foreign key column (only one side should be owner).   |
+| `mappedBy`      | string                                          | -            | Name of the inverse relation on the target model.                        |
+| `required`      | boolean                                         | `true`       | Whether the relation is required (nullable foreign key if not required). |
+| `minItems`      | number                                          | -            | Minimum items for list relations.                                        |
+| `orphanRemoval` | boolean                                         | `false`      | Delete orphaned records when parent is deleted.                          |
+| `onDelete`      | ReferentialAction                               | -            | Foreign key action on delete.                                            |
+| `onUpdate`      | ReferentialAction                               | -            | Foreign key action on update.                                            |
+| `input`         | RelationInput                                   | -            | Input DTO configuration.                                                 |
+| `output`        | RelationOutput                                  | -            | Output DTO configuration.                                                |
 
 **ReferentialAction values**: `'cascade'`, `'restrict'`, `'noAction'`, `'setNull'`, `'setDefault'`
 
 #### Relationship types
 
-The combination of `owner`, `array`, and `unique` properties determines the relationship type:
+The `type` property declares the relation cardinality explicitly, and `owner` marks the side that holds the foreign key
+column in the generated table:
 
-**One-to-One**: One side has `owner: true` and `unique: true`, the other side has `owner: false` (default) and
-`unique: false` (default).
+**One-to-One** (`type: 'oneToOne'`): Both sides reference a single record. The side with `owner: true` holds a unique
+foreign key; the inverse side is always optional.
 
 ```ts
 // User model
@@ -330,9 +331,9 @@ const config = {
   relations: {
     profile: {
       model: 'Profile',
+      type: 'oneToOne',
       mappedBy: 'user',
       owner: true,
-      unique: true,
       required: false // otherwise the Profile DTO must be sent when creating the user resource
     }
   }
@@ -345,34 +346,36 @@ const config = {
   relations: {
     user: {
       model: 'User',
+      type: 'oneToOne',
       mappedBy: 'profile'
     }
   }
 };
 ```
 
-**One-to-Many**: The "one" side has `owner: false` (default) and `array: true`, the "many" side has `owner: true` and
-`array: false` (default).
+**One-to-Many** (`type: 'oneToMany'`): The "many" side (which holds the foreign key) has `owner: true` and references a
+single record; the "one" side has no `owner` and holds a list of related records.
 
 ```ts
-// Category model (one)
+// Category model (one, list side)
 const config = {
   relations: {
     products: {
       model: 'Product',
-      mappedBy: 'category',
-      array: true
+      type: 'oneToMany',
+      mappedBy: 'category'
     }
   }
 };
 ```
 
 ```ts
-// Product model (many)
+// Product model (many, foreign key side)
 const config = {
   relations: {
     category: {
       model: 'Category',
+      type: 'oneToMany',
       mappedBy: 'products',
       owner: true
     }
@@ -380,8 +383,8 @@ const config = {
 };
 ```
 
-**Many-to-Many**: Both sides have `array: true`. Only one side should have `owner: true` (determines which creates the
-join table).
+**Many-to-Many** (`type: 'manyToMany'`): Both sides hold lists of related records, joined through an implicit join
+table. The `owner` property has no effect on this relation type.
 
 ```ts
 // Post model
@@ -389,9 +392,8 @@ const config = {
   relations: {
     tags: {
       model: 'Tag',
-      mappedBy: 'posts',
-      owner: true,
-      array: true
+      type: 'manyToMany',
+      mappedBy: 'posts'
     }
   }
 };
@@ -403,20 +405,69 @@ const config = {
   relations: {
     posts: {
       model: 'Post',
-      mappedBy: 'tags',
-      array: true
+      type: 'manyToMany',
+      mappedBy: 'tags'
     }
   }
 };
 ```
 
+#### Relation pair validation
+
+`weaver generate` validates every bidirectional relation pair linked through `mappedBy` and fails schema generation with
+a descriptive error when the two sides are inconsistent:
+
+- Both sides must declare the same relation `type`.
+- The mapped relation must reference the declaring model back via its `model` property.
+- For `oneToOne` and `oneToMany` relations, exactly one side must declare `owner: true` (neither or both is an error).
+
+A relation whose `mappedBy` field does not exist on the target model is treated as single-sided and skipped by the
+validation; an inverse field is generated automatically in the Prisma schema.
+
 #### Relation input
 
-| Property    | Type                                            | Description                                       |
-|-------------|-------------------------------------------------|---------------------------------------------------|
-| `type`      | `'all'` \| `'create'` \| `'update'` \| `'none'` | When the relation field is available as input.    |
-| `uniqueKey` | string                                          | Use a unique key field instead of ID for linking. |
-| `fullModel` | boolean                                         | Accept full nested model object as input.         |
+| Property      | Type                                            | Description                                                                                           |
+|---------------|-------------------------------------------------|-------------------------------------------------------------------------------------------------------|
+| `type`        | `'all'` \| `'create'` \| `'update'` \| `'none'` | When the relation field is available as input.                                                        |
+| `allowCreate` | boolean                                         | Allow creating related records inline (input objects without an `id`).                                |
+| `allowUpdate` | boolean                                         | Allow updating related records inline on parent update requests (input objects with a required `id`). |
+| `uniqueKey`   | string                                          | Unique field matching existing records, turning an inline create into a connect-or-create.            |
+
+Both flags are off by default: a relation only connects existing records unless `allowCreate` / `allowUpdate` is set.
+
+By default, a relation input only connects existing records. It accepts an id value, an `{ id }` object, or an array of
+either for list relations. The `allowCreate` and `allowUpdate` flags also accept the related model's own data:
+
+- **`allowCreate: true`** — input objects **without** an `id` create the related record inline. The accepted fields are
+  the related model's create data, without its own relations and files (`<Model>RelationCreate`).
+- **`allowUpdate: true`** — input objects **with** an `id` and further fields update the related record inline
+  (`<Model>RelationUpdate`). Objects carrying only an `id` are connected instead. This applies to parent **update**
+  requests only. On parent **create** requests every object with an `id` is connected, since the database updates
+  relations only within an update action.
+
+Relations that accept inline writes document their request shape as `<Model>RelationInput`. It holds the id and the
+fields of both shapes above, all optional. The shape stays permissive on purpose, since the server strips the properties
+that the matched schema does not declare. The service applies the restrictions instead. Fields excluded by the related
+model's `create` or `update` config are dropped. A missing required create field fails with a `400` error naming the
+field.
+
+Connect, create, and update inputs can be mixed within one list relation request:
+
+```ts
+// PUT /api/users/1
+{
+  posts: [
+    5,                                    // connect post 5 by id
+    { id: 7, title: 'Renamed' },          // update post 7 inline
+    { title: 'Fresh post', slug: 'new' }  // create a new post inline
+  ]
+}
+```
+
+Records without an `id` require `allowCreate: true`. Otherwise, the request fails with a `400` error and the related
+record has to be created through its own endpoint first. With `allowCreate` set, a `uniqueKey` matches an existing
+record by that field before creating a new one, so the inline create becomes a connect-or-create. Without
+`allowCreate` the `uniqueKey` has no effect. Plain connect and inline update always match related records by `id`.
 
 #### Relation output
 
@@ -632,6 +683,11 @@ const config = {
 | `exclude`    | boolean            | Exclude this field from exports.   |
 | `mapValue`   | string \| function | Transform the value during export. |
 
+A `string` `mapValue` names the field to read the column value from. On a relation or file field it is read off the
+related record (and off every item for array relations, joined with `,`); on a scalar field it is read off the exported
+record itself. A function `mapValue` receives the field value (or each item of an array field) and returns the column
+value.
+
 ### Index config
 
 Define database indexes as a flat array (single-field indexes) or nested arrays (composite indexes):
@@ -693,7 +749,7 @@ function createService(config: ResourceServiceConfig, override ?: Partial<Resour
 |-------------------|--------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
 | `modelName`       | string                                                                   | Model name to bind this service to (required).                                                                                  |
 | `beforeFind`      | `(id) => void`                                                           | Hook called before finding a single resource.                                                                                   |
-| `beforeQuery`     | `(filter, page, size, sort) => void`                                     | Hook called before querying resources.                                                                                          |
+| `beforeQuery`     | `(filter, page, size, sort) => void`                                     | Hook called before querying resources. `sort` is a field list string or a sort object.                                          |
 | `beforeAggregate` | `(filter, select, dateField, from?, to?, step?, safeIncrement?) => void` | Hook called before aggregation.                                                                                                 |
 | `beforeCreate`    | `(data) => void`                                                         | Hook called before creating a resource. Mutate `data` to modify input.                                                          |
 | `beforeUpdate`    | `(id, data) => void`                                                     | Hook called before updating a resource.                                                                                         |
@@ -712,14 +768,167 @@ All hooks can be synchronous or return a `Promise`.
 
 The created service exposes the following methods:
 
-| Method      | Signature                                                                                         | Description                                              |
-|-------------|---------------------------------------------------------------------------------------------------|----------------------------------------------------------|
-| `find`      | `(id) => Promise<ReadOne>`                                                                        | Find a single resource by ID.                            |
-| `query`     | `(filter?, page?, size?, sort?) => Promise<QueryResponse>`                                        | Query resources with filtering, pagination, and sorting. |
-| `aggregate` | `(filter?, select?, dateField?, from?, to?, step?, safeIncrement?) => Promise<AggregateResponse>` | Aggregate resources with time-series grouping.           |
-| `create`    | `(data) => Promise<ReadOne>`                                                                      | Create a new resource.                                   |
-| `update`    | `(id, data) => Promise<ReadOne>`                                                                  | Update an existing resource.                             |
-| `delete`    | `(id) => Promise<ReadOne>`                                                                        | Delete a resource.                                       |
+| Method      | Signature                                                                                         | Description                                                                                      |
+|-------------|---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|
+| `find`      | `(id) => Promise<ReadOne>`                                                                        | Find a single resource by ID.                                                                    |
+| `query`     | `(filter?, page?, size?, sort?) => Promise<QueryResponse>`                                        | Query resources with filtering, pagination, and sorting (see [Query sorting](#query-sorting)).   |
+| `aggregate` | `(filter?, select?, dateField?, from?, to?, step?, safeIncrement?) => Promise<AggregateResponse>` | Aggregate resources with time-series grouping (see [Aggregate selection](#aggregate-selection)). |
+| `create`    | `(data) => Promise<ReadOne>`                                                                      | Create a new resource.                                                                           |
+| `update`    | `(id, data) => Promise<ReadOne>`                                                                  | Update an existing resource.                                                                     |
+| `delete`    | `(id) => Promise<ReadOne>`                                                                        | Delete a resource.                                                                               |
+
+### Query filters
+
+The `filter` argument of `query`, `aggregate`, and `export` mirrors the WHERE part of a database query. The matching
+`POST /query`, `POST /aggregate`, and `POST /export` routes accept the same structure, validated against a generated
+per-model `<Model>QueryFilter` schema that strips unknown and hidden fields.
+
+**Logical operators** (filter level) — take a single filter object (each entry becomes one condition) or a list of them:
+
+| Operator | Description                               |
+|----------|-------------------------------------------|
+| `_and`   | All nested conditions must match.         |
+| `_or`    | At least one nested condition must match. |
+| `_not`   | No nested condition may match.            |
+| `_nor`   | Alias of `_not`.                          |
+
+**Comparison operators** (field level) — combined inside one object, all must match:
+
+| Operator                        | Description                                                                                                                  |
+|---------------------------------|------------------------------------------------------------------------------------------------------------------------------|
+| `_eq`                           | Equal to the given value.                                                                                                    |
+| `_ne`                           | Not equal to the given value.                                                                                                |
+| `_gt`, `_gte`, `_lt`, `_lte`    | Greater/lower than (or equal to) the given value.                                                                            |
+| `_in`, `_nin`                   | Included / not included in the given list.                                                                                   |
+| `_between`                      | Inside the inclusive `[min, max]` range.                                                                                     |
+| `_like`                         | SQL LIKE pattern with `%` wildcards (`Luk%` → starts with, `%avatar%` → contains, `%png` → ends with, no wildcard → equals). |
+| `_ilike`                        | Case-insensitive `_like` (uses `mode: 'insensitive'`, PostgreSQL and MongoDB only).                                          |
+| `_starts`, `_ends`, `_contains` | Starts with / ends with / contains the given string.                                                                         |
+| `_exists`                       | Not null (`true`) or null (`false`).                                                                                         |
+| `_not`                          | Negates a nested operator object or plain value.                                                                             |
+
+**List (array scalar) operators**: `_has`, `_hasSome`, `_hasEvery`, `_isEmpty`.
+
+**Relation operators**: `_some`, `_every`, `_none` take a filter of the related model; `_exists` maps to an `is`/`isNot`
+null check on a single relation and to `some`/`none` on a list relation.
+
+**Plain value shorthands**: a bare value matches by equality, a list by inclusion, a two-value list on a numeric or date
+field as an inclusive range, a value or list on a relation by id, an array field uses `has`/`hasSome`, and `null`
+matches missing values or related records.
+
+```json
+{
+  "filter": {
+    "_and": {
+      "firstName": {
+        "_eq": "Luka",
+        "_exists": true
+      },
+      "avatar": {
+        "_or": {
+          "title": {
+            "_eq": "New user avatar"
+          },
+          "description": {
+            "_like": "%avatar%"
+          }
+        },
+        "originalName": {
+          "_eq": "new_user_avatar.png"
+        }
+      }
+    },
+    "_or": [
+      {
+        "firstName": {
+          "_like": "Luk%"
+        }
+      },
+      {
+        "lastName": "Matošević"
+      }
+    ],
+    "tags": {
+      "_some": {
+        "name": {
+          "_contains": "news"
+        }
+      }
+    }
+  },
+  "page": 1,
+  "size": 50,
+  "sort": "-createdAt,id"
+}
+```
+
+The `QueryFilter<T>` type from `@appweaver/common` provides code completion, and `weaver generate` emits a
+`<Model>Query = QueryFilter<Model>` alias per model:
+
+```ts
+import { QueryFilter } from '@appweaver/common';
+import { User, UserQuery } from '@/types/generated';
+
+const filter: UserQuery = {
+  _and: {
+    firstName: { _eq: 'Luka' },
+    loginAt: { _exists: true }
+  }
+};
+const users = await userService.query(filter);
+```
+
+### Query sorting
+
+The `sort` argument of `query` and `export` (and the `sort` property of the `POST /query` and `POST /export` request
+bodies) accepts two interchangeable forms, both applying their fields in the declared order:
+
+```json
+{
+  "sort": "-author.createdAt,tagsCount,id"
+}
+```
+
+```json
+{
+  "sort": {
+    "author": {
+      "createdAt": "desc"
+    },
+    "tagsCount": "asc",
+    "id": "asc"
+  }
+}
+```
+
+In the string form a `-` prefix sorts descending (`+` or no prefix ascending) and a dot notation path targets a relation
+field. In the object form a relation takes a nested object, and the only accepted directions are the lower case `asc`
+and `desc`.
+
+| Field                  | String form         | Object form                         | Notes                                                                                  |
+|------------------------|---------------------|-------------------------------------|----------------------------------------------------------------------------------------|
+| Scalar, `id`, audit    | `title`, `-id`      | `{ title: 'asc' }`                  | Hidden scalars, array scalars, and virtual fields cannot be sorted by.                 |
+| To-one relation field  | `-author.createdAt` | `{ author: { createdAt: 'desc' } }` | The relation must be included in the response of the action, at any nesting depth.     |
+| To-many relation count | `-tagsCount`        | `{ tagsCount: 'desc' }`             | Sorts by the number of related records; the relation name alone (`-tags`) is an alias. |
+
+Anything else — a relation the action does not include, a field of a to-many relation, a hidden or virtual field, an
+unknown sort direction — is rejected with a `400` error naming the offending field instead of reaching the database.
+Over HTTP the sort object is additionally validated against a generated per-model `<Model>QuerySort` schema, which
+strips unknown fields the same way the query filter schema does.
+
+The default sort is `-createdAt,id`, and its `createdAt` part is dropped for models configured with
+`audit: { createdAt: false }`.
+
+Sort inputs are typed by `QuerySort<T>` from `@appweaver/common`, and `weaver generate` emits a
+`<Model>Sort = QuerySort<<Model>Multiple>` alias per model, built from the query output model so it only offers the
+relations a query response includes:
+
+```ts
+import { PostSort } from '@/types/generated';
+
+const sort: PostSort = { author: { lastName: 'asc' }, createdAt: 'desc' };
+const posts = await postService.query({}, 1, 50, sort);
+```
 
 ### Query response
 
@@ -731,28 +940,80 @@ const config = {
 };
 ```
 
+### Aggregate selection
+
+The `select` argument of `aggregate` (and the required `select` property of the `POST /aggregate` request body) holds
+the operators to apply per field. Only the fields the database can aggregate are accepted, which are the numeric and
+date scalars of the model together with its numeric `id` and audit fields:
+
+| Field kind                         | Operators                                            |
+|------------------------------------|------------------------------------------------------|
+| Numeric (`int`, `bigInt`, `float`) | `count`, `sum`, `avg`, `min`, `max`, `first`, `last` |
+| Date (`dateTime`)                  | `count`, `min`, `max`, `first`, `last`               |
+
+```json
+{
+  "select": {
+    "counter": {
+      "count": true,
+      "sum": true,
+      "avg": true,
+      "first": true,
+      "last": true
+    },
+    "publishedAt": {
+      "min": true,
+      "max": true
+    }
+  },
+  "dateField": "createdAt",
+  "from": "2026-01-01T00:00:00.000Z",
+  "to": "2026-01-08T00:00:00.000Z"
+}
+```
+
+**`first` and `last`** take the value held by the earliest and the latest record of a period, ordered by the aggregated
+`dateField` (ties broken by `id`), or `null` for a period holding no record. The database cannot aggregate them, so each
+non-empty period requesting them costs up to two extra queries.
+
+Any other field, an operator its field kind does not support, and an empty selection are rejected with a `400` error.
+Over HTTP the selection is also validated against a generated per-model `<Model>AggregateSelect` schema. The `dateField`
+must be a date field of the model (`createdAt` by default).
+
+Selections are typed by `AggregateSelect<T>` from `@appweaver/common`, with a `<Model>Aggregate` alias emitted per
+model:
+
+```ts
+import { PostAggregate } from '@/types/generated';
+
+const select: PostAggregate = { counter: { sum: true }, createdAt: { max: true } };
+const stats = await postService.aggregate({}, select);
+```
+
 ### Aggregate response
 
+The response is untyped JSON, since its shape follows whatever was selected. Each aggregated field holds one property
+per operator applied to it:
+
 ```ts
 const resp = {
-  total: AggregateValue,         // Overall aggregation
-  items: Arrray<AggregateResult> // Per-period results
+  total: AggregateValue,        // Overall aggregation
+  items: Array<AggregateResult> // Per-period results
 };
 
 // Each AggregateResult:
 const result = {
   date: 'Date',
   result: {
-    [field]:
-      {
-        count: 123,
-        min: 123,
-        max: 123,
-        avg: 123,
-        sum: 123,
-        first: 123,
-        last: 123
-      }
+    [field]: {
+      count: 123,
+      min: 123,   // an ISO date string for a date field
+      max: 123,   // an ISO date string for a date field
+      avg: 123,   // numeric fields only
+      sum: 123,   // numeric fields only
+      first: 123, // value of the earliest record of the period
+      last: 123   // value of the latest record of the period
+    }
   }
 };
 ```

package/skill/references/security.md

@@ -64,7 +64,7 @@ if `SECURITY_JWT_SECRET` is set.
 
 | Scope     | Purpose               | Access                                                                 |
 |-----------|-----------------------|------------------------------------------------------------------------|
-| `Auth`    | Full API access       | All routes except `/refresh`, `/2fa-send-code`, `/verify-2fa-code`     |
+| `Auth`    | Full API access       | All routes except `/refresh`, `/send-2fa-code`, `/verify-2fa-code`     |
 | `Refresh` | Token renewal only    | Only `POST /auth/refresh`                                              |
 | `TwoFA`   | 2FA verification only | Only `POST /account/send-2fa-code` and `POST /account/verify-2fa-code` |