@joktec/skills 0.1.4 → 0.1.8

package/dist/windsurf/.windsurf/rules/joktec-mysql-skill.md

@@ -12,8 +12,12 @@ Use this skill for relational resources backed by JokTec's TypeORM wrapper.
 - Treat `mysql`, `mariadb`, and `postgres` as the first-class dialects.
 - Keep `sync` explicit and normally enabled only by an owner process or development bootstrap.
 - Do not add new behavior to deprecated `MysqlFinder`; use `MysqlRepo.qb()` and `MysqlHelper` paths.
-- When migrating an entity to the new schema-first decorators, migrate the whole property decorator stack, not only the TypeORM primary key decorator.
-- If guidance is insufficient, read this skill's references and inspect `../joktec-framework` package source or GitHub fallback before assuming APIs.
+- Use schema-first `@Column`, `@PrimaryColumn`, and `@TimestampColumn` wrappers when an entity also acts as DTO metadata.
+- Use `@Column({ kind: 'virtual' })` for computed getters that need expose/Swagger metadata without persistence.
+- Use `immutable` for API read-only metadata; TypeORM `update: false` remains storage write behavior and is also inferred as Swagger read-only when `immutable` is not set.
+- Do not add `swagger.type` just because a column has a primitive, date, array, nested JSON class, or relation type. The wrapper infers Swagger metadata from TypeScript design type and JokTec options. Use `swagger` only to override an inferred shape.
+- Do not use `@joktec/mysql` for Mongo/ObjectId columns, even though TypeORM has Mongo-related APIs.
+- For real migrations, inspect the installed `@joktec/mysql` source in the consumer project's `node_modules` first. If that is insufficient, read GitHub package docs, then GitHub source. Use the local `../joktec-framework` checkout only when you are working inside the JokTec development workspace.
 
 ## References
 
@@ -28,13 +32,29 @@ Use this skill for relational resources backed by JokTec's TypeORM wrapper.
 
 ## Source Lookup
 
-When blocked, inspect:
+When blocked in a consumer project, inspect the installed package first:
+
+- `node_modules/@joktec/mysql/README.md`
+- `node_modules/@joktec/mysql/AGENTS.md` when published with the package
+- `node_modules/@joktec/mysql/dist/index.d.ts`
+- `node_modules/@joktec/mysql/dist/decorators/column.decorator.d.ts`
+- `node_modules/@joktec/mysql/dist/decorators/columns/column.type.d.ts`
+- `node_modules/@joktec/mysql/dist/decorators/timestamp.decorator.d.ts`
+
+If the installed package is missing enough detail, use the GitHub package docs next:
+
+- `https://github.com/joktec/joktec-framework/tree/main/packages/databases/mysql`
+
+Use GitHub source only after package docs and installed types are not enough:
 
 - `packages/databases/mysql/src/decorators/table.decorator.ts`
 - `packages/databases/mysql/src/decorators/column.decorator.ts`
 - `packages/databases/mysql/src/decorators/columns/column.type.ts`
 - `packages/databases/mysql/src/decorators/columns/column.factory.ts`
 - `packages/databases/mysql/src/decorators/columns/primary.column.ts`
+- `packages/databases/mysql/src/decorators/columns/timestamp.column.ts`
+- `packages/databases/mysql/src/decorators/columns/virtual.column.ts`
+- `packages/databases/mysql/src/decorators/columns/object.column.ts`
 - `packages/databases/mysql/src/decorators/columns/string.column.ts`
 - `packages/databases/mysql/src/decorators/columns/number.column.ts`
 - `packages/databases/mysql/src/decorators/columns/transform.column.ts`
@@ -42,7 +62,7 @@ When blocked, inspect:
 
 ## Schema-First Entity Pattern
 
-Use `@Tables`, `@Column`, and `@PrimaryColumn` from `@joktec/mysql` when an entity should also act as the source class for mapped DTOs.
+Use `@Tables`, `@Column`, `@PrimaryColumn`, and `@TimestampColumn` from `@joktec/mysql` when an entity should also act as the source class for mapped DTOs.
 
 The new decorators are not thin TypeORM aliases. They are schema-first wrappers that compose:
 
