@sezzlee/sdk-nestjs 0.2.0 → 0.2.1

package/README.md

@@ -4,7 +4,7 @@ An MCP layer that embeds into your existing NestJS backend. It exposes your endp
 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
+> Status: `0.2.1`, alpha; breaking changes are possible. [samples/demo-api](samples/demo-api) is
 > the reference wiring.
 
 ## Requirements
@@ -330,6 +330,13 @@ of BM25, bind a `ToolRanker` through `forRoot`'s overrides (`{ toolRanker: { use
 (`"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.
 
+When an operation's behaviour changes behind an unchanged schema, raise its revision
+(`@McpTool({ revision: 2 })` on the method, on the controller for every method in it, or
+`options.revision` for the whole catalog). The revision enters the tool version, so during a rolling
+deploy a call pinned to the old version is refused with `tool_changed` instead of running against
+the new behaviour. The levels add up rather than replacing one another — see the how-to on shipping
+a behaviour change mid-deploy.
+
 This repository ships a client:
 
 ```bash

package/dist/catalog.js

@@ -12,7 +12,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { Inject, Injectable, Optional, RequestMethod, } from "@nestjs/common";
 import { ApplicationConfig, DiscoveryService, HttpAdapterHost, ModulesContainer, } from "@nestjs/core";
-import { assertCatalogValid, buildCatalog, combineMarkers, matchesRoute, SezzleeTemplateError, textMediaType, urlEncodedMediaType, } from "@sezzlee/core";
+import { assertCatalogValid, buildCatalog, combineMarkers, declareRevision, matchesRoute, SezzleeTemplateError, textMediaType, urlEncodedMediaType, } from "@sezzlee/core";
 import { severityOf } from "./discovery/diagnostics.js";
 import { createRoutePaths, discoverEndpoints, modulePathOf, normalizeRoute, } from "./discovery/endpoint-discovery.js";
 import { loadFamilies, resolveFamily, } from "./families.js";
@@ -227,20 +227,41 @@ let SezzleeCatalog = class SezzleeCatalog {
             }
             return true;
         });
+        const catalogRevision = declareRevision("The catalog", { catalog: [{ value: this.options.revision, by: "options.revision" }] }, report)?.catalog;
         const built = buildCatalog(routed.map((endpoint) => {
-            const tags = endpoint.hints.tags ?? this.options.tags?.(endpoint.controller.name);
-            const searchTerms = endpoint.hints.searchTerms ??
-                this.options.searchTerms?.(endpoint.controller.name);
+            const container = endpoint.controller.name;
+            const owner = `${container}.${endpoint.handlerName}`;
+            const tags = endpoint.hints.tags ?? this.options.tags?.(container);
+            const searchTerms = endpoint.hints.searchTerms ?? this.options.searchTerms?.(container);
             return {
                 source: {
                     controller: endpoint.controller,
                     handlerName: endpoint.handlerName,
                 },
-                owner: `${endpoint.controller.name}.${endpoint.handlerName}`,
+                owner,
                 descriptor: endpoint.descriptor,
                 ...markersOf(endpoint),
                 ...(tags === undefined ? {} : { tags }),
                 ...(searchTerms === undefined ? {} : { searchTerms }),
+                revision: {
+                    catalog: [{ value: catalogRevision, by: "options.revision" }],
+                    container: [
+                        {
+                            value: endpoint.revisions.container,
+                            by: `@McpTool({ revision }) on ${container}`,
+                        },
+                        {
+                            value: this.options.containerRevision?.(container),
+                            by: "options.containerRevision",
+                        },
+                    ],
+                    operation: [
+                        {
+                            value: endpoint.revisions.operation,
+                            by: `@McpTool({ revision }) on ${owner}`,
+                        },
+                    ],
+                },
                 declare: (cleaned) => declaredDescriptor(endpoint, this.curationFor(endpoint), cleaned, families.get(endpoint)),
             };
         }), {

package/dist/decorators.d.ts

@@ -98,6 +98,13 @@ export interface McpToolOptions {
      * never a filter key and never shown to the agent ([search-semantics.md]).
      */
     readonly searchTerms?: readonly string[];
+    /**
+     * The behaviour revision at the level the decorator sits on: a method's covers that operation,
+     * a controller's every operation in it. Raised when behaviour changes behind an unchanged
+     * schema, it changes the tool version and nothing the agent reads ([metadata-contract.md]).
+     * The two levels never replace one another.
+     */
+    readonly revision?: number;
     /**
      * The body's media type, replacing the one discovery chooses. It is the host's own claim that a
      * parser for it is registered; when `@ApiConsumes` also lists types, it must be one of them.

package/dist/discovery/endpoint-discovery.d.ts

@@ -45,6 +45,10 @@ export interface DiscoveredEndpoint {
     readonly containerMarkers: readonly boolean[];
     readonly operationMarkers: readonly boolean[];
     readonly hints: McpToolOptions;
+    readonly revisions: {
+        readonly container: number | undefined;
+        readonly operation: number | undefined;
+    };
 }
 export declare function discoverEndpoints(controllers: readonly ControllerCandidate[], options?: DiscoveryOptions): DiscoveredEndpoint[];
 /** `RouterModule` writes the module path under a key scoped to the application instance, falling back to the bare key. */

package/dist/discovery/endpoint-discovery.js

@@ -95,6 +95,10 @@ function fromController(candidate, options) {
                 containerMarkers: containerMarkers.map((marker) => marker.include),
                 operationMarkers: operationMarkers.map((marker) => marker.include),
                 hints,
+                revisions: {
+                    container: declaredRevision(containerMarkers),
+                    operation: declaredRevision(operationMarkers),
+                },
             });
         }
     }
