@zyno-io/ts-server-foundation 26.712.36

package/docs/content/testing.md

@@ -0,0 +1,327 @@
+# Testing
+
+Tests use the Node `node:test` runner against compiled output. The package provides a small testing facade, in-memory HTTP requests, isolated MySQL/PostgreSQL database helpers, seed hooks, and assertion helpers.
+
+```bash
+corepack yarn test
+corepack yarn test tests/http.spec.ts
+```
+
+## Testing Facade
+
+`TestingHelpers.createTestingFacade()` creates an app with `frameworkConfig.port = 0`, then gives tests lifecycle helpers around that app.
+
+```typescript
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { TestingHelpers } from '@zyno-io/ts-server-foundation';
+
+const tf = TestingHelpers.createTestingFacade({
+    controllers: [UserController],
+    providers: [UserService]
+});
+
+TestingHelpers.installStandardHooks(tf);
+
+describe('UserController', () => {
+    it('returns users', async () => {
+        const response = await TestingHelpers.makeMockRequest(tf, 'GET', '/users');
+        assert.equal(response.statusCode, 200);
+    });
+});
+```
+
+`installStandardHooks(tf)` installs `before`, `after`, `beforeEach`, and `afterEach` hooks. `beforeEach` calls `tf.resetToSeed()`. `afterEach` resets Node mock timers and restores all mocks.
+
+Pass `suiteSeedData` when a suite needs extra baseline rows on top of the facade seed. In savepoint mode, the hook creates a second savepoint after `suiteSeedData` and resets to it before each test. Without savepoints, the hook runs `suiteSeedData` after each `resetToSeed()`.
+
+```typescript
+TestingHelpers.installStandardHooks(tf, {
+    suiteSeedData: async facade => {
+        await facade.get<AppDatabase>(AppDatabase).rawExecute(sql`INSERT INTO users (name) VALUES (${'Seed user'})`);
+    }
+});
+```
+
+## Facade Options
+
+```typescript
+interface TestingFacadeOptions {
+    defaultTestHeaders?: Record<string, string>;
+    seedData?: (facade: TestingFacade) => Promise<void> | void;
+    autoSeedData?: boolean;
+    onBeforeStart?: (facade: TestingFacade) => Promise<void> | void;
+    onStart?: (facade: TestingFacade) => Promise<void> | void;
+    onBeforeStop?: (facade: TestingFacade) => Promise<void> | void;
+    onStop?: (facade: TestingFacade) => Promise<void> | void;
+    enableDatabase?: boolean;
+    dbAdapter?: 'mysql' | 'postgres';
+    useSavepoints?: boolean;
+    databasePrefix?: string;
+    keepDatabase?: boolean;
+    enableMigrations?: boolean;
+    schemaFromEntities?: boolean | CreateMigrationPlanOptions;
+    migrations?: readonly Migration[];
+    migrationsDir?: string | readonly string[];
+    truncateAfterMigrations?: boolean;
+}
+
+interface StandardHookOptions {
+    suiteSeedData?: (facade: TestingFacade) => Promise<void> | void;
+}
+```
+
+Use `createTestingFacadeWithDatabase()` when the test always needs an isolated database.
+
+```typescript
+const tf = TestingHelpers.createTestingFacadeWithDatabase(
+    {
+        db: AppDatabase,
+        controllers: [UserController]
+    },
+    {
+        dbAdapter: 'postgres',
+        databasePrefix: 'app_test',
+        seedData: async facade => {
+            const db = facade.get<AppDatabase>(AppDatabase);
+            await db.rawExecute(sql`INSERT INTO users (name) VALUES (${'Alice'})`);
+        }
+    }
+);
+```
+
+Use `createTestingFacadeBuilder()` to define app-level testing defaults once, then let individual suites append controllers,
+providers, imports, and testing hooks:
+
+```typescript
+export const createTestingFacade = TestingHelpers.createTestingFacadeBuilder(
+    {
+        ...CoreAppOptions,
+        imports: []
+    },
+    {
+        enableDatabase: true,
+        databasePrefix: 'app_test'
+    }
+);
+
+const tf = createTestingFacade({
+    controllers: [UserController]
+});
+```
+
+Builder inputs can also be resolver functions. The returned factory passes each suite's selections to the resolvers, so
+applications can apply custom merge or filtering rules:
+
+```typescript
+export const createTestingFacade = TestingHelpers.createTestingFacadeBuilder(
+    appOptions => ({
+        ...CoreAppOptions,
+        ...appOptions,
+        providers: [...(CoreAppOptions.providers ?? []), ...appOptions.providers].filter(provider => provider !== ReportingDb)
+    }),
+    options => ({
+        enableDatabase: true,
+        databasePrefix: 'app_test',
+        ...options
+    })
+);
+```
+
+## Facade Lifecycle API
+
+`installStandardHooks()` is the normal lifecycle owner, but the facade methods are public for custom harnesses:
+
+| Method | Behavior |
+| --- | --- |
+| `start()` | Runs `onBeforeStart`, creates/prepares the database when enabled, starts the app, then runs `onStart`. |
+| `stop()` | Runs `onBeforeStop`, stops the app, cleans up database state, then runs `onStop`. |
+| `get(token)` | Resolves a provider from the facade app. |
+| `request(request)` | Sends an in-memory `HttpRequest` through the app and returns a `MemoryHttpResponse`. |
+| `createDatabase()` / `destroyDatabase()` | Explicitly owns the configured test database lifecycle. |
+| `runMigrations()` | Loads and runs the facade's configured migrations. |
+| `truncateTables()` | Clears non-internal tables and resets identity state where supported. |
+| `seed()` / `resetToSeed()` | Applies seed data or restores the per-test baseline. |
+| `createSeedSavepoint()` / `resetToSeedSavepoint()` | Manages named seed baselines when savepoint isolation is active. |
+
+`start()` and `stop()` should still be paired. Direct database lifecycle calls are intended for custom setup and debugging; they do not replace app shutdown or the facade hooks.
+
+## Database Tests
+
+The facade creates a database named from `databasePrefix`, timestamp, process id, and a counter. It updates the app config and `Env` for the chosen adapter, then restores the previous database env when stopped.
+
+Database facades use savepoints by default. In savepoint mode, compatible facades reuse migrated test databases, so migrations run once per compatible database slot instead of once per suite. Each facade still gets seed-data isolation and rolls seed/runtime changes back on stop. When `tsf-dev test` has MySQL env available, it starts a shared MySQL session manager with a slot pool sized to the Node test worker concurrency so compatible MySQL facades can run in parallel across worker processes. Each manager slot owns one database and one long-lived backend connection; after schema preparation, the manager keeps a backend transaction open, allows only one frontend connection at a time for that slot, maps frontend transaction commands to savepoints, and rolls back to the slot baseline when the frontend disconnects. Leave `TSF_TEST_MYSQL_SESSION_MANAGER` unset to start the manager when MySQL test config is present and savepoints are allowed, set it to `0` to disable the manager, or set it to `1` to force it on. Set `TSF_TEST_ALLOW_SAVEPOINTS=0` to force all facades out of savepoint mode even when `useSavepoints: true`, or set `useSavepoints: false` for a fully isolated create/migrate/drop database lifecycle. Database readiness waits run only when a facade has `enableDatabase` and are cached once per process.
+
+`TestingFacade.start()` logs `Starting test facade` before database creation, app startup, migrations, and seeding. This gives long-running database tests immediate startup feedback while routine HTTP request/response logs remain suppressed by default in test mode.
+
+Required local env keys are the same keys used by app config:
+
+```bash
+MYSQL_HOST=127.0.0.1
+MYSQL_PORT=3306
+MYSQL_USER=root
+MYSQL_PASSWORD_SECRET=secret
+MYSQL_DATABASE=app
+
+PG_HOST=127.0.0.1
+PG_PORT=5432
+PG_USER=root
+PG_PASSWORD_SECRET=secret
+PG_DATABASE=app
+```
+
+Set `TEST_KEEP_DB=true` or `keepDatabase: true` to keep test databases during facade or process cleanup.
+
+## Migrations And Seeds
+
+When `enableDatabase` is true, migrations run by default if the app has a database class. You can pass explicit `migrations`, point at `migrationsDir`, or set `enableMigrations: false`.
+
+Set `schemaFromEntities: true` to create the registered entity schema through `createMigrationPlan()` before migrations run. Pass `{ tableNames, pgSchema }` instead of `true` to scope that schema generation.
+
+After migrations, the facade truncates tables by default. Set `truncateAfterMigrations: false` when a test needs migration-provided seed rows.
+
+Migration execution logs include the number found, number previously executed, number to run, and per-migration start/end messages.
+
+Use `seedData` and `autoSeedData` for repeatable per-test state:
+
+```typescript
+const tf = TestingHelpers.createTestingFacadeWithDatabase(
+    { db: AppDatabase },
+    {
+        dbAdapter: 'mysql',
+        autoSeedData: true,
+        seedData: async facade => {
+            await facade.get<AppDatabase>(AppDatabase).rawExecute(sql`INSERT INTO users (name) VALUES (${'Alice'})`);
+        }
+    }
+);
+```
+
+## Mock Requests
+
+`TestingHelpers.makeMockRequest()` sends an in-memory `HttpRequest` through the app router and returns a `MemoryHttpResponse`.
+
+```typescript
+const getResponse = await TestingHelpers.makeMockRequest(tf, 'GET', '/users?limit=10');
+const postResponse = await TestingHelpers.makeMockRequest(tf, 'POST', '/users', { name: 'Alice' });
+const headerResponse = await TestingHelpers.makeMockRequest(tf, 'POST', '/users', { authorization: 'Bearer token' }, { name: 'Alice' });
+
+assert.equal(postResponse.statusCode, 200);
+assert.deepEqual(postResponse.json, { id: 1, name: 'Alice' });
+```
+
+For lower-level cases, call `tf.request(new HttpRequest(...))` directly.
+
+## Assertion Helpers
+
+The package root exports asymmetric testing matchers.
+
+```typescript
+import { anyOf, matchesObject, objectContaining, stringContaining } from '@zyno-io/ts-server-foundation';
+
+matchesObject(result, {
+    id: anyOf(String),
+    name: stringContaining('Alice'),
+    metadata: objectContaining({ source: 'test' })
+});
+```
+
+Available helpers are `matchesObject`, `anyOf`, `arrayContaining`, `stringContaining`, `objectContaining`, `anything`, and `assertCalledWith`.
+
+## Entity Fixtures
+
+`defineEntityFixtures()` keeps fixture objects typed against an entity and records the entity class on each fixture. Date properties accept ISO strings and are converted to `Date` instances by `prepareEntityFixtures()` or `loadEntityFixtures()`.
+
+```typescript
+const users = TestingHelpers.defineEntityFixtures(User, {
+    alice: {
+        email: 'alice@example.com',
+        createdAt: '2026-01-01T00:00:00.000Z'
+    }
+});
+
+const tf = TestingHelpers.createTestingFacadeWithDatabase(
+    { db: AppDatabase },
+    {
+        seedData: () => TestingHelpers.loadEntityFixtures([users.alice])
+    }
+);
+```
+
+`loadEntityFixtures()` persists fixtures one at a time through the entity's registered database.
+
+## Query Builder Mocks
+
+Every facade exposes `tf.sql`, a `SqlTestingHelper` for entity-query tests that do not need a real database.
+
+```typescript
+const tf = TestingHelpers.createTestingFacade({});
+
+tf.sql.mockEntity(User, [
+    { id: '1', name: 'Alice', visits: 1 },
+    { id: '2', name: 'Bob', visits: 2 }
+]);
+
+const names = await User.query()
+    .filter({ visits: { $gte: 2 } })
+    .orderBy('name')
+    .findField('name');
+
+await User.query()
+    .filterField('id', '2')
+    .patchOne({ $inc: { visits: 1 } });
+```
+
+The in-memory query builder covers common field filters (including comparison and `LIKE` operators), selection, ordering, paging, scalar/entity reads, counts, and patch/delete mutations. It does not mock raw SQL or dialect-specific SQL behavior. `installStandardHooks()` clears the facade's SQL mocks after every test; call `tf.sql.clearMocks()` when managing lifecycle manually.
+
+## Database Defaults And Cleanup
+
+`setDefaultDatabaseConfig()` writes values to `Env` only when a key is not already configured. `cleanupTestDatabases(prefix, adapter?)` drops MySQL/PostgreSQL test databases matched by SQL `LIKE '<prefix>%'`, including compatible shared-database state in the current process.
+
+```typescript
+TestingHelpers.setDefaultDatabaseConfig({
+    MYSQL_HOST: '127.0.0.1',
+    MYSQL_USER: 'root'
+});
+
+await TestingHelpers.cleanupTestDatabases('myapptest', 'mysql');
+```
+
+Use a test-specific alphanumeric prefix; cleanup is intentionally destructive for matching database names, and `_` or `%` in the prefix acts as a SQL wildcard.
+
+## Global Setup And Module State
+
+When `dist/tests/shared/globalSetup.js` exists, `tsf-test` loads it before discovering/running tests. An exported `setup()` may be synchronous or asynchronous; an exported `teardown()` runs after the test process and shared MySQL session manager finish.
+
+```typescript
+export async function setup() {
+    // one-time process setup
+}
+
+export async function teardown() {
+    // one-time process cleanup
+}
+```
+
+Environment changes performed while the global-setup module is loaded are retained for the test subprocess. Prefer suite hooks for state that can be isolated per file or facade.
+
+`TestingHelpers.resetSrcModuleCache()` removes CommonJS cache entries whose paths contain `/dist/` or `/src/`. It is useful when a test must re-evaluate application modules after changing environment or module-level state. It does not reset third-party packages, ESM module caches, process globals, registered decorators, or other singleton registries.
+
+## Exported Helpers
+
+`TestingHelpers` currently includes:
+
+- `cleanupTestDatabases`
+- `createTestingFacade`
+- `createTestingFacadeBuilder`
+- `createTestingFacadeWithDatabase`
+- `defineEntityFixtures`
+- `installStandardHooks`
+- `loadEntityFixtures`
+- `makeMockRequest`
+- `prepareEntityFixtures`
+- `resetSrcModuleCache`
+- `SqlTestingHelper`
+- `setDefaultDatabaseConfig`
+
+The fixture functions and `SqlTestingHelper` class are also exported individually from the package root, but `TestingHelpers` is the convenient facade for application tests.

