@sezzlee/sdk-nestjs 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaan Akın
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,361 @@
-# Temporary Holding Version
+# @sezzlee/sdk-nestjs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An MCP layer that embeds into your existing NestJS backend. It exposes your endpoints to agents as
+a search-first tool catalog and replays each call through **your own** pipeline, so your guards,
+pipes and interceptors keep running unchanged. Not a gateway, not duplicated business logic.
+
+> Status: `0.2.0`, alpha; breaking changes are possible. [samples/demo-api](samples/demo-api) is
+> the reference wiring.
+
+## Requirements
+
+- NestJS 10 or later (`@nestjs/common`, `@nestjs/core`), dev-tested against 11.x
+- `@modelcontextprotocol/server`, `@modelcontextprotocol/node` and `@modelcontextprotocol/express`
+  2.0 or later, `rxjs` 7 and `zod` 4
+- `class-validator` and `class-transformer` are optional; when installed, their decorators shape
+  the argument schemas
+- Node 22 or later, Express as the HTTP adapter
+
+Peers are peers on purpose: sezzlee uses your Nest and your MCP SDK, not its own copies.
+
+## 1. Install
+
+```bash
+pnpm add @sezzlee/sdk-nestjs
+```
+
+## 2. Wiring — three pieces
+
+The .NET SDK is three method calls. This one is three _pieces_, because a Nest controller is your
+code and a module cannot add a route to it.
+
+**The module.** `forRoot` takes a callback that **mutates** an options instance — not an options
+literal. Passing `{ visibility: { tier: "probe" } }` configures nothing.
+
+```ts
+@Module({
+  imports: [
+    SezzleeModule.forRoot((options) => {
+      options.visibility.tier = "probe";
+    }),
+  ],
+  controllers: [OrdersController, McpController],
+})
+export class AppModule {}
+```
+
+`forRootAsync({ imports, inject, useFactory })` is the async form. The module is `@Global()`, so
+its providers are available without importing it again.
+
+**The MCP controller.** Copy this; the seven injections are not guessable.
+
+```ts
+@Controller()
+export class McpController {
+  constructor(
+    private readonly streamableHttp: SezzleeStreamableHttp,
+    private readonly catalog: SezzleeCatalog,
+    private readonly dispatcher: SezzleeDispatcher,
+    private readonly visibility: CallerVisibilityProvider,
+    @Inject(extensionTokens.invokeResultMapper)
+    private readonly mapper: InvokeResultMapper,
+    @Inject(extensionTokens.callerScopeResolver)
+    private readonly scopes: CallerScopeResolver,
+    @Inject(SEZZLEE_OPTIONS) private readonly options: SezzleeOptions,
+  ) {}
+
+  @All("mcp")
+  async handle(@Req() req: Request, @Res() res: Response): Promise<void> {
+    await this.streamableHttp.handle(req, res, () => {
+      const server = new McpServer({ name: "your-api", version: "0.0.0" });
+      registerSezzleeTools(server, {
+        catalog: this.catalog,
+        dispatcher: this.dispatcher,
+        mapper: this.mapper,
+        visibility: this.visibility,
+        scopes: this.scopes,
+        options: this.options,
+      });
+      return server;
+    });
+  }
+}
+```
+
+`@All` rather than `@Post`: the default session mode is `stateless`, and the transport wants to
+answer `GET`/`DELETE` with `405` itself instead of letting Nest return `404`.
+
+**The bootstrap.**
+
+```ts
+import "reflect-metadata"; // must be the first import in the process
+
+const app = await NestFactory.create(AppModule);
+app.useGlobalPipes(new ValidationPipe({ transform: true }));
+
+await app.init(); // before any app.get(...) / app.use(...)
+await app.listen(3000);
+```
+
+> **Order is critical.** `reflect-metadata` must be imported first, or the decorators in §3 store
+> nothing and your catalog comes up empty. And `await app.init()` must precede `app.use(...)` that
+> resolves a provider — `app.get(...)` throws before the container is initialized.
+
+## 3. Which endpoints become tools
+
+The default is **opt-in**: nothing is exposed until you mark it.
+
+```ts
+@Controller()
+@McpTool()
+export class OrdersController {
+  @Get("orders/:id")
+  @McpTool({ description: "Fetches one order by id." })
+  getOrder(@Param("id", ParseIntPipe) id: number): Order { ... }
+}
+```
+
+NestJS has no equivalent of ASP.NET's description metadata, so `@McpTool({ description })` is how
+an agent gets something to search against. Input schemas come from your `class-validator` DTOs and
+your pipes: `ParseIntPipe` yields an integer, `@Min`/`@Max` become `minimum`/`maximum`.
+
+A whole-object query binding is expanded into one argument per member, so the agent sees the
+filters:
+
+```ts
+class ListOrdersQuery {
+  @IsString() customerId!: string;
+  @IsString() @IsOptional() status?: string;
+  @IsInt() @Min(1) @IsOptional() page?: number;
+}
+
+@Get("orders")
+list(@Query() query: ListOrdersQuery) { ... }
+// arguments: customerId (required), status, page
+```
+
+The expansion needs a readable type. A member that cannot be expressed as a query parameter — a
+nested object, a dictionary — is omitted with an `unbound_query_object` warning. If **no** member
+can be read (`@Query() q: Record<string, unknown>`, or a DTO with no `class-validator` decorators)
+the endpoint is dropped with `unresolved_query_shape` rather than published as a tool that claims
+to take no filters. Decorate the type, declare `options.schema.typeShape`, or add the code to
+`options.diagnostics.downgrade` to publish it filterless anyway.
+
+A member whose name is already claimed by a path parameter or a named `@Query('x')`/`@Headers('x')`
+binding is omitted too, with a `query_member_shadowed` warning: the flat argument object has one
+slot per name and the explicit binding owns it. Rename the member, or bind it by name.
+
+### Routes
+
+Routes are composed by Nest's own route factory, so the descriptor's route is the path Nest
+actually serves: `setGlobalPrefix` (with its `exclude` list), `RouterModule.register({ path })`,
+URI versioning, controller path and method path. Two consequences worth knowing:
+
+- **A global prefix moves the protected-resource metadata.** Nest applies the prefix to middleware
+  paths too, so `/.well-known/oauth-protected-resource/mcp` becomes `/api/.well-known/...` and RFC
+  9728 discovery breaks. When `resourceServer` is set, sezzlee raises a fatal `prm_path_prefixed`
+  diagnostic naming the fix: `setGlobalPrefix("api", { exclude: ["/.well-known/oauth-protected-resource/mcp"] })`.
+- **Non-URI versioning is not carried into invocation.** With `HEADER`, `MEDIA_TYPE` or `CUSTOM`
+  versioning the version never enters the path, and the synthetic request sezzlee replays carries no
+  version header, so dispatch lands on the default version. URI versioning has no such gap.
+
+One operation bound to several routes — `@Controller(["orders", "purchases"])`, a legacy path kept
+alongside a new one, or one handler under two URI versions — stays **one tool**: the same code at
+two URLs is one operation, and two identical tools only dilute search. The invoked route is chosen
+deterministically (shortest, then ordinal), the folded routes are reported as `route_folded`, and
+they stay searchable so a query naming the compatibility path still finds the tool.
+
+At scale, invert it and exclude the exceptions:
+
+```ts
+SezzleeModule.forRoot((options) => {
+  options.selection.default = "include";
+});
+```
+
+Then `@McpIgnore()` on the endpoints or controllers you withhold.
+
+For a subtree that is categorically off limits — or one you cannot decorate, such as a generated
+or third-party controller — put the decision in configuration instead:
+
+```ts
+SezzleeModule.forRoot((options) => {
+  options.selection.default = "include";
+  options.selection.rules = [
+    { route: "/admin/**", decision: "exclude" },
+    { method: "POST", decision: "exclude" },
+  ];
+});
+```
+
+`*` stays inside one path segment and `**` crosses them, so `**` is the catch-all and `*` is not.
+Route matching is case-sensitive and a path parameter is matched as the literal `{id}` the template
+carries; `method` ignores case. Rules rank by how many fields they name, never by declaration
+order, and two equally specific rules that disagree fail the catalog with `ambiguous_selection`
+rather than one quietly winning. An attribute always outranks a rule, so a carve-out inside an
+excluded subtree goes on the endpoint.
+
+Visibility is **not** a security mechanism. A tool hidden from the catalog still runs only if your
+backend permits it; enforcement is always in your pipeline at invoke time.
+
+## 3b. Curating what the agent sees
+
+Your DTO was written for HTTP clients. `arguments` declares a different agent-facing surface over
+the same endpoint, without touching the DTO.
+
+```ts
+@Get("orders")
+@McpTool({
+  description: "Search your orders by keyword.",
+  arguments: curate<ListOrdersQuery>({
+    customerId: hidden.from("tenant"),
+    status: { description: "active | closed" },
+    page: { as: "page_number" },
+  }),
+})
+list(@Query() query: ListOrdersQuery) { ... }
+```
+
+The agent sends `page_number`; the request still goes out as `?page=`. It never sees `customerId`,
+and sending it is an `unknown_argument` error. The value comes from a provider you register once:
+
+```ts
+options.arguments.provide("tenant", (caller) => caller.claim("tid"));
+```
+
+`hidden.value(x)` writes a constant instead, and `hidden.omit()` sends nothing so your backend's own
+default stands. Rules can also live centrally — `options.arguments.curate(target, rules)` for
+controllers you cannot decorate, `seal` for a rule no decorator may override.
+
+**Curation is not enforcement.** Filling `customerId` from a token does not isolate tenants; your
+pipeline still decides. It changes what the agent has to think about, not what it may do.
+
+`@McpVariant({ name, description, arguments })` produces several tools from one handler. Both fields
+are required, because one description cannot honestly describe two differently curated tools.
+
+`@McpToolFamily({ parameter: "methodId", source: "..." })` publishes a handler that dispatches on a
+parameter as one tool per method. `options.families.provide(name, source)` supplies the members —
+key, name, description, body schema — loaded in `onApplicationBootstrap` and on every `reload()`,
+which now returns a promise; the key is written into the route and never reaches the agent. Full
+guide: the docs site's _How to expose a dispatching endpoint as one tool per method_.
+
+Full guide: the docs site's _How to curate the arguments an agent sees_.
+
+## 3c. Telling the agent what a tool returns
+
+`load_tool` publishes an `outputSchema` alongside `inputSchema`, so an agent can plan a chain of
+calls without making the first one. Nest has to be told what a handler returns: TypeScript erases
+generics, so an `async` handler reports `Promise` at runtime and a collection reports `Array`.
+
+```ts
+@Get("orders/:id")
+@McpTool({
+  description: "Fetches one order by id.",
+  responses: { 200: OrderResponse, 404: {} },
+})
+getOrder(@Param("id", ParseIntPipe) id: number): OrderResponse { ... }
+```
+
+Per status code: a DTO class, `[OrderResponse]` for a collection of it, `{ schema }` for a shape no
+class can express, or `{}` for a status with no body. A DTO needs class-validator decorators, the
+same as a request DTO.
+
+If you already write `@ApiOkResponse({ type: OrderResponse })`, it is read as a fallback, and a sync
+handler's plain class return type is read as a last resort. The declaration wins over both.
+
+Only one status becomes the schema — `200`, `201`, `202`, `204` in that order, then the lowest
+remaining `2xx`. A non-object root is wrapped under `result`, because MCP requires an object. Unlike
+the input side, read-only members are kept: they are what a response is made of.
+
+Full guide: the docs site's _How to tell the agent what a tool returns_.
+
+## 4. Visibility and guards
+
+This is the SDK's defining behaviour, and the thing most likely to surprise you.
+
+sezzlee asks every guard on an endpoint — global, controller and method — for a declaration, by
+looking for a `describeVisibility()` method. **If any guard lacks it, the endpoint is marked
+imperative and its visibility is `unknown` forever.**
+
+```ts
+@Injectable()
+export class OrdersReadGuard implements CanActivate {
+  canActivate(): boolean {
+    /* your real check, unchanged */ return true;
+  }
+
+  describeVisibility(): { anonymous: "no"; policies: string[] } {
+    return { anonymous: "no", policies: ["OrdersRead"] };
+  }
+}
+```
+
+`unknown` is not a denial: with the default `visibility.onUnknown: "show"` the tool still appears,
+flagged `authUncertain`. When the guards cannot declare themselves, `visibility.tier = "probe"`
+resolves them by really running them — at a cost. The full recipe, including
+`visibility.probeValues`, is in the docs site's
+_How to declare visibility for a NestJS guard_.
+
+## 5. Connecting an MCP client
+
+The endpoint speaks Streamable HTTP. `tools/list` returns only three meta-tools:
+
+| Tool           | Job                                        |
+| -------------- | ------------------------------------------ |
+| `search_tools` | Finds operations by keyword, returns cards |
+| `load_tool`    | Returns one operation's full input schema  |
+| `invoke_tool`  | Calls it                                   |
+
+The catalog is not dumped into `tools/list`: on a 700-endpoint backend that drowns the agent's
+context. The agent searches, then loads, then calls.
+
+`search_tools` takes `query`, `limit`, `detail` and `tags`. `tags` narrows the answer to operations
+carrying every tag listed, matched whole and insensitive to case and accents; every answer carries
+the vocabulary the caller may see, so the agent reads a tag rather than guessing one. Each operation
+is tagged with its controller name unless you say otherwise:
+
+```ts
+@McpTool({ name: "find_orders", tags: ["billing", "read"] })
+```
+
+A declaration replaces the controller-derived tag rather than adding to it, and `options.tags` sets
+the same thing centrally for controllers you cannot decorate. Tags are search text too, so changing
+them changes ranking — see the how-to on grouping operations.
+
+Words an agent may type that your operation's text does not contain go in `searchTerms`
+(`@McpTool({ searchTerms: ["sipariş"] })`, or `options.searchTerms` centrally): indexed like the
+description, never a filter key, never shown to the agent. To rank with your own retriever instead
+of BM25, bind a `ToolRanker` through `forRoot`'s overrides (`{ toolRanker: { useClass: MyRanker } }`);
+`options.search.rankerTimeoutMs` (10000 by default) and `options.search.onRankerFailure`
+(`"fallback"` or `"error"`) govern it. Visibility, the tag filter and the payload budget still apply
+to its answer — see the how-to on plugging in your own search.
+
+This repository ships a client:
+
+```bash
+SEZZLEE_BASE_URL=http://127.0.0.1:3000 SEZZLEE_AUTH=token SEZZLEE_USER=alice \
+  node sdks/nestjs/samples/agent-client/dist/main.js --scenario smoke --query "create order"
+```
+
+To protect `/mcp`, set `options.resourceServer` and the module installs bearer verification plus
+the RFC 9728 metadata handler for you.
+
+## 6. Troubleshooting
+
+| Symptom                                                     | Cause                                                               | Fix                                                                             |
+| ----------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `search_tools` always empty                                 | `selection.default` is `exclude` and nothing is decorated           | Add `@McpTool()`, or set `selection.default = "include"`                        |
+| Everything comes back `authUncertain`                       | A guard without `describeVisibility()`, or `tier` still declarative | Declare the guards, or set `visibility.tier = "probe"`                          |
+| Catalog empty, decorators appear to do nothing              | `reflect-metadata` not imported first                               | Make it the first import in `main.ts`                                           |
+| Startup throws resolving a provider                         | `app.use(...)` before `app.init()`                                  | `await app.init()` first                                                        |
+| No PRM document, 401 carries no pointer                     | `resourceServer` unset                                              | Set `options.resourceServer`; check `/.well-known/oauth-protected-resource/mcp` |
+| `GET /mcp` returns 405                                      | `transport.sessionMode` is `stateless` (the default)                | Expected. Use `POST`, or switch to `stateful`                                   |
+| Host will not boot, fatal diagnostic                        | `name_collision` / `ambiguous_selection` / `invalid_name`           | Read the codes in the log, then `options.diagnostics.downgrade`                 |
+| A tool is missing and `unresolved_query_shape` was reported | Its `@Query()` type carries no readable members                     | Decorate the DTO, declare `options.schema.typeShape`, or downgrade the code     |
+| PRM 404s under a global prefix                              | `prm_path_prefixed` — Nest prefixed the `.well-known` path          | Add the metadata path to `setGlobalPrefix`'s `exclude` list                     |
+
+## 7. What's next
+
+- The docs site: `pnpm --filter @sezzlee/docs dev` → `http://localhost:5180`
+- [samples/demo-api](samples/demo-api) — the same endpoint matrix as the .NET sample: anonymous,
+  identity-only, policy, role, imperative ownership, and a POST with path, query and body

