@lerianstudio/matcher-mcp 1.0.0 → 1.1.0

package/dist/tools/ingestion/upload.js

@@ -0,0 +1,166 @@
+// `ingestion_upload` — curated POST
+// /v1/imports/contexts/{contextId}/sources/{sourceId}/upload.
+//
+// The backend endpoint is multipart/form-data, which a JSON MCP tool can't
+// carry directly. This tool accepts the file body one of two ways and the
+// relay rebuilds the real multipart request either way: wrap the bytes in a
+// `FormData` and let `matcher/client.ts`'s FormData branch hand it to `fetch`
+// untouched (no JSON.stringify, no content-type override — the runtime sets
+// the multipart boundary itself).
+//
+//   - `contentBase64`: the file inline, base64-encoded. Fine for small files,
+//     but base64-in-a-tool-call does NOT scale — an LLM client must emit the
+//     whole encoded string in its OUTPUT tokens, and base64 inflates bytes by
+//     ~33% on top of that (a 1000-row file is easily ~150k tokens). Practical
+//     ceiling: the relay's inbound JSON body cap (1 MiB default,
+//     MAX_BODY_BYTES override) means raw files up to ~750 KB upload cleanly.
+//   - `fileUrl`: a URL to the file. The RELAY fetches the bytes server-side
+//     (see fetch-source.ts) — the client only ever emits a short URL, so this
+//     is the path for real files. The fetch is SSRF-guarded: only hostnames
+//     in MCP_UPLOAD_ALLOWED_HOSTS (exact match, empty by default) are
+//     reachable, redirects are rejected, and the response is size-capped by
+//     MCP_UPLOAD_MAX_FETCH_BYTES.
+//
+// Exactly one of the two must be provided — validated in the handler (Huma's
+// inputSchema is a raw Zod shape, not a refinable ZodObject, so cross-field
+// "exactly one of" can't live in the schema itself).
+//
+// Field order matters: `format` MUST be appended BEFORE `file`. The backend's
+// streaming multipart parser binds the declared format from whichever field
+// arrives first; if `file` arrives first it falls back to inferring the
+// format from the filename extension, which rejects e.g. a camt053 upload
+// with `400 MTCH-0308`. See ui/scripts/seed-demo-client.mjs `uploadFile` for
+// the same contract used by the demo seeder.
+//
+// contextId and sourceId are routing path params, not tenant fields — matcher
+// validates both against the relayed token's tenant. No tenant field is
+// accepted here either.
+import { z } from 'zod';
+import { loadConfig } from '../../config.js';
+import { fetchSourceFile } from './fetch-source.js';
+import { contextSourceUploadPath, dispatchIngestion } from './shared.js';
+/** Declared parse formats the backend accepts for an ingestion upload. */
+const UPLOAD_FORMATS = ['csv', 'json', 'xml', 'camt053'];
+/** Zod raw shape for `ingestion_upload` input — path ids + format + file. */
+export const ingestionUploadInputShape = {
+    contextId: z
+        .string()
+        .min(1)
+        .describe('The reconciliation context id (UUID). Routing path param, not a tenant ' +
+        'field. The context MUST be ACTIVE — uploading to a DRAFT context is ' +
+        'rejected with 403 "context is not active".'),
+    sourceId: z
+        .string()
+        .min(1)
+        .describe('The source id (UUID) within the context to upload into. Must already ' +
+        'exist (create it first with source_create).'),
+    format: z
+        .enum(UPLOAD_FORMATS)
+        .describe('The declared parse format of the file: csv | json | xml | camt053. ' +
+        'Sent as the first multipart field — matcher binds the format from it ' +
+        'before reading the file, so always pass the true format rather than ' +
+        'relying on filename-extension inference.'),
+    filename: z
+        .string()
+        .min(1)
+        .describe('The original file name (e.g. "transactions.csv"), sent as the ' +
+        'multipart filename for the file part.'),
+    contentBase64: z
+        .string()
+        .base64()
+        .optional()
+        .describe('The file bytes, base64-encoded. For SMALL files only — base64 inflates ' +
+        'bytes by ~33% and the LLM client must emit the whole encoded string ' +
+        'as output tokens. The relay\'s inbound JSON body is capped (1 MiB by ' +
+        'default, MAX_BODY_BYTES env override), so raw files up to ~750 KB ' +
+        'upload cleanly under the default. Exactly one of contentBase64 / ' +
+        'fileUrl is required; for real files prefer fileUrl.'),
+    fileUrl: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('A URL the RELAY fetches the file from server-side — the client sends ' +
+        'only this short URL, not the file bytes, so this is the path for ' +
+        'real files (no output-token inflation). The fetch is SSRF-guarded: ' +
+        'only hostnames listed in MCP_UPLOAD_ALLOWED_HOSTS are reachable ' +
+        '(empty allowlist by default — every host is rejected until an ' +
+        'operator opts one in), redirects are rejected, and the response is ' +
+        'capped at MCP_UPLOAD_MAX_FETCH_BYTES (50 MiB default). Exactly one ' +
+        'of contentBase64 / fileUrl is required.'),
+};
+/**
+ * Register `ingestion_upload`. Resolves the file bytes from exactly one of
+ * `contentBase64` (decode) or `fileUrl` (SSRF-guarded server-side fetch — see
+ * fetch-source.ts), then rebuilds a `FormData` with `format` appended before
+ * `file` (order is load-bearing — see module comment) and dispatches the POST
+ * through the shared fail-closed relay; a matcher error (e.g. 403 inactive
+ * context, 400 malformed file) surfaces via the shared toToolError.
+ */
+export function registerIngestionUploadTool(server) {
+    server.registerTool('ingestion_upload', {
+        description: 'Upload a file into a source for ingestion. Provide the file body ' +
+            'via EXACTLY ONE of two ways: (1) contentBase64 — the file inline as ' +
+            'base64 in JSON, for SMALL files only (raw files up to ~750 KB; ' +
+            'larger payloads burn the calling LLM\'s output tokens and risk the ' +
+            'relay\'s inbound body cap). (2) fileUrl — a URL the relay fetches ' +
+            'server-side, so the client sends only the short URL; this is the ' +
+            'path for real files. fileUrl fetches are restricted to an explicit ' +
+            'hostname allowlist (MCP_UPLOAD_ALLOWED_HOSTS, empty by default) and ' +
+            'size-capped (MCP_UPLOAD_MAX_FETCH_BYTES); a non-allowlisted host is ' +
+            'rejected before any network call. Either way the relay rebuilds the ' +
+            'multipart/form-data upload the matcher backend expects. ' +
+            'Prerequisites: the context must be ACTIVE and the sourceId must ' +
+            'already exist. No tenant field is accepted. Returns the 202 job ' +
+            'response, or a structured RFC 9457 error (e.g. 403 if the context ' +
+            'is not ACTIVE).',
+        inputSchema: ingestionUploadInputShape,
+    }, async (args, extra) => {
+        const hasBase64 = args.contentBase64 !== undefined;
+        const hasFileUrl = args.fileUrl !== undefined;
+        if (hasBase64 === hasFileUrl) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: 'ingestion_upload requires exactly one of contentBase64 or ' +
+                            `fileUrl, got ${hasBase64 ? 'both' : 'neither'}.`,
+                    },
+                ],
+            };
+        }
+        let bytes;
+        if (hasBase64) {
+            bytes = Buffer.from(args.contentBase64, 'base64');
+        }
+        else {
+            const cfg = loadConfig();
+            try {
+                bytes = await fetchSourceFile(args.fileUrl, {
+                    allowedHosts: cfg.uploadAllowedHosts,
+                    maxBytes: cfg.uploadMaxFetchBytes,
+                    timeoutMs: cfg.timeoutMs,
+                });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : 'unknown error';
+                return {
+                    isError: true,
+                    content: [
+                        { type: 'text', text: `failed to fetch fileUrl: ${message}` },
+                    ],
+                };
+            }
+        }
+        const form = new FormData();
+        // 'format' MUST precede 'file' — see module comment.
+        form.append('format', args.format);
+        form.append('file', new Blob([bytes]), args.filename);
+        return dispatchIngestion({
+            method: 'POST',
+            path: contextSourceUploadPath(args.contextId, args.sourceId),
+            body: form,
+        }, extra);
+    });
+}
+//# sourceMappingURL=upload.js.map

