@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

package/dist/templates/backend/application/.claude/skills/catalyst-cross-bounded-context-ports/SKILL.md

@@ -397,7 +397,7 @@ Mock the port directly with an object literal — **much simpler** than mocking
 ```ts
 beforeEach(async () => {
   const clientReader = {
-    findByIdWithApplications: jest
+    findByIdWithApplications: vi
       .fn()
       .mockResolvedValue({ id: CLIENT_ID, applicationCodes: ['APP_A'] }),
   };

package/dist/templates/backend/application/.claude/skills/catalyst-field-schema/SKILL.md

@@ -135,14 +135,19 @@ Does the handler RECEIVE a payload?
         │
         └── Does the handler RETURN the entity?
               │
-              ├── Yes → @ApplySchema(schema)   (create, update-by-id, delete with return)
+              ├── Yes → @ApplySchema({ schema, operation })   (create, update-by-id, delete with return)
               │
-              └── No  → @Sanitize(schema)       (write-only flows, no entity in response)
+              └── No  → @Sanitize({ schema, operation })       (write-only flows, no entity in response)
 ```
 
-Non-zero-index payload? Use the object form: `@ApplySchema({ schema, payloadIndex: N })` or
-`@Sanitize({ schema, payloadIndex: N })` (`@Format` has no payloadIndex — it operates on the return
-value).
+`@ApplySchema` and `@Sanitize` accept ONLY the options-object form; the bare `@ApplySchema(schema)`
+/ `@Sanitize(schema)` array form no longer compiles. `operation: 'create' | 'update'` is REQUIRED —
+it gates whether a `createOnly` key present in the payload gets rejected. Declare `'update'`
+whenever the write can reach a row that already exists (update-by-id, bulk update, upsert, and any
+hand-written handler that updates or upserts an existing row); declare `'create'` only when the
+write can only ever insert a new row. Non-zero-index payload? Add `payloadIndex: N` to the same
+object: `@ApplySchema({ schema, operation, payloadIndex: N })` (`@Format` has no `payloadIndex` or
+`operation` — it operates on the return value and knows no write operations).
 
 ## Anti-patterns
 
@@ -176,8 +181,8 @@ value).
    already does it.
 
 6. **Calling `formatRecord` or `sanitizeRecord` directly instead of via a decorator.** → The