@@ -639,12 +643,21 @@ function argumentsOf(controller, handlerName) {
     return (Reflect.getMetadata(ROUTE_ARGS_METADATA, controller, handlerName) ??
         {});
 }
+function declaredRevision(markers) {
+    let revision;
+    for (const marker of markers) {
+        revision = marker.options.revision ?? revision;
+    }
+    return revision;
+}
 /**
- * Flat last-wins merge, except for curation.
+ * Flat last-wins merge, except for curation and the revision.
  *
  * `arguments` merges per argument and per field so a container-level rule that hides a tenant
  * identifier survives a method-level rule that only renames something else. A flat replacement
- * would silently unhide it.
+ * would silently unhide it. `revision` is kept out entirely: its levels are read apart
+ * ({@link declaredRevision}), because a method's revision replacing its controller's would hide a
+ * raised controller revision from that method's tool version.
  */
 function mergeHints(container, operation) {
     const merged = {};
@@ -652,7 +665,7 @@ function mergeHints(container, operation) {
     const variants = [];
     for (const marker of [...container, ...operation]) {
         for (const [key, value] of Object.entries(marker.options)) {
-            if (value === undefined) {
+            if (value === undefined || key === "revision") {
                 continue;
             }
             if (key === "arguments") {

package/dist/options.d.ts

@@ -195,6 +195,10 @@ export declare class SezzleeOptions {
     tags?: (container: string) => readonly string[] | undefined;
     /** Search vocabulary for a container the host cannot decorate, below a `@McpTool({ searchTerms })`. */
     searchTerms?: (container: string) => readonly string[] | undefined;
+    /** The behaviour revision of the whole catalog; raising it changes every tool version. */
+    revision?: number;
+    /** A behaviour revision for a container the host cannot decorate, below a `@McpTool({ revision })`. */
+    containerRevision?: (container: string) => number | undefined;
     schema?: TypeShapeBinderOptions;
     resourceServer?: SezzleeResourceServerOptions;
 }

package/dist/options.js

@@ -145,6 +145,10 @@ export class SezzleeOptions {
     tags;
     /** Search vocabulary for a container the host cannot decorate, below a `@McpTool({ searchTerms })`. */
     searchTerms;
+    /** The behaviour revision of the whole catalog; raising it changes every tool version. */
+    revision;
+    /** A behaviour revision for a container the host cannot decorate, below a `@McpTool({ revision })`. */
+    containerRevision;
     schema;
     resourceServer;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sezzlee/sdk-nestjs",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Embeds an MCP layer into an existing NestJS backend: search-first tool discovery over your real endpoints, dispatched through your own guards, pipes and interceptors.",
   "keywords": [
     "mcp",
@@ -41,7 +41,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@sezzlee/core": "^0.2.0"
+    "@sezzlee/core": "^0.2.1"
   },
   "peerDependencies": {
     "@modelcontextprotocol/express": ">=2.0.0",