@@ -51,11 +71,19 @@ The new decorators are not thin TypeORM aliases. They are schema-first wrappers
 - `class-transformer` expose/exclude behavior.
 - Swagger property metadata.
 
-When migrating old entities, remove duplicate property decorators from `typeorm`, `class-validator`, `class-transformer`, and Swagger when the wrapper option can represent the same behavior.
+The wrapper can also represent virtual computed getters and nested JSON/jsonb class payloads. Do not use this package for Mongo/ObjectId columns.
+
+Wrapper philosophy:
+
+- prefer one schema declaration that carries persistence, validation, transform, and Swagger metadata
+- use wrapper options before duplicating `@ApiProperty`, `@Expose`, `@Type`, or common validators
+- do not add `swagger.type` for normal scalar/date fields, arrays, nested JSON classes, or relations when the wrapper can infer the shape
+- use raw TypeORM only for advanced cases that the wrapper does not model cleanly
+- keep storage write behavior and API documentation behavior distinct when needed
 
-## Legacy Decorator Migration
+## Current Decorator Capabilities
 
-Migrate a whole property at a time. Do not only replace `PrimaryGeneratedColumn`.
+Use the package README and actual installed source for full migration details. This skill only keeps the common mappings that help an agent recognize old patterns.
 
 Common mappings:
 
@@ -64,11 +92,21 @@ Common mappings:
 | `@PrimaryGeneratedColumn()` | `@PrimaryColumn('increment')` |
 | `@PrimaryGeneratedColumn('uuid')` | `@PrimaryColumn('uuid')` |
 | app-generated ordered UUID id | `@PrimaryColumn('uuidv7')` |
+| `@CreateDateColumn(...)` | `@TimestampColumn('create', ...)` |
+| `@UpdateDateColumn(...)` | `@TimestampColumn('update', ...)` |
+| `@DeleteDateColumn(...)` | `@TimestampColumn('delete', ...)` |
+| TypeORM `@VersionColumn(...)` | `@Column({ kind: 'version', ... })` |
+| TypeORM `@VirtualColumn(...)` | `@Column({ kind: 'virtual', mode: 'sql', query, ... })` |
+| TypeORM `@ViewColumn(...)` | `@Column({ kind: 'view', ... })` |
 | `@Column(...)` | `@Column(...)` from `@joktec/mysql` |
+| `@RelationId(...)` | `@Column({ kind: 'relation-id', relationId })` |
 | `@IsNotEmpty()` | `@Column({ required: true })` |
 | `@IsOptional()` | `@Column({ required: false })` or nullable TypeORM option when storage allows null |
 | `@IsEmail()` | `@Column({ isEmail: true })` |
 | `@IsMobilePhone()` | `@Column({ isPhone: true })` |
+| `@IsInt()` | `@Column({ isInt: true })` or an integer column type |
+| `@IsUUID()` | `@Column({ isUUID: true })` |
+| `@IsObject()` | `@Column({ isObject: true })` or a JSON column |
 | `@IsHexColor()` | `@Column({ isHexColor: true })` |
 | `@IsUrl()` | `@Column({ isUrl: true })` |
 | `@MinLength(n)` | `@Column({ minLength: n })` |
@@ -78,54 +116,49 @@ Common mappings:
 | `@Expose()` | default behavior of `@Column(...)` |
 | `@Expose({ groups })` | `@Column({ groups })` |
 | `@Exclude({ toPlainOnly: true })` plus hidden Swagger | `@Column({ hidden: true })` |
