@@ -0,0 +1,10 @@
+---
+'@objectstack/service-automation': patch
+---
+
+fix(service-automation): a connector instance whose upstream no longer matches its pin is degraded in its own words
+
+Clause-②: no
+Metadata-protocol: none
+
+A provider factory that throws `CONNECTOR_UPSTREAM_CHANGED` (the `mcp` provider does when an instance's `providerConfig.toolsSnapshot` does not match what the server serves) degrades the instance on the same 5 s → 5 min backoff as an unreachable upstream, but its log records now say what happened. The materializer's ERROR reads "… serves a tool definition that differs from its toolsSnapshot — instance registered degraded (no actions); re-checking with backoff, attempt N." instead of "upstream unavailable … retrying with backoff", and the engine's degrade WARN says the instance has no actions "until its upstream serves the definitions its pin names again" instead of "until its upstream is reachable". The instance's reason (`GET /api/v1/automation/connectors`, the `connector_action` refusal) is the factory's message, naming each changed tool, as before.
@@ -0,0 +1,10 @@
+---
+'@objectstack/spec': patch
+---
+
+feat(spec): `ConnectorUpstreamChangedError`, the marker for an upstream that no longer matches the instance's pin
+
+Clause-②: yes (widening)
+Metadata-protocol: none
+
+`@objectstack/spec/integration` exports `CONNECTOR_UPSTREAM_CHANGED`, `ConnectorUpstreamChangedError` and the structural check `isConnectorUpstreamChanged`, beside the upstream-unavailable and credential-rejected markers. A connector provider factory throws it when the upstream it contacted serves a definition that differs from a pin the instance declares. Today that is the `mcp` provider's `providerConfig.toolsSnapshot`: a pinned tool whose description or `inputSchema` changed, or a pinned tool the server no longer serves. The automation materializer degrades the instance with the factory's message as its reason and re-checks it on the same backoff as an outage, so a server that restores the pinned definition recovers it. `CONNECTOR_UPSTREAM_UNAVAILABLE` keeps its meaning: the upstream could not be reached. The code is registered in the error-code ledger under `@objectstack/spec`; no HTTP door answers with it.
@@ -0,0 +1,16 @@
+---
+'@objectstack/connector-mcp': minor
+---
+
+feat(connector-mcp): `providerConfig.toolsSnapshot` pins each tool of an `mcp` instance by name
+
+Clause-②: yes (widening)
+Metadata-protocol: added
+
+An `mcp` instance's `include` decides which tools it exposes. Until now nothing noticed when the server rewrote one of them, for example a new description that steers an agent or an `inputSchema` that asks for more than it did. `providerConfig.toolsSnapshot` is a record of tool name → the sha256 of that tool's definition. It is keyed by tool name, like `include`, and the two compose.
+
+- **The digest.** sha256, lowercase hex, of the UTF-8 canonical JSON of `{ name, description, inputSchema }` from the tool's `tools/list` entry. A member the server does not send is left out. Canonical JSON sorts object keys in UTF-16 code-unit order at every depth, keeps array order, writes primitives as `JSON.stringify` does and has no whitespace: the RFC 8785 (JCS) form for values read from JSON. `computeMcpToolsSnapshot(tools)` and `mcpToolDigest(tool)` are exported and are the functions the check uses.
+- **The check.** On every materialization each pinned tool is hashed and compared on its own. A pinned tool served with a different description or `inputSchema`, or no longer served, degrades the instance: the provider throws `ConnectorUpstreamChangedError` (`CONNECTOR_UPSTREAM_CHANGED`), not the upstream-unavailable marker, so the logs say the pin did not match rather than that the server is down. Its reason names each such tool and the digest the server now serves, and none of the instance's tools are exposed. The instance is re-checked on the retry backoff and recovers once the server serves the pinned definitions again. An edited pin re-materializes it at once. A pinned tool that `include` also lists is reported by the pin when the server stops serving it, not as an `include` typo. When the instance's own credential reached the server (its `auth` over http), a pinned tool the server does not list takes the credential path instead (`ConnectorCredentialRejectedError`, 403, both causes named, a stored credential marked `rejected`), since the server may list only the tools that credential may use; a served pinned tool that hashes differently is still `CONNECTOR_UPSTREAM_CHANGED`.
+- **Refused before connecting.** A `toolsSnapshot` that is not a record of tool name → 64 lowercase hex characters fails the boot, and so does a pin on a tool `include` leaves out, since that pin would never be checked.
+- Without `toolsSnapshot`, an instance behaves exactly as before. A tool the pin does not name is not checked.
+- `McpConnectorOptions.include` now also receives the tool's `tools/list` entry as a second argument. An existing one-argument predicate is unaffected.
@@ -216,8 +216,9 @@ says which media type it accepts.
 
 ### `provider: 'mcp'` — one action per tool
 
-Config: **`transport`** (required) and **`include`** (optional tool-name
-allowlist — only the listed tools become actions):
+Config: **`transport`** (required), **`include`** (optional tool-name
+allowlist — only the listed tools become actions) and **`toolsSnapshot`**
+(optional per-tool pin, [below](#pinning-tools-toolssnapshot)):
 
 - `{ kind: 'http', url, headers? }` — a remote MCP server over streamable
   HTTP. Resolved `auth` is folded into the request headers; a grant-bearing
@@ -274,6 +275,73 @@ failing the boot, and its reason names both causes: a credential without the
 scopes those tools need, or a declaration naming a tool the server does not
 have. Leave `include` out to expose every tool.
 
+#### Pinning tools: `toolsSnapshot`
+
+`include` decides *which* tools an instance exposes; it cannot tell you when
+the server rewrites one of them — a new description that steers an agent, or
+an `inputSchema` that asks for more than it did. `toolsSnapshot` pins each tool
+you depend on: a record of tool name → the sha256 of that tool's definition.
+It is keyed by tool name, like `include`, and the two compose.
+
+{/* os:check */}
+```typescript
+import { defineConnector } from '@objectstack/spec/integration';
+
+export const PinnedSearchConnector = defineConnector({
+  name: 'pinned_search',
+  label: 'Pinned Search (MCP)',
+  type: 'api',
+  provider: 'mcp',
+  providerConfig: {
+    transport: { kind: 'http', url: 'https://mcp.example.com/mcp' },
+    include: ['web_search', 'fetch_page'],
+    toolsSnapshot: {
+      web_search: '08171ae4ba3e1cc962cad9723c755a62c0785d8ecc241a66f08864184366a990',
+      fetch_page: 'e8478992ffab43667be21a009ae297e3b4e36c7e9b2d3eb26b2ce307fef9cc78',
+    },
+  },
+});
+```
+
+A tool's digest is the sha256, in lowercase hex, of the UTF-8 **canonical
+JSON** of `{ name, description, inputSchema }` taken from its `tools/list`
+entry; a member the server does not send is left out (it is not hashed as
+`null`), and no other member (`outputSchema`, annotations) is hashed.
+Canonical JSON is: object members sorted by key in UTF-16 code-unit order
+(JavaScript's default string sort), at every depth; array elements in their
+order; strings, numbers, booleans and `null` written exactly as
+`JSON.stringify` writes them; no whitespace. For values read from JSON that is
+the RFC 8785 (JCS) form, so any JCS implementation reproduces it. In code,
+`computeMcpToolsSnapshot(tools)` from `@objectstack/connector-mcp` builds the
+record from a tool list with the same function the check uses.
+
+On every materialization each pinned tool is hashed and compared on its own:
+
+- Every pinned tool served with its pinned definition — the instance
+  materializes as usual.
+- A pinned tool served with a different description or `inputSchema`, or no
+  longer served at all — the instance registers **degraded** and exposes none
+  of its tools. Its reason names each such tool, with the digest the server
+  now serves, and the logs say the pin did not match (the provider throws
+  `CONNECTOR_UPSTREAM_CHANGED`, not the unreachable-server marker). The
+  instance is re-checked on the retry backoff, so a server that
+  serves the pinned definitions again recovers it on its own; to accept the
+  change, review it and set the pin to the served digest (the edit
+  re-materializes the instance at once). This holds for a pinned tool
+  `include` also lists: once pinned, a tool the server stops serving is
+  reported by the pin, not as an `include` typo. When the instance's own
+  credential reached the server (its `auth` over http), a pinned tool the
+  server does not list may be one hidden from that credential, so it is
+  degraded as a credential the upstream refuses instead, naming both causes —
+  a served tool that hashes differently is still reported by the pin.
+- A tool the pin does not name is not checked. Pin every tool you depend on,
+  and keep tools the server adds out with `include`.
+
+A `toolsSnapshot` that is not a record of tool name → 64 lowercase hex
+characters fails the boot before connecting, and so does a pinned tool that
+`include` leaves out — the instance never exposes it, so its pin would never be
+checked.
+
 <Callout type="warn">
 **Declarative stdio transports are denied by default.** Materializing one
 spawns a local process *from metadata* — which a runtime Studio publish can
@@ -794,6 +862,7 @@ retry):
 | Instance `name` collides with a plugin-registered connector | **Hard boot error** — there is no silent precedence between the two worlds |
 | stdio transport without host opt-in | **Hard boot error** with the `declarativeStdio` fix inline — a security rejection is never retried |
 | MCP server unreachable / `tools/list` fails; remote spec URL unreachable or transiently failing (408/429/5xx) | **Not fatal**: the instance registers **degraded** (visible on `GET /api/v1/automation/connectors` with the reason), dispatches fail with that reason, and the platform retries on a 5s→5min backoff — recovery is automatic |
+| An `mcp` instance's `toolsSnapshot` does not match what the server serves (a pinned tool's description or `inputSchema` changed, or a pinned tool is no longer listed) | **Not fatal**: the instance registers **degraded** with no actions, its reason naming each tool and the digest it now serves, and the logs say "serves a tool definition that differs from its toolsSnapshot" (`CONNECTOR_UPSTREAM_CHANGED`); it is re-checked on the same backoff and recovers once the server serves the pinned definitions again — or set the pin to the reviewed digest |
 | A retry of a degraded instance reaches the upstream and meets a configuration fault (an `include` naming a tool or operation the upstream does not offer; on an `mcp` instance that sends a static credential, the credential row above applies instead) | **Not fatal**: the instance stays **degraded**, now with the configuration reason, and is **not retried** — dispatches fail saying to edit its declaration; an edit of the entry (or a restart) re-attempts it |
 | Wrong spec URL (other 4xx) or unparseable document | Configuration fault — **hard boot error** |
 | An `openapi` operation's parameter declares a `style` OpenAPI 3.x does not define for its location (`deepObject` on a path parameter, `form` on a header) | Configuration fault — **hard boot error** naming the operation and the parameter; correct the document or leave the operation out of `include` |
 
@@ -356,7 +356,7 @@ const result = AutomationApiErrorCode.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +355 more>` | ✅ | The inner refusal's code in its WIRE spelling - the ADR-0112 member a record save of the same write answers in `error.code` (e.g. `UNIQUE_VIOLATION`); the closed set `ApiErrorSchema.code` parses against |
+| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +356 more>` | ✅ | The inner refusal's code in its WIRE spelling - the ADR-0112 member a record save of the same write answers in `error.code` (e.g. `UNIQUE_VIOLATION`); the closed set `ApiErrorSchema.code` parses against |
 | **message** | `string` | ✅ | The inner refusal's own diagnostic text, verbatim, without the node and operation prefixes the run's failure text adds |
 
 ### Allowed Values: `FlowInnerRefusal.code`
@@ -456,6 +456,7 @@ const result = AutomationApiErrorCode.parse(data);
 * `CONFLICT`
 * `CONFLICTING_MAPPING`
 * `CONNECTOR_CREDENTIAL_REJECTED`
+* `CONNECTOR_UPSTREAM_CHANGED`
 * `CONNECTOR_UPSTREAM_UNAVAILABLE`
 * `CREATE_FAILED`
 * `CUBE_NOT_FOUND`
 
@@ -28,7 +28,7 @@ const result = ApiErrorSchema.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +355 more>` | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
+| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +356 more>` | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
 | **declaredCode** | `string` | optional | The producer-declared code, verbatim, when it is not a member of the closed `code` vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
 | **message** | `string` | ✅ | Readable error message |
 | **userMessage** | `string` | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces `message`. |
@@ -135,6 +135,7 @@ const result = ApiErrorSchema.parse(data);
 * `CONFLICT`
 * `CONFLICTING_MAPPING`
 * `CONNECTOR_CREDENTIAL_REJECTED`
+* `CONNECTOR_UPSTREAM_CHANGED`
 * `CONNECTOR_UPSTREAM_UNAVAILABLE`
 * `CREATE_FAILED`
 * `CUBE_NOT_FOUND`
 
@@ -302,6 +302,7 @@ const result = ErrorCode.parse(data);
 * `CONFLICT`
 * `CONFLICTING_MAPPING`
 * `CONNECTOR_CREDENTIAL_REJECTED`
+* `CONNECTOR_UPSTREAM_CHANGED`
 * `CONNECTOR_UPSTREAM_UNAVAILABLE`
 * `CREATE_FAILED`
 * `CUBE_NOT_FOUND`
 
@@ -40,3 +40,8 @@ export {
     type McpProviderDeps,
     type McpDeclarativeStdioPolicy,
 } from './mcp-provider.js';
+export {
+    computeMcpToolsSnapshot,
+    mcpToolDigest,
+    type McpToolsSnapshot,
+} from './tool-snapshot.js';
@@ -109,8 +109,13 @@ export interface McpConnectorOptions {
     icon?: string;
     /** How to reach the MCP server. */
     transport: McpTransport;
-    /** Only expose tools whose name matches (allowlist) — keeps the palette lean. */
-    include?: (toolName: string) => boolean;
+    /**
+     * Only expose tools whose name matches (allowlist) — keeps the palette lean.
+     * Called once per listed tool with its name and its `tools/list` entry as
+     * the server served it (the `mcp` provider hashes the entry to check a
+     * `toolsSnapshot` pin).
+     */
+    include?: (toolName: string, tool: McpToolDescriptor) => boolean;
     /** Identifies this client to the MCP server during the handshake. */
     clientInfo?: { name: string; version: string };
     /**
@@ -282,7 +287,7 @@ export async function createMcpConnector(opts: McpConnectorOptions): Promise<Mcp
     }
 
     const include = opts.include ?? (() => true);
-    const selected = tools.filter((t) => include(t.name));
+    const selected = tools.filter((t) => include(t.name, t));
 
     const name = opts.name ?? slugify(opts.label ?? 'mcp');
     const label = opts.label ?? titleize(name);