package/dist/cache.d.ts

@@ -0,0 +1,18 @@
+import { type CacheTag, type CallerScope, type SezzleeCache } from "@sezzlee/core";
+import { SezzleeOptions, type OuterRequest } from "./options.js";
+export interface CallerScopeResolver {
+    resolve(outer: OuterRequest | undefined): CallerScope;
+}
+export declare class CarrierHashCallerScopeResolver implements CallerScopeResolver {
+    private readonly options;
+    constructor(options: SezzleeOptions);
+    resolve(outer: OuterRequest | undefined): CallerScope;
+}
+export declare const SEZZLEE_CACHE_INVALIDATOR: unique symbol;
+export declare class SezzleeCacheInvalidator {
+    private readonly cache;
+    constructor(cache: SezzleeCache);
+    invalidateCaller(scope: CallerScope): Promise<void>;
+    invalidateTag(tag: CacheTag): Promise<void>;
+    invalidateAll(): Promise<void>;
+}

package/dist/cache.js

@@ -0,0 +1,55 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { createCallerScope, deriveCallerScopeKey, digestInput, } from "@sezzlee/core";
+import { extensionTokens } from "./extension-points.js";
+import { SEZZLEE_OPTIONS, SezzleeOptions, } from "./options.js";
+let CarrierHashCallerScopeResolver = class CarrierHashCallerScopeResolver {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    resolve(outer) {
+        const carriers = [...this.options.identity.carriers];
+        const digest = digestInput(carriers, (name) => outer?.headers[name]);
+        return createCallerScope(deriveCallerScopeKey(digest));
+    }
+};
+CarrierHashCallerScopeResolver = __decorate([
+    Injectable(),
+    __param(0, Inject(SEZZLEE_OPTIONS)),
+    __metadata("design:paramtypes", [SezzleeOptions])
+], CarrierHashCallerScopeResolver);
+export { CarrierHashCallerScopeResolver };
+export const SEZZLEE_CACHE_INVALIDATOR = Symbol("SEZZLEE_CACHE_INVALIDATOR");
+let SezzleeCacheInvalidator = class SezzleeCacheInvalidator {
+    cache;
+    constructor(cache) {
+        this.cache = cache;
+    }
+    invalidateCaller(scope) {
+        return this.cache.removeScope(scope.key);
+    }
+    invalidateTag(tag) {
+        return this.cache.removeTag(tag);
+    }
+    invalidateAll() {
+        return this.cache.clear();
+    }
+};
+SezzleeCacheInvalidator = __decorate([
+    Injectable(),
+    __param(0, Inject(extensionTokens.cache)),
+    __metadata("design:paramtypes", [Object])
+], SezzleeCacheInvalidator);
+export { SezzleeCacheInvalidator };