-| `@ApiProperty(...)` | `@Column({ swagger: ... })`, or native options such as `example`, `comment`, `deprecated`, `min`, `max`, `minLength`, `maxLength` |
-
-Preserve decorators only when the wrapper cannot express them, by passing them through `decorators: [...]`.
-
-Migration checklist:
-
-- Replace TypeORM column decorators with wrappers from `@joktec/mysql`.
-- Remove duplicate `class-validator` decorators when equivalent wrapper options exist.
-- Remove duplicate `class-transformer` decorators when `hidden` or `groups` expresses the same behavior.
-- Move Swagger examples/descriptions/limits into wrapper options where possible.
-- Preserve custom validators/transforms only through `decorators: [...]`.
-- Keep database-specific options such as `type`, `length`, `nullable`, `unique`, `default`, `enum`, and `comment`.
-- Rebuild and run entity-related tests after migration because DTO metadata and TypeORM metadata both change.
-
-Example migration:
-
-```ts
-// Before
-@Column({ type: 'varchar', length: 255 })
-@IsEmail()
-@IsNotEmpty()
-@Expose()
-@ApiProperty({ example: 'user@example.com' })
-email!: string;
-
-// After
-@Column('varchar', {
-  length: 255,
-  required: true,
-  isEmail: true,
-  example: 'user@example.com',
-})
-email!: string;
-```
-
-For hidden fields:
-
-```ts
-// Before
-@Column({ type: 'varchar', length: 255 })
-@Exclude({ toPlainOnly: true })
-@ApiHideProperty()
-password!: string;
-
-// After
-@Column('varchar', { length: 255, hidden: true })
-password!: string;
-```
+| `@ApiProperty(...)` | Prefer native options such as `example`, `comment`, `deprecated`, `min`, `max`, `minLength`, `maxLength`; use `swagger` only as an override |
+| `@ValidateNested()` + `@Type(() => Preference)` | `@Column('jsonb', { nested: Preference })` |
+| `@ValidateNested({ each: true })` + `@Type(() => Preference)` | `@Column('jsonb', { nested: Preference, each: true })` |
+| `@Expose()` + `@ApiProperty(...)` on a getter | `@Column({ kind: 'virtual', ... })` |
+| Swagger `readOnly: true` | `@Column({ immutable: true })` or TypeORM `update: false` when ORM updates must also be blocked |
+
+## Swagger Metadata Rules
+
+The `@Column` wrapper already composes Swagger metadata. During migrations, keep entity code small and avoid redundant `swagger` declarations:
+
+- Do not add `swagger: { type: String }` for string columns.
+- Do not add `swagger: { type: Number }` for numeric columns.
+- Do not add `swagger: { type: Boolean }` for boolean columns.
+- Do not add `swagger: { type: Date }` for date, datetime, or timestamp columns.
+- Do not add `swagger: { type: String, isArray: true }` for `simple-array` or reflected array fields unless the OpenAPI shape must differ from the entity field.
+- Do not add `swagger: { type: NestedClass }` when `nested: NestedClass` is already present.
+- Do not add `swagger: { type: () => Entity }` on `Column({ kind: 'relation', type: () => Entity })`; the relation wrapper keeps the Swagger type lazy to avoid circular schema evaluation.
+
+Use `swagger` only for actual overrides, for example:
+
+- an OpenAPI primitive differs from the TypeScript property type, such as a SQL decimal represented as `string`
+- a property needs `oneOf`, `anyOf`, `allOf`, custom `items`, or a deliberately shortened example
+- a generated schema needs an explicit read/write/deprecated override that cannot be represented by wrapper options
+
+If a relation wrapper still triggers a circular Swagger error in a consumer project, inspect `node_modules/@joktec/mysql/dist/decorators/column.decorator.d.ts` and the installed implementation first. Do not paper over the issue by adding `swagger.type` to every relation; identify whether the installed package version has lazy relation Swagger support.
+
+## Read-Only Metadata
+
+`immutable` is the API read-only hint used by the JokTec MySQL wrapper. TypeORM `update: false` is the ORM write behavior. The wrapper maps both to Swagger `readOnly` when appropriate:
+
+- `immutable` has priority over `update: false`
+- `update: false` implies Swagger `readOnly` only when `immutable` is not set
+- `swagger.readOnly` remains the final explicit override
+
+Some field kinds default to API read-only because they are system-managed or computed:
+
+- primary keys
+- timestamp columns
+- version columns
+- view columns
+- virtual getter and SQL virtual columns
+- relation-id columns
+- tree level columns
 
 ## Primary Keys
 
@@ -146,7 +179,21 @@ The stable dialects are MySQL, MariaDB, and Postgres. Dialect capabilities own d
 
 ## Source Lookup
 
