@breadstone/archipel-mcp 0.0.1

package/src/knowledge/errorHandlingPattern.js

@@ -0,0 +1,219 @@
+"use strict";
+/**
+ * Static knowledge content for the Archipel error handling pattern.
+ * Returned by the get-error-handling-pattern tool.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERROR_HANDLING_PATTERN_KNOWLEDGE = void 0;
+exports.ERROR_HANDLING_PATTERN_KNOWLEDGE = `# Archipel Error Handling Pattern
+
+## Overview
+
+Archipel uses **domain-specific error classes** that are caught by **global exception filters**
+and mapped to structured HTTP responses. Services throw domain errors; the framework handles
+the HTTP translation. This keeps business logic clean and error responses consistent.
+
+## Layer Architecture
+
+\`\`\`
+Service → throws DomainError → ExceptionFilter → HTTP Response Envelope
+\`\`\`
+
+## Base Error Classes
+
+### RepositoryError
+
+Thrown when any Prisma operation fails. Automatically wrapped by \`RepositoryBase.tryCatch()\`.
+
+\`\`\`typescript
+// models/errors/RepositoryError.ts
+export class RepositoryError extends Error {
+
+  public readonly code = 'REPOSITORY_ERROR';
+  public readonly originalCode?: string;
+  public readonly meta?: Record<string, unknown>;
+
+  public constructor(message: string, originalCode?: string, meta?: Record<string, unknown>) {
+    super(message);
+    Object.setPrototypeOf(this, RepositoryError.prototype);
+    this.name = 'RepositoryError';
+    this.originalCode = originalCode;
+    this.meta = meta;
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, RepositoryError);
+    }
+  }
+
+}
+\`\`\`
+
+### MappingError (abstract)
+
+Base for mapping-related errors.
+
+\`\`\`typescript
+export abstract class MappingError extends Error {
+  public readonly code: string;
+
+  protected constructor(message: string, code: string) {
+    super(message);
+    this.code = code;
+  }
+}
+\`\`\`
+
+Concrete variants:
+- \`MappingNotRegisteredError\` — code: \`'MAPPING_NOT_REGISTERED'\`
+- \`TypeMappingNotRegisteredError\` — code: \`'TYPE_MAPPING_NOT_REGISTERED'\`
+
+## Exception Filters
+
+### RepositoryExceptionFilter
+
+\`\`\`typescript
+import { ArgumentsHost, Catch, ExceptionFilter, HttpStatus } from '@nestjs/common';
+import { Request, Response } from 'express';
+import { RepositoryError } from '../models/errors/RepositoryError';
+
+@Catch(RepositoryError)
+export class RepositoryExceptionFilter implements ExceptionFilter<RepositoryError> {
+
+  public catch(_exception: RepositoryError, host: ArgumentsHost): void {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    const request = ctx.getRequest<Request>();
+
+    response.status(HttpStatus.INTERNAL_SERVER_ERROR).json({
+      statusCode: HttpStatus.INTERNAL_SERVER_ERROR,
+      timestamp: new Date().toISOString(),
+      error: 'Repository Error',
+      path: request.url,
+    });
+  }
+
+}
+\`\`\`
+
+### Registration (in main.ts or AppModule)
+
+\`\`\`typescript
+app.useGlobalFilters(new RepositoryExceptionFilter());
+\`\`\`
+
+## How to Create a Domain Error
+
+### Step 1: Define the error class
+
+\`\`\`typescript
+// models/errors/UserNotFoundError.ts
+export class UserNotFoundError extends Error {
+
+  public readonly code = 'USER_NOT_FOUND';
+  public readonly userId: string;
+
+  public constructor(userId: string) {
+    super(\\\`User not found: \\\${userId}\\\`);
+    Object.setPrototypeOf(this, UserNotFoundError.prototype);
+    this.name = 'UserNotFoundError';
+    this.userId = userId;
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, UserNotFoundError);
+    }
+  }
+
+}
+\`\`\`
+
+### Step 2: Create an exception filter
+
+\`\`\`typescript
+// filters/UserNotFoundExceptionFilter.ts
+import { ArgumentsHost, Catch, ExceptionFilter, HttpStatus } from '@nestjs/common';
+import { Request, Response } from 'express';
+import { UserNotFoundError } from '../models/errors/UserNotFoundError';
+
+@Catch(UserNotFoundError)
+export class UserNotFoundExceptionFilter implements ExceptionFilter<UserNotFoundError> {
+
+  public catch(exception: UserNotFoundError, host: ArgumentsHost): void {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    const request = ctx.getRequest<Request>();
+
+    response.status(HttpStatus.NOT_FOUND).json({
+      statusCode: HttpStatus.NOT_FOUND,
+      timestamp: new Date().toISOString(),
+      error: exception.code,
+      message: exception.message,
+      path: request.url,
+    });
+  }
+
+}
+\`\`\`
+
+### Step 3: Register the filter globally
+
+\`\`\`typescript
+app.useGlobalFilters(
+  new RepositoryExceptionFilter(),
+  new UserNotFoundExceptionFilter(),
+);
+\`\`\`
+
+### Step 4: Throw from a service
+
+\`\`\`typescript
+@Injectable()
+export class UserService {
+
+  public async findById(id: string): Promise<IUserEntity> {
+    const user = await this._userRepository.execute(findUserByIdQuery(id));
+
+    if (!user) {
+      throw new UserNotFoundError(id);
+    }
+
+    return user;
+  }
+
+}
+\`\`\`
+
+## Response Envelope Convention
+
+All error responses follow the same shape:
+
+\`\`\`json
+{
+  "statusCode": 404,
+  "timestamp": "2026-04-05T12:00:00.000Z",
+  "error": "USER_NOT_FOUND",
+  "message": "User not found: abc-123",
+  "path": "/api/v1/users/abc-123"
+}
+\`\`\`
+
+## Prisma Error Code Reference
+
+Common Prisma error codes wrapped by \`RepositoryError\`:
+
+| Code | Meaning |
+|------|---------|
+| P2000 | Value too long |
+| P2002 | Unique constraint violation |
+| P2003 | Foreign key constraint violation |
+| P2025 | Record not found |
+
+## Rules
+
+1. **Services throw domain errors** — never raw NestJS HttpException in service layer.
+2. **Exception filters map to HTTP** — one filter per domain error type.
+3. **Error classes include a machine-readable \`code\`** — used for client-side error handling.
+4. **Use \`Object.setPrototypeOf\`** and \`Error.captureStackTrace\` in custom Error subclasses.
+5. **Don't leak internal details** — the filter should not expose Prisma error codes or stack traces.
+6. **Register filters globally** in the bootstrap function or via \`APP_FILTER\` provider.
+`;
+//# sourceMappingURL=errorHandlingPattern.js.map

package/src/knowledge/guardPattern.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Static knowledge content for the Archipel guard & interceptor pattern.
+ * Returned by the get-guard-pattern tool.
+ */
+export declare const GUARD_PATTERN_KNOWLEDGE = "# Archipel Guard & Interceptor Pattern\n\n## Overview\n\nArchipel uses a **metadata-driven** guard and interceptor pattern. A custom decorator\nattaches metadata (e.g., a feature key or role) to the handler. The guard reads this\nmetadata to decide access. An optional interceptor runs after the handler to record\nusage or perform side effects.\n\nThis creates a reusable trio: **Decorator \u2192 Guard \u2192 Interceptor**.\n\n## Guard Architecture\n\n```\n@RequiresFeature('create-posts')       \u2190 Decorator sets metadata\n@UseGuards(JwtAuthGuard, FeatureGuard) \u2190 Guard reads metadata, checks access\n@UseInterceptors(FeatureUsageInterceptor) \u2190 Interceptor records usage after success\n```\n\n## Available Guards\n\n| Guard | Strategy | Purpose |\n|-------|----------|---------|\n| `JwtAuthGuard` | jwt | Validates JWT bearer token |\n| `LocalAuthGuard` | local | Validates username + password |\n| `AnonymousAuthGuard` | anonymous | Allows unauthenticated access with a seed user |\n| `GithubAuthGuard` | github | OAuth via GitHub |\n| `RolesGuard` | metadata | Checks user roles against required roles |\n| `FeatureGuard` | metadata + port | Checks feature access via FeatureAccessPort |\n\n## The Feature Guard Pattern (Full Example)\n\n### Step 1: Metadata Decorator\n\n```typescript\nimport { SetMetadata } from '@nestjs/common';\n\nexport const FEATURE_KEY_METADATA = 'feature_key';\n\nexport const RequiresFeature = (featureKey: string) =>\n  SetMetadata(FEATURE_KEY_METADATA, featureKey);\n```\n\n### Step 2: Guard\n\n```typescript\nimport { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';\nimport { Reflector } from '@nestjs/core';\nimport { FeatureAccessPort } from '../contracts/FeatureAccessPort';\n\n@Injectable()\nexport class FeatureGuard implements CanActivate {\n\n  // #region Fields\n\n  private readonly _featureAccessPort: FeatureAccessPort;\n  private readonly _reflector: Reflector;\n\n  // #endregion\n\n  // #region Ctor\n\n  public constructor(featureAccessPort: FeatureAccessPort, reflector: Reflector) {\n    this._featureAccessPort = featureAccessPort;\n    this._reflector = reflector;\n  }\n\n  // #endregion\n\n  // #region Methods\n\n  public async canActivate(context: ExecutionContext): Promise<boolean> {\n    const featureKey = this._reflector.get<string>(FEATURE_KEY_METADATA, context.getHandler());\n\n    if (!featureKey) {\n      return true; // No feature requirement on this endpoint\n    }\n\n    const request = context.switchToHttp().getRequest();\n    const user = request.user;\n\n    if (!user || !user.id) {\n      return false;\n    }\n\n    const access = await this._featureAccessPort.checkAccess(user.id, featureKey);\n    request.featureAccess = access; // Attach for downstream use\n\n    return access.allowed;\n  }\n\n  // #endregion\n\n}\n```\n\n### Step 3: Interceptor (records usage after success)\n\n```typescript\nimport { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';\nimport { Reflector } from '@nestjs/core';\nimport { Observable } from 'rxjs';\nimport { tap } from 'rxjs/operators';\n\n@Injectable()\nexport class FeatureUsageInterceptor implements NestInterceptor {\n\n  // #region Fields\n\n  private readonly _featureAccessPort: FeatureAccessPort;\n  private readonly _reflector: Reflector;\n\n  // #endregion\n\n  // #region Ctor\n\n  public constructor(featureAccessPort: FeatureAccessPort, reflector: Reflector) {\n    this._featureAccessPort = featureAccessPort;\n    this._reflector = reflector;\n  }\n\n  // #endregion\n\n  // #region Methods\n\n  public intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {\n    const featureKey = this._reflector.get<string>(FEATURE_KEY_METADATA, context.getHandler());\n\n    if (!featureKey) {\n      return next.handle();\n    }\n\n    const request = context.switchToHttp().getRequest();\n    const user = request.user;\n\n    return next.handle().pipe(\n      tap(async () => {\n        if (user && user.id) {\n          await this._featureAccessPort.recordUsage(user.id, featureKey);\n        }\n      }),\n    );\n  }\n\n  // #endregion\n\n}\n```\n\n### Step 4: Controller Usage\n\n```typescript\n@Controller('/posts')\nexport class PostsController {\n\n  @Post()\n  @RequiresFeature('create-posts')\n  @UseGuards(JwtAuthGuard, FeatureGuard)\n  @UseInterceptors(FeatureUsageInterceptor)\n  public async createPost(@Body() body: CreatePostRequest): Promise<PostResponse> {\n    const entity = await this._postService.create(body);\n\n    return this._mappingService.map(POST_MAPPING_KEY, entity);\n  }\n\n}\n```\n\n## Roles Guard Pattern\n\n```typescript\n// Decorator\nexport const Roles = (...roles: string[]) => SetMetadata('roles', roles);\n\n// Guard\n@Injectable()\nexport class RolesGuard implements CanActivate {\n\n  public constructor(private readonly _reflector: Reflector) {}\n\n  public canActivate(context: ExecutionContext): boolean {\n    const requiredRoles = this._reflector.get<string[]>('roles', context.getHandler());\n    if (!requiredRoles) return true;\n\n    const request = context.switchToHttp().getRequest();\n    const user = request.user;\n\n    return requiredRoles.some((role) => user.roles?.includes(role));\n  }\n\n}\n\n// Usage\n@Get('/admin')\n@Roles('admin', 'superadmin')\n@UseGuards(JwtAuthGuard, RolesGuard)\npublic async getAdminPanel(): Promise<AdminResponse> { ... }\n```\n\n## Telemetry Interceptor\n\n```typescript\n@Injectable()\nexport class OperationTelemetryInterceptor implements NestInterceptor {\n\n  private readonly _facade: ITelemetryFacade;\n\n  public intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {\n    const handler = context.getHandler().name;\n    const cls = context.getClass().name;\n    // ... start span, capture duration, record outcome\n    return next.handle();\n  }\n\n}\n```\n\n## How to Create a Custom Guard + Interceptor Pair\n\n### Step 1: Define the metadata key and decorator\n\n```typescript\nexport const RATE_LIMIT_METADATA = 'rate_limit';\nexport const RateLimit = (maxRequests: number) => SetMetadata(RATE_LIMIT_METADATA, maxRequests);\n```\n\n### Step 2: Create the guard\n\nRead metadata via `Reflector`, check the condition, return boolean.\n\n### Step 3: Create the interceptor (optional)\n\nUse `tap()` in the RxJS pipeline to perform post-handler side effects.\n\n### Step 4: Register in the module\n\nExport guard and interceptor from the library module so consumers can apply them.\n\n## Rules\n\n1. **Guards decide access** \u2014 return `true` or `false`, never throw directly.\n2. **Interceptors handle side effects** \u2014 recording, logging, transforming responses.\n3. **Metadata decorators are the glue** \u2014 they attach config to handlers, read by guards/interceptors.\n4. **Auth guards extend Passport's AuthGuard** \u2014 e.g. `AuthGuard('jwt')`.\n5. **Feature guards delegate to ports** \u2014 the guard itself holds no business logic.\n6. **Guard order matters** \u2014 `@UseGuards(AuthGuard, FeatureGuard)`: auth runs first.\n7. **Interceptors use `tap()`** for post-handler logic, `map()` for response transformation.\n";