package/dist/catalog.d.ts

@@ -0,0 +1,100 @@
+import { type OnApplicationBootstrap } from "@nestjs/common";
+import { ApplicationConfig, DiscoveryService, HttpAdapterHost, ModulesContainer } from "@nestjs/core";
+import { type ArgumentCuration, type CatalogBuild, type CatalogEntry as CoreCatalogEntry, type EndpointDescriptor, type ToolRanker } from "@sezzlee/core";
+import { type CatalogDiagnostic } from "./discovery/diagnostics.js";
+import { type DiscoveredEndpoint } from "./discovery/endpoint-discovery.js";
+import type { ArgumentRule } from "./decorators.js";
+import { type FamilyResolution } from "./families.js";
+import { type SezzleeOptions } from "./options.js";
+export { cleanTags } from "@sezzlee/core";
+export interface NestSource {
+    readonly controller: NewableFunction;
+    readonly handlerName: string;
+}
+export type CatalogEntry = CoreCatalogEntry<NestSource>;
+export interface CatalogSnapshot extends CatalogBuild<NestSource> {
+    readonly discovered: number;
+}
+type LoweredFamily = Extract<FamilyResolution, {
+    kind: "members";
+}>;
+export declare class SezzleeCatalog implements OnApplicationBootstrap {
+    private readonly discovery;
+    private readonly modules;
+    private readonly applicationConfig;
+    private readonly options;
+    private readonly adapterHost?;
+    private readonly toolRanker;
+    private snapshot;
+    private currentGeneration;
+    private readonly listeners;
+    private loads;
+    private pending;
+    constructor(discovery: DiscoveryService, modules: ModulesContainer, applicationConfig: ApplicationConfig, options: SezzleeOptions, adapterHost?: HttpAdapterHost | undefined, toolRanker?: ToolRanker | null);
+    get ranker(): ToolRanker | null;
+    get generation(): number;
+    get current(): CatalogSnapshot;
+    onChange(listener: () => void): () => void;
+    /**
+     * Rebuilds the catalog, loading family members first when any source is registered.
+     *
+     * Without a source the rebuild happens before this returns, as it always has. With one, reloads
+     * run one at a time, and a rebuild that would turn a valid catalog fatal is refused and the
+     * current catalog kept ([tool-families.md] §Membership): member data added under a name another
+     * tool already has would otherwise take every tool offline.
+     *
+     * @throws SezzleeCatalogError through the returned promise when the rebuild is refused
+     */
+    reload(): Promise<void>;
+    /**
+     * Loads family members once the application's own providers are ready, since a source usually
+     * reads from one of them. A catalog built earlier carries `family_not_loaded` and is rebuilt
+     * here, which signals `listChanged`.
+     */
+    onApplicationBootstrap(): Promise<void>;
+    private enqueue;
+    private commit;
+    get diagnostics(): readonly CatalogDiagnostic[];
+    find(name: string): CatalogEntry | undefined;
+    ensureValid(): void;
+    /**
+     * Guard: Express 5 defaults `query parser` to `simple`, which does not parse
+     * brackets — `?filter[status]=x` then arrives as one literal key and the DTO
+     * binds nothing. A tool that composes a filter the backend silently ignores
+     * returns an unfiltered result set, which is the failure
+     * `unresolved_query_shape` exists to prevent, so this is fatal rather than a
+     * warning. Only Express is checked: `getInstance().get` is a route
+     * registrar on Fastify, not a settings reader.
+     */
+    private reportUnparsedBrackets;
+    /**
+     * Guard: Express parses a body only for the media types a registered parser declares, and an
+     * unparsed body reaches the handler as `req.body === undefined` with no error (form-body-probe
+     * N6) — a tool the backend answers as if every field were absent. The default parsers are
+     * `jsonParser` and `urlencodedParser`, visible by name on the router stack (N7); a text body
+     * needs `app.useBodyParser('text')`. Only Express is checked, for `reportUnparsedBrackets`'s
+     * reason.
+     */
+    private lacksBodyParser;
+    private build;
+    private checkMetadataPath;
+    /**
+     * Applies the declaration ladder, least specific first, with sealed fields last.
+     *
+     * Merging is per argument and per field, so a global rule that hides a tenant identifier and a
+     * method-level rule that renames a page number both survive. A decorator wins a tie against a
+     * central rule of the same specificity: it is nearer the code and that is the reading a
+     * maintainer expects.
+     */
+    private curationFor;
+}
+/**
+ * Folds the decorator's declarations into the descriptor.
+ *
+ * Discovery reports facts; declarations are reduced here, the same way `toolName` and
+ * `containerPrefix` are. The curation list arrives resolved because the ladder that produces it
+ * needs the host's central rules, which are not a property of the endpoint; a family's members
+ * arrive already lowered, because they were loaded from a source rather than declared.
+ */
+export declare function declaredDescriptor(endpoint: DiscoveredEndpoint, curation: readonly ArgumentCuration[], tags?: readonly string[], family?: LoweredFamily): EndpointDescriptor;
+export declare function toCuration(rules: Readonly<Record<string, ArgumentRule>>): ArgumentCuration[];