-When blocked, inspect:
+When blocked in a consumer project, inspect installed package docs and types first:
+
+- `node_modules/@joktec/mysql/README.md`
+- `node_modules/@joktec/mysql/AGENTS.md` when published with the package
+- `node_modules/@joktec/mysql/dist/index.d.ts`
+- `node_modules/@joktec/mysql/dist/mysql.module.d.ts`
+- `node_modules/@joktec/mysql/dist/mysql.service.d.ts`
+- `node_modules/@joktec/mysql/dist/mysql.repo.d.ts`
+- `node_modules/@joktec/mysql/dist/models/mysql.request.d.ts`
+
+If the installed package is insufficient, read GitHub package docs next:
+
+- `https://github.com/joktec/joktec-framework/tree/main/packages/databases/mysql`
+
+Use GitHub source only after installed types and package docs are not enough:
 
 - `packages/databases/mysql/README.md`
 - `packages/databases/mysql/AGENTS.md`

package/dist/windsurf/.windsurf/rules/joktec-tool-skill.md

@@ -47,6 +47,7 @@ Best practice:
 - Use the package service for outbound HTTP so retry/proxy/metrics behavior stays centralized.
 - Keep external endpoint URLs and credentials in runtime config.
 - Be careful with ESM/CommonJS import changes in HTTP/Axios ecosystem packages.
+- `HttpService.buildAgent(proxy, opts)` expects proxy identity in `HttpProxyConfig` and agent tuning in Node `AgentOptions`; inspect the installed source before adapting to proxy-agent major-version changes.
 - Test request behavior with mocks unless the test is an explicit consumer integration scenario.
 
 ## File

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joktec/skills",
-  "version": "0.1.4",
+  "version": "0.1.8",
   "private": false,
   "description": "Hybrid agent skill pack for using @joktec/* libraries in consumer projects.",
   "license": "MIT",
@@ -47,7 +47,10 @@
     "skills"
   ],
   "scripts": {
-    "check": "node scripts/validate-skills.mjs && node scripts/sync-from-joktec-framework.mjs --check",
+    "sync:version": "node scripts/sync-pack-version.mjs",
+    "check:version": "node scripts/sync-pack-version.mjs --check",
+    "version": "node scripts/sync-pack-version.mjs --stage",
+    "check": "pnpm run check:version && node scripts/validate-skills.mjs && node scripts/sync-from-joktec-framework.mjs --check",
     "validate": "node scripts/validate-skills.mjs",
     "build": "node scripts/build-skill-folders.mjs && node scripts/build-cursor-rules.mjs && node scripts/build-gemini-md.mjs && node scripts/build-copilot-instructions.mjs && node scripts/build-windsurf-rules.mjs",
     "build:skills": "node scripts/build-skill-folders.mjs",
@@ -58,7 +61,7 @@
     "sync:check": "node scripts/sync-from-joktec-framework.mjs --check",
     "pack:check": "pnpm pack --dry-run",
     "prepublish:check": "pnpm run build && pnpm run check && pnpm pack --dry-run",
-    "publish:dry-run": "pnpm run prepublish:check && pnpm publish --dry-run --no-git-checks --access public",
+    "publish:dry-run": "pnpm run prepublish:check && pnpm publish --dry-run --access public",
     "publish:registry": "pnpm run prepublish:check && pnpm publish --access public",
     "release:patch": "pnpm version patch && pnpm run publish:registry",
     "release:minor": "pnpm version minor && pnpm run publish:registry",

package/scripts/sync-pack-version.mjs

@@ -0,0 +1,38 @@
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { PACK_PATH, ROOT, readJson, writeFile } from './lib.mjs';
+
+const args = new Set(process.argv.slice(2));
+const checkOnly = args.has('--check');
+const stage = args.has('--stage');
+const packagePath = path.join(ROOT, 'package.json');
+
+const pkg = readJson(packagePath);
+const pack = readJson(PACK_PATH);
+const version = pkg.version;
+
+if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version || '')) {
+  console.error(`Invalid package.json version: ${version || '<missing>'}`);
+  process.exit(1);
+}
+
+function stagePackFile() {
+  execFileSync('git', ['add', PACK_PATH], { cwd: ROOT, stdio: 'inherit' });
+  console.log('Staged skill-pack.json');
+}
+
+if (pack.version === version) {
+  console.log(`skill-pack.json version is in sync: ${version}`);
+  if (stage) stagePackFile();
+  process.exit(0);
+}
+
+if (checkOnly) {
+  console.error(`Version mismatch: package.json=${version}, skill-pack.json=${pack.version || '<missing>'}`);
+  process.exit(1);
+}
+
+pack.version = version;
+writeFile(PACK_PATH, JSON.stringify(pack, null, 2));
+console.log(`Updated skill-pack.json version to ${version}`);
+if (stage) stagePackFile();