package/dist/tools/ingestion/upload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.js","sourceRoot":"","sources":["../../../src/tools/ingestion/upload.ts"],"names":[],"mappings":"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"}

package/dist/tools/match-rule/create.js

@@ -13,9 +13,14 @@
 // exists in the schema: the rule is created for the tenant of the relayed bearer
 // token, and matcher validates that the context belongs to that tenant.
 import { z } from 'zod';
-import { contextRulesPath, dispatchMatchRule } from './shared.js';
-/** Matching strategy. EXACT / TOLERANCE / DATE_LAG — there is no FUZZY. */
-export const MATCH_RULE_TYPES = ['EXACT', 'TOLERANCE', 'DATE_LAG'];
+import { contextRulesPath, dispatchMatchRule, RULE_CONFIG_DESC_BODY, } from './shared.js';
+/** Matching strategy. EXACT / TOLERANCE / DATE_LAG / FUZZY (spec oneof). */
+export const MATCH_RULE_TYPES = [
+    'EXACT',
+    'TOLERANCE',
+    'DATE_LAG',
+    'FUZZY',
+];
 /** Zod raw shape for `match_rule_create` input — mirrors CreateMatchRuleRequest. */
 export const createMatchRuleInputShape = {
     contextId: z
@@ -34,14 +39,12 @@ export const createMatchRuleInputShape = {
         .enum(MATCH_RULE_TYPES)
         .describe('Matching strategy. EXACT requires identical field values; TOLERANCE ' +
         'allows configured numeric slack; DATE_LAG allows a configured date ' +
-        'offset between sides.'),
+        'offset between sides; FUZZY matches on normalized/similarity-scored ' +
+        'references (free-text memos, truncated refs) and ALWAYS proposes for ' +
+        'review — never auto-confirms.'),
     config: z
         .record(z.string(), z.unknown())
-        .describe('Rule-specific configuration object (matched fields and tolerance/lag ' +
-        'parameters). Its shape depends on `type` and is validated server-side. ' +
-        'EXACT: {"fields":["amount","reference"]}. TOLERANCE: ' +
-        '{"fields":["amount"],"toleranceAbs":"0.01"} or "tolerancePct". ' +
-        'DATE_LAG: {"fields":["date"],"maxLagDays":2}.'),
+        .describe('Rule-specific ' + RULE_CONFIG_DESC_BODY),
 };
 /**
  * Register `match_rule_create`. Splits the routing `contextId` (path) from the
@@ -52,7 +55,7 @@ export function registerMatchRuleCreateTool(server) {
     server.registerTool('match_rule_create', {
         description: 'Create a match rule within a reconciliation context. Provide contextId ' +
             '(UUID path), priority (1–1000, unique within the context), type ' +
-            '(EXACT|TOLERANCE|DATE_LAG), and config (a type-specific object validated ' +
+            '(EXACT|TOLERANCE|DATE_LAG|FUZZY), and config (a type-specific object validated ' +
             'server-side). No tenant field is accepted — the rule is created for your ' +
             "token's tenant. Returns the created rule, or a structured RFC 9457 error.",
         inputSchema: createMatchRuleInputShape,

package/dist/tools/match-rule/create.js.map

@@ -1 +1 @@
-{"version":3,"file":"create.js","sourceRoot":"","sources":["../../../src/tools/match-rule/create.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,EAAE;AACF,yEAAyE;AACzE,+EAA+E;AAC/E,8EAA8E;AAC9E,iFAAiF;AACjF,8EAA8E;AAC9E,kFAAkF;AAClF,gFAAgF;AAChF,WAAW;AACX,EAAE;AACF,2EAA2E;AAC3E,iFAAiF;AACjF,wEAAwE;AAExE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAEjE,2EAA2E;AAC3E,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,UAAU,CAAU,CAAA;AAE3E,oFAAoF;AACpF,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,yEAAyE;QACvE,qEAAqE,CACxE;IACH,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,IAAI,CAAC;SACT,QAAQ,CACP,uEAAuE;QACrE,qBAAqB,CACxB;IACH,IAAI,EAAE,CAAC;SACJ,IAAI,CAAC,gBAAgB,CAAC;SACtB,QAAQ,CACP,sEAAsE;QACpE,qEAAqE;QACrE,uBAAuB,CAC1B;IACH,MAAM,EAAE,CAAC;SACN,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/B,QAAQ,CACP,uEAAuE;QACrE,yEAAyE;QACzE,uDAAuD;QACvD,iEAAiE;QACjE,+CAA+C,CAClD;CACJ,CAAA;AAOD;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,MAAiB;IAC3D,MAAM,CAAC,YAAY,CACjB,mBAAmB,EACnB;QACE,WAAW,EACT,yEAAyE;YACzE,kEAAkE;YAClE,2EAA2E;YAC3E,2EAA2E;YAC3E,2EAA2E;QAC7E,WAAW,EAAE,yBAAyB;KACvC,EACD,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QACpB,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAA;QACnC,OAAO,iBAAiB,CACtB,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,EAC3D,KAAK,CACN,CAAA;IACH,CAAC,CACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"create.js","sourceRoot":"","sources":["../../../src/tools/match-rule/create.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,EAAE;AACF,yEAAyE;AACzE,+EAA+E;AAC/E,8EAA8E;AAC9E,iFAAiF;AACjF,8EAA8E;AAC9E,kFAAkF;AAClF,gFAAgF;AAChF,WAAW;AACX,EAAE;AACF,2EAA2E;AAC3E,iFAAiF;AACjF,wEAAwE;AAExE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,aAAa,CAAA;AAEpB,4EAA4E;AAC5E,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,OAAO;IACP,WAAW;IACX,UAAU;IACV,OAAO;CACC,CAAA;AAEV,oFAAoF;AACpF,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,yEAAyE;QACvE,qEAAqE,CACxE;IACH,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,IAAI,CAAC;SACT,QAAQ,CACP,uEAAuE;QACrE,qBAAqB,CACxB;IACH,IAAI,EAAE,CAAC;SACJ,IAAI,CAAC,gBAAgB,CAAC;SACtB,QAAQ,CACP,sEAAsE;QACpE,qEAAqE;QACrE,sEAAsE;QACtE,uEAAuE;QACvE,+BAA+B,CAClC;IACH,MAAM,EAAE,CAAC;SACN,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/B,QAAQ,CAAC,gBAAgB,GAAG,qBAAqB,CAAC;CACtD,CAAA;AAOD;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,MAAiB;IAC3D,MAAM,CAAC,YAAY,CACjB,mBAAmB,EACnB;QACE,WAAW,EACT,yEAAyE;YACzE,kEAAkE;YAClE,iFAAiF;YACjF,2EAA2E;YAC3E,2EAA2E;QAC7E,WAAW,EAAE,yBAAyB;KACvC,EACD,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QACpB,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAA;QACnC,OAAO,iBAAiB,CACtB,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,EAC3D,KAAK,CACN,CAAA;IACH,CAAC,CACF,CAAA;AACH,CAAC"}

package/dist/tools/match-rule/list.js

@@ -19,7 +19,7 @@ export const listMatchRulesInputShape = {
     type: z
         .enum(MATCH_RULE_TYPES)
         .optional()
-        .describe('Optional filter by rule type (EXACT|TOLERANCE|DATE_LAG). Omit to list all.'),
+        .describe('Optional filter by rule type (EXACT|TOLERANCE|DATE_LAG|FUZZY). Omit to list all.'),
     limit: z
         .number()
         .int()
@@ -56,7 +56,7 @@ export function registerMatchRuleListTool(server) {
     server.registerTool('match_rule_list', {
         description: 'List the match rules of a reconciliation context (cursor-paginated). ' +
             'Provide contextId (UUID path); optionally filter by type ' +
-            '(EXACT|TOLERANCE|DATE_LAG) and pass limit (1–200) and/or cursor. The ' +
+            '(EXACT|TOLERANCE|DATE_LAG|FUZZY) and pass limit (1–200) and/or cursor. The ' +
             'response carries { items, nextCursor } — paginate by re-calling with the ' +
             'returned nextCursor. No tenant field is accepted.',
         inputSchema: listMatchRulesInputShape,

package/dist/tools/match-rule/list.js.map

@@ -1 +1 @@
-{"version":3,"file":"list.js","sourceRoot":"","sources":["../../../src/tools/match-rule/list.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,4EAA4E;AAC5E,iEAAiE;AACjE,6EAA6E;AAC7E,wEAAwE;AACxE,iFAAiF;AACjF,4BAA4B;AAE5B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAKvB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAEjE,6FAA6F;AAC7F,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,yEAAyE;QACvE,4BAA4B,CAC/B;IACH,IAAI,EAAE,CAAC;SACJ,IAAI,CAAC,gBAAgB,CAAC;SACtB,QAAQ,EAAE;SACV,QAAQ,CACP,4EAA4E,CAC7E;IACH,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,GAAG,CAAC;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,0DAA0D,CAAC;IACvE,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,mEAAmE;QACjE,oEAAoE,CACvE;CACJ,CAAA;AAOD,+EAA+E;AAC/E,SAAS,cAAc,CAAC,IAAyB;IAC/C,MAAM,KAAK,GAAoC,EAAE,CAAA;IACjD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAA;IACxB,CAAC;IACD,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC7B,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;IAC1B,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC9B,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAA;IAC5B,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;AAC1D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAAiB;IACzD,MAAM,CAAC,YAAY,CACjB,iBAAiB,EACjB;QACE,WAAW,EACT,uEAAuE;YACvE,2DAA2D;YAC3D,uEAAuE;YACvE,2EAA2E;YAC3E,mDAAmD;QACrD,WAAW,EAAE,wBAAwB;KACtC,EACD,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QACpB,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,CAAA;QAClC,OAAO,iBAAiB,CACtB;YACE,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC;YACtC,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1C,EACD,KAAK,CACN,CAAA;IACH,CAAC,CACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../../../src/tools/match-rule/list.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,4EAA4E;AAC5E,iEAAiE;AACjE,6EAA6E;AAC7E,wEAAwE;AACxE,iFAAiF;AACjF,4BAA4B;AAE5B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAKvB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAEjE,6FAA6F;AAC7F,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,yEAAyE;QACvE,4BAA4B,CAC/B;IACH,IAAI,EAAE,CAAC;SACJ,IAAI,CAAC,gBAAgB,CAAC;SACtB,QAAQ,EAAE;SACV,QAAQ,CACP,kFAAkF,CACnF;IACH,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,GAAG,CAAC;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,0DAA0D,CAAC;IACvE,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,mEAAmE;QACjE,oEAAoE,CACvE;CACJ,CAAA;AAOD,+EAA+E;AAC/E,SAAS,cAAc,CAAC,IAAyB;IAC/C,MAAM,KAAK,GAAoC,EAAE,CAAA;IACjD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAA;IACxB,CAAC;IACD,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC7B,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;IAC1B,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC9B,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAA;IAC5B,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;AAC1D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAAiB;IACzD,MAAM,CAAC,YAAY,CACjB,iBAAiB,EACjB;QACE,WAAW,EACT,uEAAuE;YACvE,2DAA2D;YAC3D,6EAA6E;YAC7E,2EAA2E;YAC3E,mDAAmD;QACrD,WAAW,EAAE,wBAAwB;KACtC,EACD,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QACpB,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,CAAA;QAClC,OAAO,iBAAiB,CACtB;YACE,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC;YACtC,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1C,EACD,KAAK,CACN,CAAA;IACH,CAAC,CACF,CAAA;AACH,CAAC"}

package/dist/tools/match-rule/shared.js

@@ -32,6 +32,29 @@ export function contextRulePath(contextId, ruleId) {
 export function contextRulesReorderPath(contextId) {
     return `${contextRulesPath(contextId)}/reorder`;
 }
+/**
+ * Shared body of the `config` field description, centralized so create and
+ * update stay in lockstep as the rule vocabulary grows. Callers prepend the
+ * lead phrase ("Rule-specific " / "New rule-specific ") to preserve their exact
+ * historical wording.
+ */
+export const RULE_CONFIG_DESC_BODY = 'configuration object; shape depends on `type` and is ' +
+    'validated server-side (unknown keys are rejected with a 422). Built-in ' +
+    'toggles: matchAmount, matchCurrency, matchDate, matchReference ' +
+    '(booleans). EXACT example: {"matchAmount":true,"matchCurrency":true,' +
+    '"matchReference":true,"matchDate":false}. TOLERANCE adds absTolerance ' +
+    'and percentTolerance (decimal STRINGS, e.g. "0.05") and dateWindowDays ' +
+    '(int): {"absTolerance":"0.05","percentTolerance":"0","dateWindowDays":4}. ' +
+    'TOLERANCE also accepts fxVarianceBand (decimal string fraction, e.g. ' +
+    '"0.0001" for 1bp) for cross-currency residual matches. DATE_LAG uses ' +
+    'minDays, maxDays (ints) and inclusive (bool): {"minDays":0,"maxDays":4,' +
+    '"inclusive":true}. FUZZY uses minSimilarity (a 0..1 decimal threshold, ' +
+    'default 0.80) plus toggles: {"minSimilarity":0.85,"matchAmount":true,' +
+    '"matchCurrency":true}. EXACT/TOLERANCE also accept matchFields ' +
+    '(composite-key array: [{ field, mode: required|conditional|off, ' +
+    'tolerance? }]). Optional across types: timezone (IANA zone), calendar ' +
+    '(US_FED|BR_ANBIMA), businessDayMode (DATE_LAG only), and signMode ' +
+    '(same|opposite|ignore).';
 /**
  * Run one assembled request through the relay: fail-closed auth, dispatch, and
  * RFC 9457 → tool-error mapping — identical to the generic invoke's dispatch so

package/dist/tools/match-rule/shared.js.map

@@ -1 +1 @@
-{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../src/tools/match-rule/shared.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,EAAE;AACF,6DAA6D;AAC7D,mEAAmE;AACnE,+EAA+E;AAC/E,+EAA+E;AAC/E,2EAA2E;AAC3E,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAC/E,kEAAkE;AAClE,6EAA6E;AAC7E,yBAAyB;AACzB,EAAE;AACF,gFAAgF;AAChF,+EAA+E;AAC/E,2EAA2E;AAC3E,0EAA0E;AAC1E,2EAA2E;AAC3E,yCAAyC;AAIzC,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GAErB,MAAM,6BAA6B,CAAA;AAEpC,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAEjE,0EAA0E;AAC1E,MAAM,UAAU,gBAAgB,CAAC,SAAiB;IAChD,OAAO,gBAAgB,kBAAkB,CAAC,SAAS,CAAC,QAAQ,CAAA;AAC9D,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,eAAe,CAAC,SAAiB,EAAE,MAAc;IAC/D,OAAO,GAAG,gBAAgB,CAAC,SAAS,CAAC,IAAI,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAA;AACvE,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,uBAAuB,CAAC,SAAiB;IACvD,OAAO,GAAG,gBAAgB,CAAC,SAAS,CAAC,UAAU,CAAA;AACjD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAuB,EACvB,KAAmC,EACnC,YAAyD,oBAAoB;IAE7E,IAAI,MAAqB,CAAA;IACzB,IAAI,CAAC;QACH,4DAA4D;QAC5D,MAAM,GAAG,SAAS,CAAC,KAAK,CAAC,CAAA;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,oBAAoB,EAAE,CAAC;YACxC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,EAAE,CAAA;QAC1E,CAAC;QACD,MAAM,GAAG,CAAA;IACX,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;QAC5C,0EAA0E;QAC1E,oCAAoC;QACpC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,IAAI,IAAI,CAAC,EAAE,CAAC,EAAE,CAAA;IAC9E,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,4EAA4E;QAC5E,4EAA4E;QAC5E,+CAA+C;QAC/C,IAAI,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,OAAO,WAAW,CAAC,GAAG,CAAC,CAAA;QACzB,CAAC;QACD,MAAM,GAAG,CAAA;IACX,CAAC;AACH,CAAC"}
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../src/tools/match-rule/shared.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,EAAE;AACF,6DAA6D;AAC7D,mEAAmE;AACnE,+EAA+E;AAC/E,+EAA+E;AAC/E,2EAA2E;AAC3E,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAC/E,kEAAkE;AAClE,6EAA6E;AAC7E,yBAAyB;AACzB,EAAE;AACF,gFAAgF;AAChF,+EAA+E;AAC/E,2EAA2E;AAC3E,0EAA0E;AAC1E,2EAA2E;AAC3E,yCAAyC;AAIzC,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GAErB,MAAM,6BAA6B,CAAA;AAEpC,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAEjE,0EAA0E;AAC1E,MAAM,UAAU,gBAAgB,CAAC,SAAiB;IAChD,OAAO,gBAAgB,kBAAkB,CAAC,SAAS,CAAC,QAAQ,CAAA;AAC9D,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,eAAe,CAAC,SAAiB,EAAE,MAAc;IAC/D,OAAO,GAAG,gBAAgB,CAAC,SAAS,CAAC,IAAI,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAA;AACvE,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,uBAAuB,CAAC,SAAiB;IACvD,OAAO,GAAG,gBAAgB,CAAC,SAAS,CAAC,UAAU,CAAA;AACjD,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAChC,uDAAuD;IACvD,yEAAyE;IACzE,iEAAiE;IACjE,sEAAsE;IACtE,wEAAwE;IACxE,yEAAyE;IACzE,4EAA4E;IAC5E,uEAAuE;IACvE,uEAAuE;IACvE,yEAAyE;IACzE,yEAAyE;IACzE,uEAAuE;IACvE,iEAAiE;IACjE,kEAAkE;IAClE,wEAAwE;IACxE,oEAAoE;IACpE,yBAAyB,CAAA;AAE3B;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAuB,EACvB,KAAmC,EACnC,YAAyD,oBAAoB;IAE7E,IAAI,MAAqB,CAAA;IACzB,IAAI,CAAC;QACH,4DAA4D;QAC5D,MAAM,GAAG,SAAS,CAAC,KAAK,CAAC,CAAA;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,oBAAoB,EAAE,CAAC;YACxC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,EAAE,CAAA;QAC1E,CAAC;QACD,MAAM,GAAG,CAAA;IACX,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;QAC5C,0EAA0E;QAC1E,oCAAoC;QACpC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,IAAI,IAAI,CAAC,EAAE,CAAC,EAAE,CAAA;IAC9E,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,4EAA4E;QAC5E,4EAA4E;QAC5E,+CAA+C;QAC/C,IAAI,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,OAAO,WAAW,CAAC,GAAG,CAAC,CAAA;QACzB,CAAC;QACD,MAAM,GAAG,CAAA;IACX,CAAC;AACH,CAAC"}

package/dist/tools/match-rule/update.js

@@ -6,7 +6,7 @@
 // (matcher scopes to the relayed token's tenant via the context).
 import { z } from 'zod';
 import { MATCH_RULE_TYPES } from './create.js';
-import { contextRulePath, dispatchMatchRule } from './shared.js';
+import { contextRulePath, dispatchMatchRule, RULE_CONFIG_DESC_BODY, } from './shared.js';
 /** Zod raw shape for `match_rule_update` input — ids (path) + optional fields. */
 export const updateMatchRuleInputShape = {
     contextId: z
@@ -25,13 +25,13 @@ export const updateMatchRuleInputShape = {
     type: z
         .enum(MATCH_RULE_TYPES)
         .optional()
-        .describe('New matching strategy (EXACT|TOLERANCE|DATE_LAG). Changing type usually ' +
-        'requires a matching `config` change.'),
+        .describe('New matching strategy (EXACT|TOLERANCE|DATE_LAG|FUZZY). FUZZY matches on ' +
+        'similarity-scored references and always proposes for review (never ' +
+        'auto-confirms). Changing type usually requires a matching `config` change.'),
     config: z
         .record(z.string(), z.unknown())
         .optional()
-        .describe('New rule-specific configuration object (matched fields and tolerance/lag ' +
-        'parameters). Shape depends on `type`; validated server-side.'),
+        .describe('New rule-specific ' + RULE_CONFIG_DESC_BODY),
 };
 /**
  * Build the PATCH body from the input minus the path-only `contextId`/`ruleId`.
@@ -53,7 +53,7 @@ export function registerMatchRuleUpdateTool(server) {
     server.registerTool('match_rule_update', {
         description: 'Update a match rule by id (UUID) within a context (UUID). All fields are ' +
             'optional (PATCH): priority (1–1000, unique), type ' +
-            '(EXACT|TOLERANCE|DATE_LAG), config (type-specific, validated server-side). ' +
+            '(EXACT|TOLERANCE|DATE_LAG|FUZZY), config (type-specific, validated server-side). ' +
             'No tenant field is accepted. Returns the updated rule, or a structured ' +
             'RFC 9457 error.',
         inputSchema: updateMatchRuleInputShape,

package/dist/tools/match-rule/update.js.map

@@ -1 +1 @@
-{"version":3,"file":"update.js","sourceRoot":"","sources":["../../../src/tools/match-rule/update.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAC/E,yEAAyE;AACzE,kEAAkE;AAElE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAEhE,kFAAkF;AAClF,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,+EAA+E,CAChF;IACH,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,qCAAqC,CAAC;IACzE,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,IAAI,CAAC;SACT,QAAQ,EAAE;SACV,QAAQ,CACP,wEAAwE;QACtE,qBAAqB,CACxB;IACH,IAAI,EAAE,CAAC;SACJ,IAAI,CAAC,gBAAgB,CAAC;SACtB,QAAQ,EAAE;SACV,QAAQ,CACP,0EAA0E;QACxE,sCAAsC,CACzC;IACH,MAAM,EAAE,CAAC;SACN,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/B,QAAQ,EAAE;SACV,QAAQ,CACP,2EAA2E;QACzE,8DAA8D,CACjE;CACJ,CAAA;AAOD;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAC7B,IAA0B;IAE1B,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAA;IAChE,KAAK,UAAU,CAAA;IACf,KAAK,OAAO,CAAA;IACZ,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,MAAiB;IAC3D,MAAM,CAAC,YAAY,CACjB,mBAAmB,EACnB;QACE,WAAW,EACT,2EAA2E;YAC3E,oDAAoD;YACpD,6EAA6E;YAC7E,yEAAyE;YACzE,iBAAiB;QACnB,WAAW,EAAE,yBAAyB;KACvC,EACD,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QACpB,OAAO,iBAAiB,CACtB;YACE,MAAM,EAAE,OAAO;YACf,IAAI,EAAE,eAAe,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC;YAClD,IAAI,EAAE,eAAe,CAAC,IAAI,CAAC;SAC5B,EACD,KAAK,CACN,CAAA;IACH,CAAC,CACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"update.js","sourceRoot":"","sources":["../../../src/tools/match-rule/update.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAC/E,yEAAyE;AACzE,kEAAkE;AAElE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,aAAa,CAAA;AAEpB,kFAAkF;AAClF,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,+EAA+E,CAChF;IACH,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,qCAAqC,CAAC;IACzE,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,IAAI,CAAC;SACT,QAAQ,EAAE;SACV,QAAQ,CACP,wEAAwE;QACtE,qBAAqB,CACxB;IACH,IAAI,EAAE,CAAC;SACJ,IAAI,CAAC,gBAAgB,CAAC;SACtB,QAAQ,EAAE;SACV,QAAQ,CACP,2EAA2E;QACzE,qEAAqE;QACrE,4EAA4E,CAC/E;IACH,MAAM,EAAE,CAAC;SACN,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/B,QAAQ,EAAE;SACV,QAAQ,CAAC,oBAAoB,GAAG,qBAAqB,CAAC;CAC1D,CAAA;AAOD;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAC7B,IAA0B;IAE1B,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAA;IAChE,KAAK,UAAU,CAAA;IACf,KAAK,OAAO,CAAA;IACZ,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,MAAiB;IAC3D,MAAM,CAAC,YAAY,CACjB,mBAAmB,EACnB;QACE,WAAW,EACT,2EAA2E;YAC3E,oDAAoD;YACpD,mFAAmF;YACnF,yEAAyE;YACzE,iBAAiB;QACnB,WAAW,EAAE,yBAAyB;KACvC,EACD,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QACpB,OAAO,iBAAiB,CACtB;YACE,MAAM,EAAE,OAAO;YACf,IAAI,EAAE,eAAe,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC;YAClD,IAAI,EAAE,eAAe,CAAC,IAAI,CAAC;SAC5B,EACD,KAAK,CACN,CAAA;IACH,CAAC,CACF,CAAA;AACH,CAAC"}

package/dist/tools/matching/get.js

@@ -1,15 +1,24 @@
 // `match_run_get` — curated GET /v1/matching/runs/{runId}?contextId=<id>.
 //
 // Reads one match run's detail by id: status, timing, aggregate stats, and the
-// per-rule matched-group counts (ruleStats). The matcher payload is returned
-// verbatim — this is how an operator polls a run started by `match_run_start`.
+// per-rule matched-group counts (ruleStats). This is how an operator polls a
+// run started by `match_run_start`. In-flight states (keep polling): QUEUED,
+// PROCESSING, FINALIZING. Terminal states (stop): COMPLETED, FAILED.
+//
+// `stats` is NOT returned fully verbatim: matcher's per-rule keys
+// (`rule_matched:<uuid>`, `rule_meta:<uuid>:<type>`) are stripped before the
+// response reaches the model (see `stripRuleStatKeys` in shared.ts) — they are
+// UUID-keyed noise that duplicates the clean `ruleStats[]` array already in the
+// same payload. Every static stats key (matches, unmatched_left, etc.) and
+// `ruleStats[]` itself pass through unchanged.
 //
 // Path/query split (per the spec): `runId` is the PATH param, but `contextId` is
 // a REQUIRED QUERY param (not part of the path), so matcher can scope the run to
 // the right context. `contextId` is a routing param matcher validates ownership
 // of, NOT a tenant field; no tenant field is accepted.
 import { z } from 'zod';
-import { dispatchMatching, runPath } from './shared.js';
+import { requireMatcherClient } from '../../auth/request-token.js';
+import { dispatchMatching, runPath, stripRuleStatKeys } from './shared.js';
 /** Zod raw shape for `match_run_get` input — runId (path) + contextId (query, required). */
 export const getMatchRunInputShape = {
     runId: z
@@ -22,27 +31,41 @@ export const getMatchRunInputShape = {
         .describe('The reconciliation context id (UUID) the run belongs to. Sent as a query ' +
         'param (required); routing param scoped to your token.'),
 };
+/**
+ * Fetch the run and return it with `stats` cleaned of the dynamic per-rule
+ * keys (see `stripRuleStatKeys`). Delegates to the shared `dispatchMatching`
+ * relay (fail-closed auth, RFC 9457 → tool-error mapping) and passes a
+ * success-body transform — the one matching read that post-processes the body.
+ */
+function fetchAndCleanRun(runId, contextId, extra, clientFor = requireMatcherClient) {
+    return dispatchMatching({ method: 'GET', path: runPath(runId), query: { contextId } }, extra, clientFor, (run) => run !== undefined && run !== null
+        ? {
+            ...run,
+            stats: stripRuleStatKeys(run.stats),
+        }
+        : run);
+}
 /**
  * Register `match_run_get`. Substitutes runId into the path and sends contextId
- * as a query param; dispatches a GET through the shared fail-closed relay. The
- * run payload (status/stats/ruleStats) is returned verbatim; a matcher error
- * (e.g. 404) surfaces via the shared toToolError.
+ * as a query param; fetches through the fail-closed relay and strips the
+ * dynamic per-rule `stats` keys (see module doc) before returning. A matcher
+ * error (e.g. 404) surfaces via the shared toToolError.
  */
 export function registerMatchRunGetTool(server) {
     server.registerTool('match_run_get', {
         description: 'Fetch a single match run by id, including status, timing, aggregate ' +
             'statistics, and per-rule matched-group counts. Use this to poll a run ' +
-            'started by match_run_start. Requires runId and contextId (contextId is ' +
-            'sent as a query param). Both are routing params scoped to your token; no ' +
-            'tenant field is accepted. Returns the run detail, or a structured RFC ' +
-            '9457 error (e.g. 404).',
+            'started by match_run_start. status is one of: QUEUED, PROCESSING, ' +
+            'FINALIZING (all IN-FLIGHT — still running, keep polling; FINALIZING is a ' +
+            'transient near-done state, not an error) or COMPLETED, FAILED (TERMINAL ' +
+            '— stop polling). Requires runId and contextId (contextId is sent as a ' +
+            'query param). Both are routing params scoped to your token; no tenant ' +
+            'field is accepted. Returns the run detail (stats excludes the raw ' +
+            'rule_matched:/rule_meta: keys — see ruleStats[] for the same data, ' +
+            'readable), or a structured RFC 9457 error (e.g. 404).',
         inputSchema: getMatchRunInputShape,
     }, async (args, extra) => {
-        return dispatchMatching({
-            method: 'GET',
-            path: runPath(args.runId),
-            query: { contextId: args.contextId },
-        }, extra);
+        return fetchAndCleanRun(args.runId, args.contextId, extra);
     });
 }
 //# sourceMappingURL=get.js.map

package/dist/tools/matching/get.js.map

@@ -1 +1 @@
-{"version":3,"file":"get.js","sourceRoot":"","sources":["../../../src/tools/matching/get.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAC7E,+EAA+E;AAC/E,EAAE;AACF,iFAAiF;AACjF,iFAAiF;AACjF,gFAAgF;AAChF,uDAAuD;AAEvD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAEvD,4FAA4F;AAC5F,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CAAC,mCAAmC,CAAC;IAChD,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,2EAA2E;QACzE,uDAAuD,CAC1D;CACJ,CAAA;AAOD;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAiB;IACvD,MAAM,CAAC,YAAY,CACjB,eAAe,EACf;QACE,WAAW,EACT,sEAAsE;YACtE,wEAAwE;YACxE,yEAAyE;YACzE,2EAA2E;YAC3E,wEAAwE;YACxE,wBAAwB;QAC1B,WAAW,EAAE,qBAAqB;KACnC,EACD,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QACpB,OAAO,gBAAgB,CACrB;YACE,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;YACzB,KAAK,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE;SACrC,EACD,KAAK,CACN,CAAA;IACH,CAAC,CACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"get.js","sourceRoot":"","sources":["../../../src/tools/matching/get.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAC7E,6EAA6E;AAC7E,qEAAqE;AACrE,EAAE;AACF,kEAAkE;AAClE,6EAA6E;AAC7E,+EAA+E;AAC/E,gFAAgF;AAChF,2EAA2E;AAC3E,+CAA+C;AAC/C,EAAE;AACF,iFAAiF;AACjF,iFAAiF;AACjF,gFAAgF;AAChF,uDAAuD;AAEvD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAMvB,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAA;AAElE,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAE1E,4FAA4F;AAC5F,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CAAC,mCAAmC,CAAC;IAChD,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,2EAA2E;QACzE,uDAAuD,CAC1D;CACJ,CAAA;AAOD;;;;;GAKG;AACH,SAAS,gBAAgB,CACvB,KAAa,EACb,SAAiB,EACjB,KAAmC,EACnC,YAAyD,oBAAoB;IAE7E,OAAO,gBAAgB,CACrB,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,EAAE,EAC7D,KAAK,EACL,SAAS,EACT,CAAC,GAAG,EAAE,EAAE,CACN,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI;QAC/B,CAAC,CAAC;YACE,GAAI,GAA+B;YACnC,KAAK,EAAE,iBAAiB,CAAE,GAA+B,CAAC,KAAgC,CAAC;SAC5F;QACH,CAAC,CAAC,GAAG,CACV,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAiB;IACvD,MAAM,CAAC,YAAY,CACjB,eAAe,EACf;QACE,WAAW,EACT,sEAAsE;YACtE,wEAAwE;YACxE,oEAAoE;YACpE,2EAA2E;YAC3E,0EAA0E;YAC1E,wEAAwE;YACxE,wEAAwE;YACxE,oEAAoE;YACpE,qEAAqE;YACrE,uDAAuD;QACzD,WAAW,EAAE,qBAAqB;KACnC,EACD,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QACpB,OAAO,gBAAgB,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAA;IAC5D,CAAC,CACF,CAAA;AACH,CAAC"}

package/dist/tools/matching/shared.js

@@ -38,6 +38,34 @@ export function runPath(runId) {
 export function runGroupsPath(runId) {
     return `/v1/matching/runs/${encodeURIComponent(runId)}/groups`;
 }
+/**
+ * Per-rule stat-key prefixes matcher writes into a run's `stats` map
+ * (entities.StatKeyRuleMatchedPrefix / StatKeyRuleMetaPrefix on the backend):
+ * `rule_matched:<ruleID>` and `rule_meta:<ruleID>:<TYPE>`. UUID-keyed and
+ * unreadable on the wire — and pure duplication, since the same payload's
+ * `ruleStats[]` array (`{ruleId, priority, type, matched}`) is derived from
+ * these exact keys server-side (RuleStatsFromStats).
+ */
+const RULE_STAT_KEY_PREFIXES = ['rule_matched:', 'rule_meta:'];
+/**
+ * Strip the dynamic per-rule `rule_matched:<uuid>` / `rule_meta:<uuid>:<type>`
+ * keys from a run's `stats` map before it reaches the model. Every other key
+ * (the static aggregates: matches, unmatched_left, auto_matched_left, etc.) is
+ * passed through untouched. The per-rule data is NOT lost — it remains
+ * available, readable, in the response's `ruleStats[]` array.
+ */
+export function stripRuleStatKeys(stats) {
+    if (stats === undefined || stats === null) {
+        return stats;
+    }
+    const cleaned = {};
+    for (const [key, value] of Object.entries(stats)) {
+        if (!RULE_STAT_KEY_PREFIXES.some((prefix) => key.startsWith(prefix))) {
+            cleaned[key] = value;
+        }
+    }
+    return cleaned;
+}
 /**
  * Run one assembled request through the relay: fail-closed auth, dispatch, and
  * RFC 9457 → tool-error mapping — identical to the generic invoke's dispatch so
@@ -46,7 +74,7 @@ export function runGroupsPath(runId) {
  * `clientFor` is injectable for tests; production callers pass nothing and get
  * the request-scoped, fail-closed `requireMatcherClient`.
  */
-export async function dispatchMatching(request, extra, clientFor = requireMatcherClient) {
+export async function dispatchMatching(request, extra, clientFor = requireMatcherClient, transform) {
     let client;
     try {
         // Fail-closed on a missing / empty / non-Bearer credential.
@@ -61,8 +89,10 @@ export async function dispatchMatching(request, extra, clientFor = requireMatche
     try {
         const result = await client.request(request);
         // Success → matcher's run payload returned as-is (202 { runId, status },
-        // run detail status/stats/ruleStats, or the group pagination envelope).
-        return { content: [{ type: 'text', text: JSON.stringify(result ?? null) }] };
+        // run detail status/stats/ruleStats, or the group pagination envelope),
+        // unless a caller-supplied transform post-processes the body first.
+        const output = transform ? transform(result) : result;
+        return { content: [{ type: 'text', text: JSON.stringify(output ?? null) }] };
     }
     catch (err) {
         // RFC 9457 problem → the SHARED structured tool error (status/title/detail/

package/dist/tools/matching/shared.js.map

@@ -1 +1 @@
-{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../src/tools/matching/shared.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,EAAE;AACF,gFAAgF;AAChF,+EAA+E;AAC/E,8EAA8E;AAC9E,4EAA4E;AAC5E,wEAAwE;AACxE,gFAAgF;AAChF,iFAAiF;AACjF,+EAA+E;AAC/E,wEAAwE;AACxE,EAAE;AACF,gFAAgF;AAChF,kFAAkF;AAClF,6EAA6E;AAC7E,kFAAkF;AAClF,EAAE;AACF,gFAAgF;AAChF,+EAA+E;AAC/E,2EAA2E;AAC3E,iFAAiF;AACjF,yEAAyE;AAIzE,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GAErB,MAAM,6BAA6B,CAAA;AAEpC,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAEjE,oEAAoE;AACpE,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,OAAO,yBAAyB,kBAAkB,CAAC,SAAS,CAAC,MAAM,CAAA;AACrE,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC/C,OAAO,yBAAyB,kBAAkB,CAAC,SAAS,CAAC,OAAO,CAAA;AACtE,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,OAAO,qBAAqB,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAA;AACzD,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,qBAAqB,kBAAkB,CAAC,KAAK,CAAC,SAAS,CAAA;AAChE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAuB,EACvB,KAAmC,EACnC,YAAyD,oBAAoB;IAE7E,IAAI,MAAqB,CAAA;IACzB,IAAI,CAAC;QACH,4DAA4D;QAC5D,MAAM,GAAG,SAAS,CAAC,KAAK,CAAC,CAAA;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,oBAAoB,EAAE,CAAC;YACxC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,EAAE,CAAA;QAC1E,CAAC;QACD,MAAM,GAAG,CAAA;IACX,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;QAC5C,yEAAyE;QACzE,wEAAwE;QACxE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,IAAI,IAAI,CAAC,EAAE,CAAC,EAAE,CAAA;IAC9E,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,4EAA4E;QAC5E,4EAA4E;QAC5E,+CAA+C;QAC/C,IAAI,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,OAAO,WAAW,CAAC,GAAG,CAAC,CAAA;QACzB,CAAC;QACD,MAAM,GAAG,CAAA;IACX,CAAC;AACH,CAAC"}
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../src/tools/matching/shared.ts"],"names":[],"mappings":"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"}

package/dist/tools/matching/start.js

@@ -1,8 +1,12 @@
 // `match_run_start` — curated POST /v1/matching/contexts/{contextId}/run.
 //
-// Triggers a matching run for a reconciliation context. This is an async action:
-// matcher responds 202 with { runId, status } and processes in the background —
-// the operator polls `match_run_get` with the returned runId to follow progress.
+// Triggers a matching run for a reconciliation context. Both submit paths return
+// HTTP 202 with { runId, status }; the `status` distinguishes them:
+//   - sync (async omitted/false): the run executes in-request and the 202 carries
+//     the TERMINAL run — status COMPLETED or FAILED. No polling needed.
+//   - async (async:true): the run is created QUEUED and executed by a background
+//     worker; the 202 carries status QUEUED. The operator polls `match_run_get`
+//     with the returned runId to follow progress.
 // This tool does NOT auto-poll; it returns the 202 acceptance body verbatim.
 //
 // `contextId` is a routing path param (matcher validates it belongs to the
@@ -27,28 +31,50 @@ export const startMatchRunInputShape = {
         .enum(RUN_MODES)
         .describe('Execution mode. DRY_RUN tests the rules without committing any matches; ' +
         'COMMIT executes the rules and persists the resulting matches.'),
+    async: z
+        .boolean()
+        .optional()
+        .describe('Submit path (optional, default false). Both return 202 with ' +
+        '{ runId, status }; the status distinguishes them. Omit (or false) to ' +
+        'run in-request: the 202 carries the TERMINAL run (status COMPLETED or ' +
+        'FAILED). Set true to enqueue: the run is created QUEUED and a background ' +
+        'worker executes it — the 202 status is QUEUED and you poll match_run_get ' +
+        'with the runId until it reaches COMPLETED/FAILED.'),
 };
 /**
- * Register `match_run_start`. Substitutes contextId into the path and sends only
- * `{ mode }` as the body (per RunMatchRequest, which forbids extra properties).
- * Dispatches through the shared fail-closed relay; a matcher error surfaces via
- * the shared toToolError.
+ * Register `match_run_start`. Substitutes contextId into the path and sends
+ * `{ mode }` as the body, adding `async` ONLY when the caller set it (per
+ * RunMatchRequest, which accepts `async` but forbids unknown properties — so the
+ * key is omitted when undefined to keep the body minimal). Dispatches through the
+ * shared fail-closed relay; a matcher error surfaces via the shared toToolError.
  */
 export function registerMatchRunStartTool(server) {
     server.registerTool('match_run_start', {
-        description: 'Trigger a matching run for a reconciliation context. Async: returns 202 ' +
-            'with { runId, status } and processes in the background — poll ' +
-            'match_run_get with the runId to follow progress (this tool does not ' +
+        description: 'Trigger a matching run for a reconciliation context. Both submit paths ' +
+            'return 202 with { runId, status }; the status distinguishes them. Omit ' +
+            'async (or set false) to run in-request: the 202 carries the TERMINAL run ' +
+            '(status COMPLETED or FAILED). Set async:true to enqueue: the run is ' +
+            'created QUEUED and a background worker executes it (202 status QUEUED) — ' +
+            'poll match_run_get with the runId to follow progress (this tool does not ' +
             'auto-poll). mode is required: DRY_RUN tests rules without committing, ' +
             'COMMIT persists the matches. contextId is a routing param scoped to your ' +
             'token (no tenant field is accepted). Returns the acceptance body, or a ' +
-            'structured RFC 9457 error.',
+            'structured RFC 9457 error (e.g. 422 when the rule set is not ' +
+            'stream-bounded and cannot run at unbounded scale).',
         inputSchema: startMatchRunInputShape,
     }, async (args, extra) => {
+        // Omit `async` unless the caller set it — match the { mode } body style and
+        // keep the body minimal for RunMatchRequest's no-unknown-props contract.
+        const body = {
+            mode: args.mode,
+        };
+        if (args.async !== undefined) {
+            body.async = args.async;
+        }
         return dispatchMatching({
             method: 'POST',
             path: contextRunPath(args.contextId),
-            body: { mode: args.mode },
+            body,
         }, extra);
     });
 }

package/dist/tools/matching/start.js.map

@@ -1 +1 @@
-{"version":3,"file":"start.js","sourceRoot":"","sources":["../../../src/tools/matching/start.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,EAAE;AACF,iFAAiF;AACjF,gFAAgF;AAChF,iFAAiF;AACjF,6EAA6E;AAC7E,EAAE;AACF,2EAA2E;AAC3E,4EAA4E;AAE5E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAE9D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAU,CAAA;AAEvD,oFAAoF;AACpF,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,2EAA2E;QACzE,8CAA8C,CACjD;IACH,IAAI,EAAE,CAAC;SACJ,IAAI,CAAC,SAAS,CAAC;SACf,QAAQ,CACP,0EAA0E;QACxE,+DAA+D,CAClE;CACJ,CAAA;AAOD;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAAiB;IACzD,MAAM,CAAC,YAAY,CACjB,iBAAiB,EACjB;QACE,WAAW,EACT,0EAA0E;YAC1E,gEAAgE;YAChE,sEAAsE;YACtE,wEAAwE;YACxE,2EAA2E;YAC3E,yEAAyE;YACzE,4BAA4B;QAC9B,WAAW,EAAE,uBAAuB;KACrC,EACD,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QACpB,OAAO,gBAAgB,CACrB;YACE,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC;YACpC,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE;SAC1B,EACD,KAAK,CACN,CAAA;IACH,CAAC,CACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"start.js","sourceRoot":"","sources":["../../../src/tools/matching/start.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,EAAE;AACF,iFAAiF;AACjF,oEAAoE;AACpE,kFAAkF;AAClF,wEAAwE;AACxE,iFAAiF;AACjF,gFAAgF;AAChF,kDAAkD;AAClD,6EAA6E;AAC7E,EAAE;AACF,2EAA2E;AAC3E,4EAA4E;AAE5E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAE9D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAU,CAAA;AAEvD,oFAAoF;AACpF,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,2EAA2E;QACzE,8CAA8C,CACjD;IACH,IAAI,EAAE,CAAC;SACJ,IAAI,CAAC,SAAS,CAAC;SACf,QAAQ,CACP,0EAA0E;QACxE,+DAA+D,CAClE;IACH,KAAK,EAAE,CAAC;SACL,OAAO,EAAE;SACT,QAAQ,EAAE;SACV,QAAQ,CACP,8DAA8D;QAC5D,uEAAuE;QACvE,wEAAwE;QACxE,2EAA2E;QAC3E,2EAA2E;QAC3E,mDAAmD,CACtD;CACJ,CAAA;AAOD;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAAiB;IACzD,MAAM,CAAC,YAAY,CACjB,iBAAiB,EACjB;QACE,WAAW,EACT,yEAAyE;YACzE,yEAAyE;YACzE,2EAA2E;YAC3E,sEAAsE;YACtE,2EAA2E;YAC3E,2EAA2E;YAC3E,wEAAwE;YACxE,2EAA2E;YAC3E,yEAAyE;YACzE,+DAA+D;YAC/D,oDAAoD;QACtD,WAAW,EAAE,uBAAuB;KACrC,EACD,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QACpB,4EAA4E;QAC5E,yEAAyE;QACzE,MAAM,IAAI,GAA0D;YAClE,IAAI,EAAE,IAAI,CAAC,IAAI;SAChB,CAAA;QACD,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC7B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;QACzB,CAAC;QACD,OAAO,gBAAgB,CACrB;YACE,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC;YACpC,IAAI;SACL,EACD,KAAK,CACN,CAAA;IACH,CAAC,CACF,CAAA;AACH,CAAC"}

package/dist/tools/report/count-exceptions.js

@@ -30,8 +30,9 @@ export function registerReportCountExceptionsTool(server) {
             'between a sync download (<1000 rows) and an async export. The date ' +
             "filter applies to each exception's created_at. Pass contextId (UUID " +
             'path param — not a tenant field), and optionally date_from/date_to ' +
-            '(YYYY-MM-DD, window ≤ 90 days) and source_id. No tenant field is ' +
-            'accepted.',
+            '(YYYY-MM-DD, window ≤ 90 days; if omitted, defaults to the last ~30 ' +
+            'days and SILENTLY EXCLUDES older exceptions — pass an explicit range ' +
+            'for a full picture) and source_id. No tenant field is accepted.',
         inputSchema: countExceptionsInputShape,
     }, async (args, extra) => {
         const query = buildReportFilterQuery(args);