package/docs/content/type-reflection-architecture.md

@@ -0,0 +1,149 @@
+# Type Reflection Architecture
+
+TSF reflection metadata is the shared contract between validation, deserialization, HTTP routing, OpenAPI generation, and database schema extraction. The compiler should emit one coherent metadata shape, and runtime consumers should interpret that shape through shared helpers instead of re-implementing TypeScript type rules or duplicating validation logic.
+
+For application-facing `typeOf`, class/member inspection, annotation readers, custom validators/deserializers, and shared-package setup, see [Type Reflection](./reflection.md).
+
+This document is the source of truth for reflection policy. Implementation details can move, but code should continue to satisfy these rules.
+
+## Goals
+
+Reflection must preserve the TypeScript type that application authors wrote while still letting TypeScript resolve complex type algebra. The important outcomes are:
+
+- validation and OpenAPI describe the same shape and constraints;
+- database schema extraction uses the same reflected facts, with storage-specific interpretation only where needed;
+- public aliases stay visible when they are part of an API contract;
+- generated OpenAPI component names are stable and human-meaningful;
+- consumer package paths, model names, and workspace layouts are never hardcoded;
+- compiler work is scoped so metadata generation does not explode memory usage.
+
+## Metadata Pipeline
+
+The compiler has two encoders.
+
+The Typia encoder is preferred for structural DTOs. It asks TypeScript and Typia for the resolved type, so mapped types, conditional types, intersections, unions, `Pick`, `Omit`, `Partial`, and local aliases are reduced by the TypeScript checker before TSF serializes metadata.
+
+The internal encoder is reserved for TSF-only semantics that Typia cannot preserve on its own. Examples include root framework wrappers, root database/entity metadata, unresolved index metadata, ordered literal unions, native `Date` metadata that must remain a runtime `Date`, and source alias boundaries that runtime consumers must still see.
+
+The compiler may precompute metadata for emitted project files so checker-backed work is done before parallel write callbacks. That cache is an implementation detail. It must not become a broad semantic pass that asks Typia for every reachable type.
+
+## Preferred Surfaces
+
+HTTP controller method arguments and return types are preferred structural metadata surfaces. On those surfaces, the compiler should use Typia for the outer structural DTO whenever Typia can preserve the observable runtime meaning.
+
+Preferred surfaces intentionally allow nested TSF tags such as `DateString`, `UuidString`, validation tags, database tags, and named aliases without forcing the whole DTO through the internal encoder. If a specific property carries metadata Typia cannot preserve, the compiler should preserve that property's source metadata rather than abandoning the entire DTO shape.
+
+Root wrappers are different from their payloads. A wrapper such as `HttpBody<T>`, `HttpQueries<T>`, `HttpQuery<T>`, `HttpPath<T>`, `HttpHeader<T>`, or `ApiResponse<T, Status>` must keep wrapper metadata because routing and response handling depend on it. The wrapped payload type `T` should still follow the normal preferred-surface rules.
+
+Non-preferred surfaces are more conservative. They may use Typia when the type or an alias body contains Typia-preferred syntax, such as Typia-compatible tags or complex mapped/conditional helpers. Otherwise, root framework markers, root database markers, external package aliases, `Date`, and similar runtime-sensitive types should stay on the internal encoder.
+
+## Internal Encoder Boundaries
+
+Use the internal encoder for shapes where TSF metadata is observable and Typia does not carry enough information:
+
+- framework wrappers and response metadata;
+- root database/entity markers;
+- root or unresolved index metadata where TSF must preserve `additionalProperties` or index value details that Typia did not emit;
+- source-dependent utility metadata only when preserving an alias, index, or property-source boundary is observable to runtime consumers;
+- ordered literal unions when schema order is observable;
+- direct `Date` or `ValidDate` roots, because runtime deserialization must produce a `Date`;
+- object-target custom validators where Typia tag metadata does not preserve the validator on the native value;
+- imported package aliases when the alias boundary should be loaded from that package's emitted metadata.
+
+These boundaries are narrow. `Record`, index signatures, and indexed access should not force an enclosing controller DTO onto the internal encoder when TypeScript and Typia can resolve the composed type into equivalent structural metadata. TypeScript utility composition such as `OptionalNulls<Pick<T, K>>` should be resolved by the checker/Typia path on preferred structural surfaces, not reimplemented by name in Go.
+
+## Tags And Annotations
+
+Custom type semantics should be represented as Typia-compatible tag metadata wherever possible. Type definitions should attach structured tags in TypeScript; compiler code should read those tag shapes instead of duplicating alias-specific meanings.
+
+Runtime consumers should read tags through shared annotation helpers:
+
+- validation executes validators from reflected validation metadata;
+- deserialization reads reflected metadata for transforms and runtime value handling;
+- OpenAPI maps the same reflected validation metadata into schema keywords;
+- database extraction reads database tags and may additionally use shared validation facts, such as `minimum >= 0` for unsigned numeric columns.
+
+## Runtime Execution Boundaries
+
+Reflection metadata is available to multiple subsystems, but metadata availability does not imply that every value crosses the validation/deserialization pipeline.
+
+| Surface                                                  | Reflected deserialization       | Reflected validation     |
+| -------------------------------------------------------- | ------------------------------- | ------------------------ |
+| HTTP body, query, path, and header controller parameters | Yes                             | Yes                      |
+| Explicit `validatedDeserialize<T>()`                     | Yes                             | Yes                      |
+| Compiler-backed `deserialize<T>()`                       | Yes                             | No final validation pass |
+| Compiler-backed `validate<T>()`                          | No                              | Yes                      |
+| Configuration loading                                    | Primitive config coercion only  | Yes                      |
+| Entity/query-builder database I/O                        | Column-specific conversion only | No                       |
+| Controller return values                                 | No; ordinary JSON serialization | No                       |
+
+TSF intentionally has a reflected deserializer registry for incoming transforms and no matching reflected outbound serializer registry. HTTP output relies on TypeScript return types at development time and ordinary JSON serialization at runtime. Database runtime conversion is a storage boundary with its own column-specific rules; it does not implicitly run API-input transforms or validators.
+
+The current compiler injects generic metadata for `deserialize<T>()`, `validate<T>()`, `validatedDeserialize<T>()`, and `typeOf<T>()`. It also injects metadata for compatibility exports such as `cast<T>()`, `assert<T>()`, and `is<T>()` when import identity proves that the call targets the foundation package. Uncompiled compatibility calls require explicit metadata and throw when it is absent.
+
+TSF tags are metadata, not fake object properties. Typia-internal `typia.tag` objects must not appear as user-visible OpenAPI properties or validation targets.
+
+`Pattern<T>` and `Validate<T>` should use literal string arguments when possible so the compiler can emit portable metadata. Non-literal runtime validator references remain an internal-encoder concern.
+
+## Validation And OpenAPI
+
+Validation and OpenAPI should be nearly 1:1. If validation knows about a string format, pattern, length, numeric minimum, numeric maximum, or custom named validator, OpenAPI should usually expose the corresponding schema information from the same reflected metadata.
+
+OpenAPI should not infer TSF semantics from bare type names such as `DateString`, `UuidString`, `PhoneNumber`, or `UnsignedNumber`. Those semantics must come from annotations, Typia tags, constructor identity, or structurally bare marker stubs. Matching a user-defined class or alias by name alone is not acceptable.
+
+Validation may execute runtime functions that OpenAPI can only name or approximate. In those cases, both consumers should still read the same reflected validator metadata.
+
+## Database Extraction
+
+Database schema extraction is the intended domain-specific consumer of reflection metadata. It may interpret tags and validation facts in storage-specific ways, including:
+
+- column type selection from database field tags;
+- primary keys, uniqueness, indexes, references, defaults, and update hooks;
+- `minimum >= 0` as an unsigned numeric column hint for dialects that support unsigned columns;
+- length constraints as string column width hints.
+
+Database-specific interpretation should remain in database extraction. Validation and OpenAPI should not duplicate database schema rules unless the rule is also a validation rule.
+
+## Alias And Package Boundaries
+
+Named aliases are part of the public API when they are written into controller DTOs or exported from shared packages. Reflection should preserve that boundary so OpenAPI can emit component references using exported names.
+
+Generic application aliases use the exported base name for OpenAPI components. For example, `Envelope<string, Record<string, unknown>>` should produce `Envelope`, not a sanitized instantiated name. Generated utility components may use stable generated names when no exported alias exists.
+
+Shared packages should expose emitted alias metadata through `__tsfTypeAliases`. When an app imports a type from a package that exposes TSF metadata, the compiler should reference that package metadata by import/export identity. It must not resolve behavior by repository path, workspace layout, or application-specific package name.
+
+TSF's own package spec may be recognized as a single compiler constant because the compiler must distinguish foundation metadata helpers from arbitrary user imports. Other package specs must not be special-cased.
+
+## Component Naming
+
+OpenAPI component naming should prioritize stable public names:
+
+- explicit OpenAPI names win;
+- named aliases and classes use their exported names;
+- non-utility generic aliases use the exported base name;
+- utility displays such as `Pick`, `Omit`, `Partial`, and `Required` may generate stable names only when no public alias is available;
+- same-name components with equivalent OpenAPI signatures should be reused;
+- same-name components with different signatures should be disambiguated deterministically.
+
+Anonymous object literals should stay inline unless a stable name is explicitly available.
+
+## Hardcoding And Duplication
+
+Hardcoded names should be minimized and centralized. Acceptable hardcoded values are framework wrapper names, reflection kind names, TSF tag keys, known TypeScript built-ins such as `Date`, and TSF's own package spec as a single compiler constant.
+
+Application model names, app package paths, shared-package aliases, and consumer repository names must never be hardcoded.
+
+Compiler code may know TSF marker names when those names define metadata syntax, such as `DatabaseField`, `Index`, `Pattern`, or `TsfValidatorTag`. It should not duplicate semantic payloads that can be expressed in TypeScript tags. For example, a date-string alias should get its date behavior from `TypiaFormat<'date'>` and `TsfTypeTag`, not from a Go switch on the alias name.
+
+## Implementation Checks
+
+When changing reflection behavior, check these invariants:
+
+- a DTO containing a nested database tag should still use structural Typia metadata where the database tag is not the root payload;
+- DTOs composed with `Record`, index signatures, or indexed access should still use Typia when the resolved structural shape preserves the observable runtime contract;
+- a DTO containing `Date` should not force the whole object through the internal encoder, but the `Date` property must still deserialize and document as a date-time value;
+- a direct `Date` or `ValidDate` root should preserve runtime `Date` metadata;
+- literal unions that need stable emitted ordering should not be reordered by Typia;
+- imported shared-package aliases should remain references to that package metadata;
+- OpenAPI component names should not include sanitized generic instantiations when an exported alias name is available;
+- validation metadata and OpenAPI schema keywords should come from the same annotations.