package/skill-pack.json

@@ -1,6 +1,6 @@
 {
   "name": "@joktec/skills",
-  "version": "0.1.2",
+  "version": "0.1.8",
   "sourceOfTruth": "../joktec-framework",
   "frameworkBaseline": {
     "repo": "https://github.com/joktec/joktec-framework",
@@ -350,6 +350,40 @@
         "copilot": true,
         "windsurf": true
       }
+    },
+    {
+      "id": "advanced-typescript-design",
+      "title": "Advanced TypeScript Design",
+      "role": "focused",
+      "requiredByDefault": false,
+      "dependencies": [],
+      "recommended": [],
+      "packages": [
+        "TypeScript",
+        "NestJS"
+      ],
+      "scope": {
+        "paths": [
+          "**/*.ts",
+          "**/*.tsx"
+        ]
+      },
+      "triggers": [
+        "typescript",
+        "generic public APIs",
+        "conditional types",
+        "decorator metadata",
+        "type-safe query DSL",
+        "design patterns"
+      ],
+      "outputs": {
+        "codex": true,
+        "claude": true,
+        "cursor": true,
+        "gemini": true,
+        "copilot": true,
+        "windsurf": true
+      }
     }
   ]
 }

package/skills/advanced-typescript-design/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: advanced-typescript-design
+description: Use this skill for TypeScript framework/library design, including generic public APIs, infer/conditional/recursive mapped types, decorator metadata, type-safe query DSLs, lifecycle abstractions, and design pattern selection. Use for TypeScript/NestJS packages, repositories, DTO/query types, clients, loaders, metrics, or when deciding whether simple TypeScript is enough or advanced type-system design is justified.
+---
+
+# Advanced TypeScript Design
+
+## Overview
+
+Act as a TypeScript architecture partner. Choose the simplest design that preserves clear boundaries, runtime correctness, and useful compile-time guarantees.
+
+Use design patterns as vocabulary and pressure tests, not as decoration. Prefer local project conventions, readable APIs, and low-friction extension points before adding type-level machinery.
+
+## Architectural Mindset
+
+- Start from the domain boundary: identify entity, request/response, service, repository, client, decorator, loader, and integration responsibilities.
+- Keep public APIs narrow and stable. Make extension explicit through interfaces, abstract classes, generic constraints, or composition.
+- Use classes when lifecycle, inheritance hooks, decorators, or framework reflection matter. Use plain functions/types when behavior is stateless or purely transformational.
+- Let runtime validation and compile-time types reinforce each other. Do not pretend TypeScript types validate untrusted runtime data.
+- Do not assume TypeScript generics, interfaces, unions, or array element types exist at runtime through `reflect-metadata`.
+- Escalate type complexity only when it removes real duplication, prevents invalid states, or makes an API substantially safer.
+- Check existing code before inventing a new pattern; mirror the repository's style when it already solves the same class of problem.
+
+## Public API Compatibility
+
+- Treat exported types, classes, decorators, config objects, modules, and provider APIs as public contracts.
+- Prefer additive changes over breaking renames, deleted fields, changed generic parameter order, or narrower accepted input shapes.
+- Before changing exported generic types, check downstream inference from normal call sites and verify that common extension patterns still compile.
+- If a breaking type or runtime contract change is unavoidable, report migration impact explicitly and include the smallest migration path.
+
+## Pattern Vocabulary
+
+Use the classic catalog as shared language, including the TypeScript examples catalog from Refactoring.Guru.
+
+- Creational Patterns: Abstract Factory, Builder, Factory Method, Prototype, Singleton.
+- Structural Patterns: Adapter, Bridge, Composite, Decorator, Facade, Flyweight, Proxy.
+- Behavioral Patterns: Chain of Responsibility, Iterator, Memento, State, Template Method, Command, Mediator, Observer, Strategy, Visitor.
+
+Treat pattern names as a starting point for design discussion. Validate whether the implementation needs the pattern's tradeoffs, or whether a direct function, data object, or interface is enough.
+
+## Agent Workflow
+
+1. Inspect local code first when working inside a repository. Look for existing abstractions, decorators, DTO types, factory functions, lifecycle hooks, and tests.
+2. Classify the task:
+   - Use `references/simple.md` for everyday TypeScript, OOP, data modeling, classes, interfaces, types, records, maps, arrays, simple decorators, and pragmatic refactors.
+   - Use `references/advanced.md` for generic framework code, recursive mapped types, `infer`, distributed/deferred conditional types, reflection metadata, advanced decorators, type-safe builders, plugin architectures, or expert pattern selection.
+3. Choose the least complex pattern that solves the force in front of you. Record why a simpler alternative was not enough when choosing advanced machinery.
+4. Design the public surface before implementation: inputs, outputs, extension points, error behavior, lifecycle, and type inference experience.
+5. Implement incrementally. Keep runtime behavior testable, and add focused type-level checks when exported generic or decorator behavior is subtle.
+6. Review for overengineering: remove unused generic parameters, speculative base classes, unnecessary inheritance, and type utilities that do not protect a real API.
+
+## Repository Signals
+
+In JokTec-style TypeScript, expect patterns such as:
+
+- Generic request/query types with recursive conditions and sort/populate typing.
+- Factory functions that return decorated NestJS classes.
+- Abstract services and clients with template methods for lifecycle-specific behavior.
+- Decorator factories that compose validation, Swagger, transformation, metrics, and integration metadata.
+- Loader/registry patterns that collect decorator metadata and wire runtime behavior during module initialization.