-   decorator wires `handlerMeta.timezone`, `meta.contentLanguage`, and other options automatically.
-   A direct call loses that context and produces inconsistent output. No exceptions remain — the
+   decorator resolves the options from `handlerMeta` and picks the direction for you. A direct
+   call duplicates that wiring and drifts away from it. No exceptions remain — the
    pre-1.1.0 "manual format on included relation" workaround is obsolete (see anti-pattern #3).
 
 ## Naming Conventions

package/dist/templates/backend/application/.claude/skills/catalyst-field-schema/references/field-schema-and-decorators.md

@@ -44,9 +44,9 @@ import { FieldSchema } from '@aurorajs.dev/core-back';
 export const IamTagFieldSchema: FieldSchema[] = [
   { name: 'id', type: 'id', nullable: false, maxLength: 36 },
   { name: 'name', type: 'varchar', nullable: false, maxLength: 64, rules: { minLength: 1 } },
-  { name: 'createdAt', type: 'timestamp', nullable: true },
-  { name: 'updatedAt', type: 'timestamp', nullable: true },
-  { name: 'deletedAt', type: 'timestamp', nullable: true },
+  { name: 'createdAt', type: 'dateTime', nullable: true },
+  { name: 'updatedAt', type: 'dateTime', nullable: true },
+  { name: 'deletedAt', type: 'dateTime', nullable: true },
 ];
 ```
 
@@ -67,7 +67,7 @@ export const IamAccountFieldSchema: FieldSchema[] = [
   { name: 'tags', type: 'array', nullable: true },
   { name: 'dPermissions', type: 'jsonb', nullable: false },
   { name: 'meta', type: 'jsonb', nullable: true },
-  { name: 'createdAt', type: 'timestamp', nullable: true },
+  { name: 'createdAt', type: 'dateTime', nullable: true },
   // … plus surname, deletedAt, etc.
 ];
 ```
@@ -98,31 +98,29 @@ interface TypeHandler {
 
 - **`validate`** throws if the value violates the schema (type mismatch, maxLength overflow, enum
   membership failure, `rules.minLength` violation). Runs before persist.
-- **`sanitize`** transforms the value going in (e.g., trim strings, remove timezone from timestamps,
-  bcrypt-hash passwords).
-- **`format`** transforms the value coming out (e.g., add timezone to timestamps, mask sensitive
-  data).
+- **`sanitize`** transforms the value going in (e.g., trim strings, bcrypt-hash passwords).
+- **`format`** transforms the value coming out (e.g., mask sensitive data).
 
 The 16 handlers in catalyst today:
 
-| Type        | Behavior highlights                                                                  |
-| ----------- | ------------------------------------------------------------------------------------ |
-| `id`        | UUID v4; `maxLength: 36`.                                                            |
-| `varchar`   | String; validates `maxLength` and `rules.minLength`.                                 |
-| `text`      | Unbounded string; validates `rules.minLength`.                                       |
-| `char`      | Fixed-length string; validates exact length from `maxLength`.                        |
-| `password`  | See spotlight below.                                                                 |
-| `enum`      | Validates membership in `enumOptions`. Never null unless `nullable: true`.           |
-| `boolean`   | Validates it is `true` / `false`.                                                    |
-| `timestamp` | ISO 8601; `sanitize` strips timezone, `format` applies `handlerMeta.timezone`.       |
-| `date`      | Calendar date without time; format respects `handlerMeta.timezone`.                  |
-| `array`     | JS array; no per-element validation unless `rules` declares one.                     |
-| `jsonb`     | Arbitrary JSON, stored as `jsonb` in Postgres. No schema validation inside.          |
-| `json`      | Arbitrary JSON stored as `json`. Same semantics as `jsonb` from the handler.         |
-| `bigint`    | Arbitrary-precision integer as string. Range-validated.                              |
-| `smallint`  | 16-bit signed integer (-32768..32767). Validates range.                              |
-| `int`       | 32-bit signed integer. Validates range.                                              |
-| `decimal`   | Fixed-precision decimal; `decimals: [total, scale]` (e.g., `[10, 2]` = 99999999.99). |
+| Type        | Behavior highlights                                                                                                                                  |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`        | UUID v4; `maxLength: 36`.                                                                                                                            |
+| `varchar`   | String; validates `maxLength` and `rules.minLength`.                                                                                                 |
+| `text`      | Unbounded string; validates `rules.minLength`.                                                                                                       |
+| `char`      | Fixed-length string; validates exact length from `maxLength`.                                                                                        |
+| `password`  | See spotlight below.                                                                                                                                 |
+| `enum`      | Validates membership in `enumOptions`. Never null unless `nullable: true`.                                                                           |
+| `boolean`   | Validates it is `true` / `false`.                                                                                                                    |
+| `timestamp` | Numeric Unix epoch in a `bigint` column; rejects anything but a safe integer. No `sanitize`, no `format`.                                            |
+| `date`      | Calendar date without time; `validate` rejects anything but a real `YYYY-MM-DD`. No `format`.                                                        |
+| `array`     | JS array; a `null`/`undefined` element is always rejected (index named in the error); `rules.minLength` adds a floor. Element TYPE is not validated. |
+| `jsonb`     | Arbitrary JSON, stored as `jsonb` in Postgres. No schema validation inside.                                                                          |
+| `json`      | Arbitrary JSON stored as `json`. Same semantics as `jsonb` from the handler.                                                                         |
+| `bigint`    | Integer; every string is rejected. No range check beyond the integer test.                                                                           |
+| `smallint`  | Integer; every string is rejected. No range check: a 16-bit overflow fails at the column.                                                            |
+| `int`       | Integer; every string is rejected. No range check: a 32-bit overflow fails at the column.                                                            |
+| `decimal`   | Fixed-precision decimal; `decimals: [total, scale]` (e.g., `[10, 2]` = 99999999.99).                                                                 |
 
 When a type requires additional constraints, `rules` carries them. Observed rules today:
 
@@ -163,8 +161,9 @@ export const PasswordTypeHandler = {
 
 Consequences for any handler that touches an `iam/user` record:
 
-- **On write** (create/update with `@ApplySchema(IamUserFieldSchema)`): the plaintext password from
-  the payload is replaced by its bcrypt hash before the service runs. You never store plaintext.
+- **On write** (create/update with `@ApplySchema({ schema: IamUserFieldSchema, operation })`): the
+  plaintext password from the payload is replaced by its bcrypt hash before the service runs. You
+  never store plaintext.
 - **On read** (`@Format(IamUserFieldSchema)`): the `password` key in the returned object becomes
   `undefined`. JSON serialization drops it, so the client never sees the hash.
 
@@ -181,7 +180,8 @@ formatting" section in [`query-statement.md`](query-statement.md) for the contra
 
 All three live in `@aurorajs.dev/core-back` and apply a `FieldSchema[]` to a method's payload and/or
 return value. Always prefer the decorator over calling `sanitizeRecord()` or `formatRecord()`
-directly — the decorator wires `handlerMeta.timezone` and other options automatically.
+directly — the decorator resolves the options from the handler's meta argument and picks the
+direction for you.
 
 ### `@ApplySchema` — sanitize + format (write handlers that return the entity)
 
@@ -189,7 +189,7 @@ directly — the decorator wires `handlerMeta.timezone` and other options automa
 import { ApplySchema } from '@aurorajs.dev/core-back';
 
 @EmitEvent('iam.tag.created')
-@ApplySchema(IamTagFieldSchema)
+@ApplySchema({ schema: IamTagFieldSchema, operation: 'create' })
 async main(payload: IamCreateTagInput, handlerMeta?: HandlerMeta): Promise<IamTag> {
   await this.createService.main(payload, handlerMeta);
   return await this.findByIdService.main(payload.id, {}, handlerMeta);
@@ -198,11 +198,16 @@ async main(payload: IamCreateTagInput, handlerMeta?: HandlerMeta): Promise<IamTa
 
 - Runs `sanitize` on `payload` BEFORE `main()` executes.
 - Runs `format` on the return value AFTER `main()` resolves.
-- The default assumes `payload` is the first argument. For a different position, pass the object
-  form:
+- `@ApplySchema` accepts ONLY the options-object form; the bare `@ApplySchema(schema)` array form no
+  longer compiles. `operation: 'create' | 'update'` is REQUIRED — it gates whether a `createOnly`
+  key present in the payload gets rejected. Declare `'update'` whenever the write can reach a row
+  that already exists (update-by-id, bulk update, upsert, and any hand-written handler that updates
+  or upserts an existing row); declare `'create'` only when the write can only ever insert a new
+  row. `payloadIndex` defaults to `0` (payload is the first argument); for a different position,
+  add it to the same object:
 
   ```typescript
-  @ApplySchema({ schema: IamTagFieldSchema, payloadIndex: 1 })
+  @ApplySchema({ schema: IamTagFieldSchema, operation: 'update', payloadIndex: 1 })
   async main(otherArg, payload, handlerMeta?) { … }
   ```
 
@@ -228,7 +233,7 @@ async main(id: string, constraint?: QueryStatement, handlerMeta?: HandlerMeta):
 ```typescript
 import { Sanitize } from '@aurorajs.dev/core-back';
 
-@Sanitize(IamUserFieldSchema)
+@Sanitize({ schema: IamUserFieldSchema, operation: 'create' })
 async main(payload: IamBulkIngestUsersInput, handlerMeta?: HandlerMeta): Promise<void> {
   await this.bulkIngestService.main(payload, handlerMeta);
 }
@@ -236,7 +241,8 @@ async main(payload: IamBulkIngestUsersInput, handlerMeta?: HandlerMeta): Promise
 
 - Same sanitize step as `@ApplySchema`, but no format. Use when the handler returns `void`,
   `boolean`, or a summary type that is NOT the entity.
-- Same `payloadIndex` option as `@ApplySchema`.
+- Same options-object shape as `@ApplySchema`: `operation: 'create' | 'update'` is REQUIRED,
+  `payloadIndex` stays optional with a default of `0`.
 - **No current real usage in the backend.** Documented for completeness and for the SRP case:
   write-only flows where imposing a format pass on an unrelated return type would be noise.
 
@@ -251,14 +257,19 @@ Does the handler RECEIVE a payload?
         │
         └── Does the handler RETURN the entity (or entities)?
               │
-              ├── Yes → @ApplySchema(schema)
+              ├── Yes → @ApplySchema({ schema, operation })
               │
-              └── No  → @Sanitize(schema)
+              └── No  → @Sanitize({ schema, operation })
 ```
 
-Additional dimension: if the payload is NOT the first argument, use the object form
-`{ schema, payloadIndex: N }` on `@ApplySchema` or `@Sanitize` (no `payloadIndex` on `@Format` — it
-operates on the return value).
+`@ApplySchema` and `@Sanitize` accept ONLY the options-object form — the bare array form
+`@ApplySchema(schema)` / `@Sanitize(schema)` no longer compiles, and `operation` is REQUIRED on
+both: it gates whether a `createOnly` key present in the payload gets rejected, so declare
+`'update'` whenever the write can reach a row that already exists (update-by-id, bulk update,
+upsert, and any hand-written handler that updates or upserts an existing row), and `'create'` only
+when the write can only ever insert a new row. Additional dimension: if the payload is NOT the
+first argument, add `payloadIndex: N` to the same object (`{ schema, operation, payloadIndex: N }`);
+`@Format` has neither option — it operates on the return value and knows no write operations.
 
 ## `Obj.diffAtomic` / `Obj.diff` — two functions, two different jobs
 
@@ -326,8 +337,8 @@ for the full update-handler flow.
   validation + modification concern is fully delegated to `FieldSchema` + type handlers via
   `@ApplySchema`.
 - **Calling `formatRecord` or `sanitizeRecord` directly.** Always use `@ApplySchema`, `@Format`, or
-  `@Sanitize`. The decorators extract `handlerMeta.timezone` and other options for you; a direct
-  call loses that context and produces inconsistent output.
+  `@Sanitize`. The decorators resolve the options from `handlerMeta` and pick the direction for
+  you; a direct call duplicates that wiring and drifts away from it.
 - **Conflating `@Sanitize` alone with `@ApplySchema`.** They differ: `@Sanitize` runs only on input
   and does NOT format the return. If the handler returns the entity, use `@ApplySchema`; otherwise
   `@Sanitize` is fine on its own.

package/dist/templates/backend/application/.claude/skills/catalyst-field-schema/references/query-statement.md

@@ -32,10 +32,23 @@ Handlers keep the pre-existing two-parameter convention; nothing about this chan
 Sequelize→Drizzle cutover:
 
 - **`queryStatement`** — client-facing filter/sort/pagination payload (resolver/controller input).
-- **`constraint`** — server-side scope (tenant isolation, permission filter), forwarded unchanged
-  through the handler and merged by the service/repository layer via
-  `DrizzleCriteria.mergeQueryConstraintStatement` (deep-merge; a non-empty `where` on both sides
-  combines under `and`, never wholesale-replaces).
+- **`constraint`** — a SECOND argument the handler also forwards unchanged, merged by the
+  service/repository layer via `DrizzleCriteria.mergeQueryConstraintStatement` (deep-merge; a
+  non-empty `where` on both sides combines under `and`, never wholesale-replaces — this property
+  does not change and the tenant predicate below depends on it).
+
+**`constraint` is caller-supplied by default — it is NOT automatically a server-side scope.** On a
+generated endpoint the generated resolver exposes it as `@Args('constraint')` and the generated
+controller takes it from the request body, exactly like `queryStatement`. Nothing in the handler,
+the merge, or the transport makes it trusted; describing it as "server-side scope" without that
+qualification asserts a security property the code does not provide on its own.
+
+**What DOES turn it into a server-side scope**: a decorator on the operation that replaces the
+`constraint` argument with a server-composed statement before the method body runs — i.e. before the
+caller's own value is ever read. `@TenantConstraint()` is that mechanism for tenant isolation; see
+`backend/.claude/skills/catalyst-nestjs-primitives/SKILL.md` for its arguments and
+`openspec/specs/tenant-scope-decorators/spec.md` (the `tenant-scope-decorators` capability) for the
+full behavioral contract — this file does not restate those scenarios.
 
 Real signature, `reporting-get-reporting-catalog-report.handler.ts`:
 
@@ -240,8 +253,8 @@ const existingAccounts = await this.getAccountsService.main({
   Delete the manual call and verify the generated `IamAccountFieldSchema` declares the `user`
   relation entry.
 - **Calling `formatRecord` or `sanitizeRecord` directly instead of via a decorator.** The
-  decorator wires `handlerMeta.timezone`, `meta.contentLanguage`, and other options automatically.
-  A direct call loses that context and produces inconsistent output. No exceptions remain — the
+  decorator resolves the options from `handlerMeta` and picks the direction for you. A direct
+  call duplicates that wiring and drifts away from it. No exceptions remain — the
   pre-1.1.0 "manual format on included relation" workaround is obsolete.
 
 ## Cross-references

package/dist/templates/backend/application/.claude/skills/catalyst-handler-composer/SKILL.md

@@ -303,7 +303,7 @@ export class IamCreateTagHandler {
   ) {}
 
   @EmitEvent('iam.tag.created')
-  @ApplySchema(IamTagFieldSchema)
+  @ApplySchema({ schema: IamTagFieldSchema, operation: 'create' })
   async main(payload: IamCreateTagInput, handlerMeta?: HandlerMeta): Promise<IamTag> {
     // pre-persistence validation would sit here, before the service call
     await this.createService.main(payload, handlerMeta);
@@ -325,9 +325,9 @@ training-memory instincts, reach for the alternative instead.
    resolver/controller holds a reference to the handler directly and calls
    `this.handler.main(payload, { timezone, repositoryOptions: { auditing } })`. There is no bus.
 
-3. **Constructing Value Objects inside the handler.** → Use `@ApplySchema(FieldSchema)` and let the
-   `FieldSchema` declare validation (nullable, maxLength, rules, etc.). The decorator validates the
-   payload before `main()` runs. See
+3. **Constructing Value Objects inside the handler.** → Use `@ApplySchema({ schema, operation })`
+   and let the `FieldSchema` declare validation (nullable, maxLength, rules, etc.). The decorator
+   validates the payload before `main()` runs. See
    [`catalyst-field-schema/references/field-schema-and-decorators.md`](../catalyst-field-schema/references/field-schema-and-decorators.md)
    for the full `FieldSchema` interface, the 16 type handlers, and the `@Sanitize` / `@Format` /
    `@ApplySchema` decision tree.

package/dist/templates/backend/application/.claude/skills/catalyst-handler-composer/references/additional-apis-workflow.md

@@ -28,31 +28,81 @@ Template source lives at `packages/cli/src/templates/codegen/backend/additional-
 
 ## The defaults the CLI chooses (which you will usually override)
 
-The CLI has to guess at five things because the YAML only declares the path, resolver type, and HTTP
+The CLI has to guess at six things because the YAML only declares the path, resolver type, and HTTP
 method. The guesses are conservative but frequently wrong for the real operation.
 
-| Dimension       | CLI default (mutation)                                | CLI default (query)                   |
-| --------------- | ----------------------------------------------------- | ------------------------------------- |
-| Payload type    | `<Bc>Update<Mod>ByIdInput` / `<Bc>Update<Mod>ByIdDto` | `QueryStatement` (no payload)         |
-| Auth permission | `<bc>.<mod>.update`                                   | `<bc>.<mod>.get`                      |
-| Return type     | `Promise<boolean>`                                    | `Promise<<Bc><Mod>[]>`                |
-| Handler body    | `return true;`                                        | `return [];`                          |
-| Constructor     | empty with `// TODO: inject services`                 | empty with `// TODO: inject services` |
+| Dimension          | CLI default (mutation)                                                  | CLI default (query)                   |
+| ------------------ | ----------------------------------------------------------------------- | ------------------------------------- |
+| Payload type       | `<Bc>Update<Mod>ByIdInput` / `<Bc>Update<Mod>ByIdDto`                   | `QueryStatement` (no payload)         |
+| Payload validation | `@ApplySchema({ schema: <Aggregate>FieldSchema, operation: 'update' })` | none                                  |
+| Auth permission    | `<bc>.<mod>.update`                                                     | `<bc>.<mod>.get`                      |
+| Return type        | `Promise<boolean>`                                                      | `Promise<<Bc><Mod>[]>`                |
+| Handler body       | `return true;`                                                          | `return [];`                          |
+| Constructor        | empty with `// TODO: inject services`                                   | empty with `// TODO: inject services` |
 
 Tenancy and auditing branches the CLI also emits conditionally:
 
-- `hasTenant: true` → the handler, resolver, and controller receive `account: IamAccountResponse` as
-  the first argument; the resolver/controller carry `@TenantPolicy()` (mutation) or
-  `@TenantConstraint()` (query).
+- `hasTenant: true` → the handler, resolver, and controller receive `account: IamAccount` (from
+  `@api/graphql`), positioned per the decorator's own signature: first for a query
+  (`@TenantConstraint()` puts `account` before `queryStatement`/`constraint`), after the payload for
+  a mutation (`@TenantPolicy()` is payload-first); the resolver/controller carry the matching
+  decorator.
 - `hasAuditing: true` and mutation → the resolver/controller add
   `@Auditing() auditing?: AuditingMeta` and forward it as `repositoryOptions: { auditing }` into the
   handler meta.
 - The module has i18n properties → `@ContentLanguage()` is added and forwarded as
   `meta: { contentLanguage }`.
 
+## Payload validation: `@ApplySchema` on the mutation branch
+
+Every mutation `additionalApis` handler carries
+`@ApplySchema({ schema: <Aggregate>FieldSchema, operation: 'update' })` above `main()`, with a
+guiding comment above the decorator naming the three edits below. The query branch carries no such
+decorator: it takes no payload, so there is nothing to sanitize. It emits no `@Format` either,
+unlike the core `get`/`find`/`paginate` templates, so a custom query handler that returns aggregate
+rows returns them unmasked and in the raw stored timezone.
+
+**What it does.** The decorator validates and normalizes `payload` (argument 0) against the
+aggregate's `FieldSchema` before `main()` runs, and formats the return value on the way out — the
+same mechanism the `create`/`update`/`upsert` templates already emit. The pipeline is SCHEMA-driven:
+it validates a payload key only when the aggregate's schema declares a field of that name, so a key
+the schema does not declare passes through untouched. But a key matching a `readOnly` property, or a
+`createOnly` property under `operation: 'update'`, is rejected with 400 — a custom payload shape
+that reuses one of THOSE field names is not safe just because it is custom.
+
+**It rewrites, it does not only check.** The sanitize direction transforms values before `main()`
+sees them: a `password` key is bcrypt-hashed by `PasswordTypeHandler.sanitize`. A decorated handler
+must therefore never forward its `payload` to a second decorated handler — the second pass hashes
+the hash, and the account can never authenticate again. `iam/user` is the live case: it declares
+`forgot-password` and `reset-password` as mutation `additionalApis`, and its aggregate declares
+`password` with `type: 'password'`.
+
+**What it does NOT do.** It validates by NAME COINCIDENCE — it does not understand what the custom
+verb actually does. `operation: 'update'` is fixed because it mirrors the payload type the template
+already emits (`<Bc>Update<Mod>ByIdInput` / `<Bc>Update<Mod>ByIdDto`); it is not an inference about
+whether the operation inserts or updates a row.
+
+**The developer's three edits:**
+
+1. Switch `operation` to `'create'` when the custom API only ever inserts a new row. For example,
+   `business-partner-portal/supplier-document/tenant/create` inserts a new
+   `BusinessPartnerPortalSupplierDocument` row and never touches an existing one — `operation`
+   should read `'create'` there, not the emitted default of `'update'`.
+2. Declare `payloadIndex: N` if `payload` is moved off argument 0 during refinement (Phase 1 above).
+   The emitted default of `0` is correct for the scaffold as generated; it stops being correct the
+   moment the handler's signature changes shape.
+3. Remove the decorator entirely once the payload stops being aggregate-shaped (a primitive
+   parameter, a bespoke DTO with no overlapping field names). This is not cosmetic. `sanitizeRecord`
+   opens with `const result = { ...payload }`, and `@Sanitize` writes that copy back over the
+   argument, so a primitive payload reaches the body mangled and no error is raised:
+   `'a@b.c'` arrives as `{ 0: 'a', 1: '@', 2: 'b', 3: '.', 4: 'c' }`, and a number arrives as `{}`.
+
 ## Anchor example: `iam/role/inherit-permissions-role`
 
-This is the canonical scaffolded `additionalApis` on disk today. The YAML declares:
+This is what the CLI emits today for that entry. The file on disk does not carry the decorator:
+`iam/role` has not been regenerated since the template started emitting it. Prettier also reformats
+the braces on the way to disk, so the on-disk file reads K&R where the template emits Allman. The
+YAML declares:
 
 ```yaml
 # cliter/iam/role.aurora.yaml
@@ -123,16 +173,25 @@ export class IamInheritPermissionsRoleRoleController {
 ```typescript
 // @app/iam/role/application/inherit-permissions-role/iam-inherit-permissions-role-role.handler.ts
 @Injectable()
-export class IamInheritPermissionsRoleRoleHandler {
-  constructor() {
-    // TODO: inject services needed for this operation
-  }
-
+export class IamInheritPermissionsRoleRoleHandler
+{
+  // TODO: inject services needed for this operation
+  constructor() {}
+
+  // @ApplySchema runs the aggregate's FieldSchema over `payload`. Two behaviours to know: it
+  // REWRITES values (a `password` key is bcrypt-hashed right here, so never forward this payload
+  // to another decorated handler), and it rejects with 400 a key matching a `readOnly` property,
+  // or a `createOnly` one under 'update'. Yours to adjust: switch `operation` to 'create',
+  // declare `payloadIndex: N` if `payload` moves off argument 0, or remove the decorator when
+  // `payload` is not aggregate-shaped — removal is required, not cosmetic: a primitive arrives
+  // mangled, because the pipeline copies it with a spread.
+  @ApplySchema({ schema: IamRoleFieldSchema, operation: 'update' })
   async main(
     payload: IamUpdateRoleByIdInput | IamUpdateRoleByIdDto,
     constraint?: QueryStatement,
     handlerMeta?: HandlerMeta,
-  ): Promise<boolean> {
+  ): Promise<boolean>
+  {
     // TODO: implement business logic
     return true;
   }

package/dist/templates/backend/application/.claude/skills/catalyst-handler-composer/references/create-handler.md

@@ -38,7 +38,7 @@ export class IamCreateTagHandler {
   ) {}
 
   @EmitEvent('iam.tag.created')
-  @ApplySchema(IamTagFieldSchema)
+  @ApplySchema({ schema: IamTagFieldSchema, operation: 'create' })
   async main(payload: IamCreateTagInput, handlerMeta?: HandlerMeta): Promise<IamTag> {
     await this.createService.main(payload, handlerMeta);
 
@@ -55,9 +55,11 @@ Role of each moving part:
   in its fully-hydrated shape so the resolver does not have to re-query.
 - **`@EmitEvent('iam.tag.created')`** — publishes on `EventEmitter2` after `main()` resolves without
   throwing. You do not call `eventEmitter.emit(...)` by hand.
-- **`@ApplySchema(IamTagFieldSchema)`** — runs declarative validation over `payload` before `main()`
-  begins. Anything the `FieldSchema` expresses (required fields, maxLength, enum membership, custom
-  rules) is enforced here; do not duplicate those checks inside `main()`.
+- **`@ApplySchema({ schema: IamTagFieldSchema, operation: 'create' })`** — runs declarative
+  validation over `payload` before `main()` begins. Anything the `FieldSchema` expresses (required
+  fields, maxLength, enum membership, custom rules) is enforced here; do not duplicate those checks
+  inside `main()`. `operation: 'create'` is REQUIRED on every create handler — it is what lets a
+  `createOnly` property stay writable here while an update handler rejects it.
 - **`payload`** — the GraphQL input type (or DTO in REST controllers); the type comes from
   `@api/graphql`.
 - **`handlerMeta?`** — carries `timezone` and `repositoryOptions.auditing`. The resolver or
@@ -94,7 +96,7 @@ already-persisted aggregate, which is too late to reject cleanly.
 
 ```typescript
 @EmitEvent('iam.tag.created')
-@ApplySchema(IamTagFieldSchema)
+@ApplySchema({ schema: IamTagFieldSchema, operation: 'create' })
 async main(payload: IamCreateTagInput, handlerMeta?: HandlerMeta): Promise<IamTag> {
   // Pre-persistence: reject if a tag with the same slug already exists in the same tenant.
   const existing = await this.repository.find({

package/dist/templates/backend/application/.claude/skills/catalyst-handler-composer/references/update-handler.md

@@ -43,7 +43,7 @@ export class IamUpdateTagByIdHandler {
   ) {}
 
   @EmitEvent('iam.tag.updated')
-  @ApplySchema(IamTagFieldSchema)
+  @ApplySchema({ schema: IamTagFieldSchema, operation: 'update' })
   async main(
     payload: IamUpdateTagByIdInput,
     constraint?: QueryStatement,