package/src/knowledge/guardPattern.js

@@ -0,0 +1,256 @@
+"use strict";
+/**
+ * Static knowledge content for the Archipel guard & interceptor pattern.
+ * Returned by the get-guard-pattern tool.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GUARD_PATTERN_KNOWLEDGE = void 0;
+exports.GUARD_PATTERN_KNOWLEDGE = `# Archipel Guard & Interceptor Pattern
+
+## Overview
+
+Archipel uses a **metadata-driven** guard and interceptor pattern. A custom decorator
+attaches metadata (e.g., a feature key or role) to the handler. The guard reads this
+metadata to decide access. An optional interceptor runs after the handler to record
+usage or perform side effects.
+
+This creates a reusable trio: **Decorator → Guard → Interceptor**.
+
+## Guard Architecture
+
+\`\`\`
+@RequiresFeature('create-posts')       ← Decorator sets metadata
+@UseGuards(JwtAuthGuard, FeatureGuard) ← Guard reads metadata, checks access
+@UseInterceptors(FeatureUsageInterceptor) ← Interceptor records usage after success
+\`\`\`
+
+## Available Guards
+
+| Guard | Strategy | Purpose |
+|-------|----------|---------|
+| \`JwtAuthGuard\` | jwt | Validates JWT bearer token |
+| \`LocalAuthGuard\` | local | Validates username + password |
+| \`AnonymousAuthGuard\` | anonymous | Allows unauthenticated access with a seed user |
+| \`GithubAuthGuard\` | github | OAuth via GitHub |
+| \`RolesGuard\` | metadata | Checks user roles against required roles |
+| \`FeatureGuard\` | metadata + port | Checks feature access via FeatureAccessPort |
+
+## The Feature Guard Pattern (Full Example)
+
+### Step 1: Metadata Decorator
+
+\`\`\`typescript
+import { SetMetadata } from '@nestjs/common';
+
+export const FEATURE_KEY_METADATA = 'feature_key';
+
+export const RequiresFeature = (featureKey: string) =>
+  SetMetadata(FEATURE_KEY_METADATA, featureKey);
+\`\`\`
+
+### Step 2: Guard
+
+\`\`\`typescript
+import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { FeatureAccessPort } from '../contracts/FeatureAccessPort';
+
+@Injectable()
+export class FeatureGuard implements CanActivate {
+
+  // #region Fields
+
+  private readonly _featureAccessPort: FeatureAccessPort;
+  private readonly _reflector: Reflector;
+
+  // #endregion
+
+  // #region Ctor
+
+  public constructor(featureAccessPort: FeatureAccessPort, reflector: Reflector) {
+    this._featureAccessPort = featureAccessPort;
+    this._reflector = reflector;
+  }
+
+  // #endregion
+
+  // #region Methods
+
+  public async canActivate(context: ExecutionContext): Promise<boolean> {
+    const featureKey = this._reflector.get<string>(FEATURE_KEY_METADATA, context.getHandler());
+
+    if (!featureKey) {
+      return true; // No feature requirement on this endpoint
+    }
+
+    const request = context.switchToHttp().getRequest();
+    const user = request.user;
+
+    if (!user || !user.id) {
+      return false;
+    }
+
+    const access = await this._featureAccessPort.checkAccess(user.id, featureKey);
+    request.featureAccess = access; // Attach for downstream use
+
+    return access.allowed;
+  }
+
+  // #endregion
+
+}
+\`\`\`
+
+### Step 3: Interceptor (records usage after success)
+
+\`\`\`typescript
+import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Observable } from 'rxjs';
+import { tap } from 'rxjs/operators';
+
+@Injectable()
+export class FeatureUsageInterceptor implements NestInterceptor {
+
+  // #region Fields
+
+  private readonly _featureAccessPort: FeatureAccessPort;
+  private readonly _reflector: Reflector;
+
+  // #endregion
+
+  // #region Ctor
+
+  public constructor(featureAccessPort: FeatureAccessPort, reflector: Reflector) {
+    this._featureAccessPort = featureAccessPort;
+    this._reflector = reflector;
+  }
+
+  // #endregion
+
+  // #region Methods
+
+  public intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
+    const featureKey = this._reflector.get<string>(FEATURE_KEY_METADATA, context.getHandler());
+
+    if (!featureKey) {
+      return next.handle();
+    }
+
+    const request = context.switchToHttp().getRequest();
+    const user = request.user;
+
+    return next.handle().pipe(
+      tap(async () => {
+        if (user && user.id) {
+          await this._featureAccessPort.recordUsage(user.id, featureKey);
+        }
+      }),
+    );
+  }
+
+  // #endregion
+
+}
+\`\`\`
+
+### Step 4: Controller Usage
+
+\`\`\`typescript
+@Controller('/posts')
+export class PostsController {
+
+  @Post()
+  @RequiresFeature('create-posts')
+  @UseGuards(JwtAuthGuard, FeatureGuard)
+  @UseInterceptors(FeatureUsageInterceptor)
+  public async createPost(@Body() body: CreatePostRequest): Promise<PostResponse> {
+    const entity = await this._postService.create(body);
+
+    return this._mappingService.map(POST_MAPPING_KEY, entity);
+  }
+
+}
+\`\`\`
+
+## Roles Guard Pattern
+
+\`\`\`typescript
+// Decorator
+export const Roles = (...roles: string[]) => SetMetadata('roles', roles);
+
+// Guard
+@Injectable()
+export class RolesGuard implements CanActivate {
+
+  public constructor(private readonly _reflector: Reflector) {}
+
+  public canActivate(context: ExecutionContext): boolean {
+    const requiredRoles = this._reflector.get<string[]>('roles', context.getHandler());
+    if (!requiredRoles) return true;
+
+    const request = context.switchToHttp().getRequest();
+    const user = request.user;
+
+    return requiredRoles.some((role) => user.roles?.includes(role));
+  }
+
+}
+
+// Usage
+@Get('/admin')
+@Roles('admin', 'superadmin')
+@UseGuards(JwtAuthGuard, RolesGuard)
+public async getAdminPanel(): Promise<AdminResponse> { ... }
+\`\`\`
+
+## Telemetry Interceptor
+
+\`\`\`typescript
+@Injectable()
+export class OperationTelemetryInterceptor implements NestInterceptor {
+
+  private readonly _facade: ITelemetryFacade;
+
+  public intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
+    const handler = context.getHandler().name;
+    const cls = context.getClass().name;
+    // ... start span, capture duration, record outcome
+    return next.handle();
+  }
+
+}
+\`\`\`
+
+## How to Create a Custom Guard + Interceptor Pair
+
+### Step 1: Define the metadata key and decorator
+
+\`\`\`typescript
+export const RATE_LIMIT_METADATA = 'rate_limit';
+export const RateLimit = (maxRequests: number) => SetMetadata(RATE_LIMIT_METADATA, maxRequests);
+\`\`\`
+
+### Step 2: Create the guard
+
+Read metadata via \`Reflector\`, check the condition, return boolean.
+
+### Step 3: Create the interceptor (optional)
+
+Use \`tap()\` in the RxJS pipeline to perform post-handler side effects.
+
+### Step 4: Register in the module
+
+Export guard and interceptor from the library module so consumers can apply them.
+
+## Rules
+
+1. **Guards decide access** — return \`true\` or \`false\`, never throw directly.
+2. **Interceptors handle side effects** — recording, logging, transforming responses.
+3. **Metadata decorators are the glue** — they attach config to handlers, read by guards/interceptors.
+4. **Auth guards extend Passport's AuthGuard** — e.g. \`AuthGuard('jwt')\`.
+5. **Feature guards delegate to ports** — the guard itself holds no business logic.
+6. **Guard order matters** — \`@UseGuards(AuthGuard, FeatureGuard)\`: auth runs first.
+7. **Interceptors use \`tap()\`** for post-handler logic, \`map()\` for response transformation.
+`;
+//# sourceMappingURL=guardPattern.js.map

package/src/knowledge/mappingPattern.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Static knowledge content for the Archipel mapping pattern.
+ * Returned by the get-mapping-pattern tool.
+ */
+export declare const MAPPING_PATTERN_KNOWLEDGE = "# Archipel Mapping Pattern\n\n## Overview\n\nIn Archipel, all object-to-object mapping goes through a central **MappingService** with\n**branded, type-safe mapping keys**. This guarantees compile-time type safety: the key\nencodes both the input and output type, so calling `mappingService.map(KEY, input)` is\nstatically checked \u2014 the compiler verifies that `input` matches the key's input type and\ninfers the return type automatically.\n\n**Rule:** Services MUST NOT inline-create response objects. They return entities.\nControllers use the MappingService to convert entities to response DTOs.\n\n## Core Types\n\n### IMappingKey<TInput, TOutput>\n\n```typescript\nexport interface IMappingKey<TInput, TOutput> {\n  readonly _brand: 'MappingKey';\n  readonly _input: TInput;\n  readonly _output: TOutput;\n  readonly key: string;\n}\n```\n\nThe `_input` and `_output` fields are phantom types \u2014 they exist only for compile-time\ntype encoding and are never accessed at runtime.\n\n### createMappingKey<TInput, TOutput>\n\n```typescript\nimport { createMappingKey } from '@breadstone/archipel-platform-core';\n\nexport const PRODUCT_MAPPING_KEY = createMappingKey<IProductMappingInput, ProductResponse>('food.product');\n```\n\nThe string argument `'food.product'` is the unique registry key. Convention:\n`<domain>.<entity>` in lowercase dot-notation.\n\n## MappingService API\n\n```typescript\n// Key-based mapping (preferred)\nconst response = mappingService.map(PRODUCT_MAPPING_KEY, input);\n// \u2192 TOutput is inferred from the key, TInput is validated\n\n// Safe variant (returns undefined if not registered)\nconst maybeResponse = mappingService.tryMap(PRODUCT_MAPPING_KEY, input);\n\n// Type-based mapping (alternative)\nconst response = mappingService.mapTypes(sourceInstance, DestinationClass);\nconst responses = mappingService.mapTypesArray(sourceArray, DestinationClass);\n```\n\n## How to Create a Mapping\n\n### Step 1: Define the input interface\n\nThe input interface represents the shape of data coming from the repository query.\nProperty names MUST match the Prisma select shape exactly.\n\n```typescript\n// models/mapping-inputs/IProductMappingInput.ts\nexport interface IProductMappingInput {\n  readonly id: string;\n  readonly barcode: string;\n  readonly name: string;\n  readonly categoryId: string;\n  readonly createdAt: Date;\n}\n```\n\n### Step 2: Create a branded mapping key\n\nEach key is an **exported constant** \u2014 never inline magic strings.\n\n```typescript\n// constants/MappingKeys.ts\nimport { createMappingKey } from '@breadstone/archipel-platform-core';\nimport { IProductMappingInput } from '../models/mapping-inputs/IProductMappingInput';\nimport { ProductResponse } from '../dtos/ProductResponse';\n\nexport const PRODUCT_MAPPING_KEY = createMappingKey<IProductMappingInput, ProductResponse>('food.product');\n```\n\n### Step 3: Create a mapping profile\n\nA profile extends `MappingProfileBase` and registers one or more mappings via the builder.\n\n```typescript\n// mappers/ProductMappingProfile.ts\nimport { MappingProfileBase, IMappingBuilder } from '@breadstone/archipel-platform-core';\nimport { PRODUCT_MAPPING_KEY } from '../constants/MappingKeys';\nimport { IProductMappingInput } from '../models/mapping-inputs/IProductMappingInput';\nimport { ProductResponse } from '../dtos/ProductResponse';\n\nexport class ProductMappingProfile extends MappingProfileBase {\n\n  // #region Methods\n\n  public configure(builder: IMappingBuilder): void {\n    builder.createKeyedMap(PRODUCT_MAPPING_KEY, (input: IProductMappingInput) => {\n      const response = new ProductResponse();\n      response.id = input.id;\n      response.barcode = input.barcode;\n      response.name = input.name;\n      response.categoryId = input.categoryId;\n      response.createdAt = input.createdAt;\n\n      return response;\n    });\n  }\n\n  // #endregion\n\n}\n```\n\n### Step 4: Register the profile in the module\n\n```typescript\nimport { MappingModule } from '@breadstone/archipel-platform-core';\nimport { ProductMappingProfile } from './mappers/ProductMappingProfile';\n\n@Module({\n  imports: [\n    MappingModule.withProfiles([ProductMappingProfile]),\n  ],\n})\nexport class ProductModule {}\n```\n\n### Step 5: Use in controller (NOT in service)\n\n```typescript\n@Controller('/products')\nexport class ProductController {\n\n  // #region Fields\n\n  private readonly _productService: ProductService;\n  private readonly _mappingService: MappingService;\n\n  // #endregion\n\n  // #region Ctor\n\n  public constructor(productService: ProductService, mappingService: MappingService) {\n    this._productService = productService;\n    this._mappingService = mappingService;\n  }\n\n  // #endregion\n\n  // #region Methods\n\n  @Get(':id')\n  public async getProduct(@Param('id') id: string): Promise<ProductResponse> {\n    const entity = await this._productService.findById(id);\n\n    return this._mappingService.map(PRODUCT_MAPPING_KEY, entity);\n  }\n\n  @Get()\n  public async listProducts(): Promise<ProductResponse[]> {\n    const entities = await this._productService.findAll();\n\n    return entities.map((e) => this._mappingService.map(PRODUCT_MAPPING_KEY, e));\n  }\n\n  // #endregion\n\n}\n```\n\n## MappingBuilder Methods\n\nThe builder supports two registration flavors:\n\n### createKeyedMap (preferred)\n\n```typescript\nbuilder.createKeyedMap(SOME_MAPPING_KEY, (input: TInput) => {\n  const output = new TOutput();\n  // ... map fields\n  return output;\n});\n```\n\n### createMap (type-based)\n\n```typescript\nbuilder.createMap(SourceClass, DestinationClass, (source: SourceClass) => {\n  const dest = new DestinationClass();\n  // ... map fields\n  return dest;\n});\n```\n\n## Error Handling\n\n- `MappingNotRegisteredError` \u2014 thrown when a keyed mapping is not found\n- `TypeMappingNotRegisteredError` \u2014 thrown when a type-based mapping is not found\n- Both extend `MappingError` with a machine-readable `code` field\n\n## Rules\n\n1. **Mapping keys MUST be exported constants** \u2014 never inline magic strings in services or controllers.\n2. **Services return entities, controllers map to responses** \u2014 services MUST NOT create response objects.\n3. **One mapping key per entity\u2192response pair** \u2014 use descriptive dot notation for the key string.\n4. **Input interfaces match Prisma select shape** \u2014 property names must align exactly.\n5. **Profiles extend MappingProfileBase** and are registered via `MappingModule.withProfiles()`.\n6. **Use `createKeyedMap` over `createMap`** \u2014 branded keys provide better type safety.\n7. **Mapping functions instantiate response classes** \u2014 use `new ResponseClass()` and assign fields.\n";
+export declare const MAPPING_PATTERN_WITH_CONTEXT: (entityName: string, fields: string[], responseName: string) => string;