package/skills/advanced-typescript-design/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Advanced TypeScript Design"
+  short_description: "Design advanced TypeScript APIs"
+  default_prompt: "Use $advanced-typescript-design to design or refactor TypeScript framework code with an appropriate type-safety and pattern level."

package/skills/advanced-typescript-design/references/advanced.md

@@ -0,0 +1,219 @@
+# Advanced TypeScript Design Guidance
+
+Use this reference for framework-level TypeScript, generic libraries, decorator infrastructure, metadata-driven loaders, and APIs where compile-time inference is part of the product experience.
+
+## Escalation Criteria
+
+Reach for advanced TypeScript only when at least one is true:
+
+- The API is reused widely and type inference prevents real misuse.
+- The runtime model is already generic, recursive, or metadata-driven.
+- The abstraction eliminates repeated boilerplate across many entities, DTOs, repositories, services, clients, or transports.
+- The type-level design mirrors a stable domain contract, not a speculative future.
+- Tests or examples can prove both runtime behavior and developer ergonomics.
+
+If the advanced type exists only to feel clever, delete it.
+
+## Infer, Conditional, and Deferred Types
+
+- Use `infer` to extract return types, payloads, entity types, DTO shapes, tuple elements, and callback signatures from source contracts.
+- Control distributive conditional types intentionally. Wrap operands in tuples, such as `[T] extends [U]`, when union distribution is not wanted.
+- Prefer named intermediate aliases when nested conditionals exceed two branches.
+- Use `never` as a filter, but verify that it cannot erase useful error information from public APIs.
+- Treat deferred conditional types and generic inference as public UX: callers should get helpful autocomplete and errors without manual type arguments.
+
+## Recursive and Mapped Types
+
+- Use recursive mapped types for query languages, nested sort/select/populate APIs, deep partials, and entity graph traversal.
+- Add clear stop conditions for primitives, dates, arrays, functions, and branded values.
+- Use branded or opaque types for special primitives such as `ObjectId`, `UserId`, tenant IDs, cursors, or external reference IDs when plain strings would blur domain boundaries.
+- Avoid infinite or overly expensive type recursion. Keep recursion shallow enough for editor performance.
+- Preserve optionality and readonly modifiers intentionally with `+?`, `-?`, `readonly`, and `-readonly`.
+- Separate query operator typing from entity typing so the operator model remains testable and reusable.
+
+## Reflection and Decorators
+
+- Use `reflect-metadata` only when runtime type information materially improves the API: schema generation, validation composition, serialization, dependency injection, or loader registration.
+- Remember that reflected TypeScript types are lossy at runtime. Arrays, unions, generics, and interfaces need explicit options or factories.
+- Prefer decorator factories that normalize options, resolve type factories, compose framework decorators, and define one clear metadata contract.
+- Keep advanced decorators thin at the call site and explicit internally: clone options, sanitize runtime-only fields, then compose validators, transformers, docs, and persistence metadata.
+- For method decorators, preserve `this`, return values, thrown errors, and async behavior unless the decorator explicitly changes them.
+- Use function source parsing only as a last-resort runtime technique for decorator infrastructure, such as mapping method argument names. Keep it isolated, deterministic, and covered by tests because minification, transpilation, defaults, destructuring, and comments can break it.
+- Test decorator behavior through a class that uses it, especially for metadata, wrapping behavior, and dependency injection.
+
+## Type-Level Verification
+
+- Add type-level tests when changing exported generic utilities, query DSLs, decorators, builders, or public inference-heavy APIs.
+- Prefer the project's existing compile/type test setup. If available, use `tsd`, `expect-type`, `vitest`/`jest` type helpers, or a dedicated `tsc --noEmit` fixture.
+- Include positive inference examples from normal call sites, not only explicit generic arguments.
+- Include negative examples with `@ts-expect-error` when an invalid state must stay rejected.
+- Verify runtime tests separately when decorators, reflection metadata, validation, transformation, or loaders are involved.
+
+## Expert Pattern Selection
+
+- Abstract Factory fits families of related clients, repositories, or transport adapters that must be created consistently.
+- Builder fits fluent configuration with required-step guarantees; type-state builders can enforce completeness but should stay readable.
+- Factory Method fits framework hooks that create DTOs, pagination wrappers, controllers, or provider instances.
+- Prototype fits cloning configured objects when construction is expensive or stateful.
+- Singleton should usually be delegated to the DI container; avoid hand-rolled global state.
+- Adapter fits third-party client normalization and migration layers.
+- Bridge fits separating abstraction from implementation, such as transport-agnostic messaging APIs over Rabbit, Kafka, or Redis.
+- Composite fits tree-shaped filters, pipelines, menu/routes, or nested query conditions.
+- Decorator fits metrics, retries, circuit breakers, serialization, validation, or publishing side effects around existing behavior.
+- Facade fits a stable service hiding multiple low-level collaborators.
+- Flyweight fits large repeated metadata or schema objects only after measuring memory pressure.
+- Proxy fits lazy clients, caching, access control, retries, and remote boundaries.
+- Chain of Responsibility fits validation, middleware, parsing, and request pipelines.
+- Command fits queued work, replayable operations, and undoable actions.
+- Iterator fits cursor pagination and collection traversal without exposing storage details.
+- Mediator fits module coordination where direct dependencies would become tangled.
+- Memento fits snapshots, rollbacks, and state restoration.
+- Observer fits event streams and pub/sub, with explicit unsubscribe and error policy.
+- State fits lifecycle-heavy clients, jobs, or connections with mode-specific behavior.
+- Strategy fits interchangeable algorithms selected by config or runtime context.
+- Template Method fits abstract base services/clients that own lifecycle while subclasses implement `init`, `start`, `stop`, `validate`, or `transform` steps.
+- Visitor fits operations over stable object structures when adding new operations is more common than adding new node types.
+
+## Symbolic Examples
+
+Use examples like these as compact templates for thinking. Keep production implementations smaller or larger depending on the actual force.
+
+### Type-Safe Event Map
+
+```typescript
+type EventMap = {
+  "user.created": { id: string };
+  "invoice.paid": { invoiceId: string; amount: number };
+};
+
+class EventBus<TEvents extends Record<string, unknown>> {
+  on<K extends keyof TEvents>(event: K, handler: (payload: TEvents[K]) => void) {}
+  emit<K extends keyof TEvents>(event: K, payload: TEvents[K]) {}
+}
+
+const bus = new EventBus<EventMap>();
+bus.emit("invoice.paid", { invoiceId: "inv_1", amount: 100 });
+```
+
+Use this for Observer/Mediator-style APIs where event names and payloads must stay coupled.
+
+### API Contract Inference
+
+```typescript
+type Endpoint = {
+  "/users/:id": {
+    GET: { params: { id: string }; response: User };
+    PATCH: { params: { id: string }; body: Partial<User>; response: User };
+  };
+};
+
+type ResponseOf<T> = T extends { response: infer R } ? R : never;
+
+class ApiClient<TContract extends Record<string, any>> {
+  request<Path extends keyof TContract, Method extends keyof TContract[Path]>(
+    path: Path,
+    method: Method,
+  ): Promise<ResponseOf<TContract[Path][Method]>> {
+    return null as any;
+  }
+}
+```
+
+Use this when a contract object should drive call-site inference.
+
+### Type-State Builder
+
+```typescript
+type With<K extends string> = Record<K, true>;
+
+class JobBuilder<State = {}> {
+  queue(name: string): JobBuilder<State & With<"queue">> {
+    return this as any;
+  }
+
+  handler(fn: () => Promise<void>): JobBuilder<State & With<"handler">> {
+    return this as any;
+  }
+
+  build(this: State extends With<"queue"> & With<"handler"> ? JobBuilder<State> : never) {
+    return {};
+  }
+}
+```
+
+Use this when incomplete configuration is common and worth rejecting at compile time.
+
+### Recursive Query Shape
+
+```typescript
+type Primitive = string | number | boolean | Date;
+type FieldOp<T> = T | { $eq?: T; $in?: T[] };
+type Brand<T, Name extends string> = T & { readonly __brand: Name };
+type ObjectId = Brand<string, "ObjectId">;
+
+type Query<T> = {
+  [K in keyof T]?: T[K] extends Primitive
+    ? FieldOp<T[K]>
+    : T[K] extends Array<infer U>
+      ? Query<U>
+      : Query<T[K]>;
+} & {
+  $or?: Query<T>[];
+};
+```
+
+Use this for Composite-style nested filters, but add stop conditions before expanding it.
+
+### Opaque ID Boundary
+
+```typescript
+type Brand<T, Name extends string> = T & { readonly __brand: Name };
+type UserId = Brand<string, "UserId">;
+type PostId = Brand<string, "PostId">;
+
+function asUserId(value: string): UserId {
+  return value as UserId;
+}
+
+function findUser(id: UserId) {}
+
+findUser(asUserId("u_1"));
+// @ts-expect-error raw strings are not accepted here
+findUser("u_1");
+```
+
+Use this when a domain primitive crosses many generic/query layers and accidental mixing would be costly.
+
+### Decorator Wrapper with Preserved Method Contract
+
+```typescript
+function Around(run: (next: () => unknown) => unknown): MethodDecorator {
+  return (_, __, descriptor) => {
+    const original = descriptor.value;
+
+    descriptor.value = function (...args: unknown[]) {
+      return run(() => original.apply(this, args));
+    };
+  };
+}
+```
+
+Use this for metrics, retry, logging, or publishing side effects; preserve `this`, args, return values, and thrown errors.
+
+## JokTec-Style Signals to Reuse
+
+- Recursive query typing can combine entity properties with operator unions, nested entity traversal, and logical `$or`/`$and` shapes.
+- Base services and clients commonly use Template Method: the base class owns lifecycle and shared behavior while subclasses provide specific implementation steps.
+- Controller factories can return decorated classes to avoid repetitive NestJS endpoint scaffolding while preserving DTO-specific metadata.
+- Decorator infrastructure often composes Swagger, validation, transformation, persistence, and metric behavior from one options object.
+- Rabbit loaders show a metadata registry plus module-init loader pattern: decorators declare intent; loaders resolve providers and connect runtime consumers.
+
+## Advanced Review Checklist
+
+- Does every generic parameter appear in the public contract or implementation?
+- Can inference succeed from normal call-site arguments?
+- Does the type-level model match runtime validation and transformation?
+- Are metadata keys centralized and collision-resistant?
+- Are decorator side effects documented by tests?
+- Is editor performance acceptable after adding recursive or conditional types?
+- Is there a simpler Strategy, Adapter, or function-based design that would provide the same value?