@lerianstudio/matcher-mcp 1.2.0 → 1.2.1-beta.1

package/dist/config.js

@@ -10,7 +10,6 @@ const DEFAULT_MATCHER_API_URL = 'http://localhost:4018';
 const DEFAULT_TIMEOUT_MS = 30_000;
 const DEFAULT_MAX_BODY_BYTES = 1_048_576; // 1 MiB
 const DEFAULT_OTEL_SERVICE_NAME = 'matcher-mcp';
-const DEFAULT_UPLOAD_MAX_FETCH_BYTES = 52_428_800; // 50 MiB
 /**
  * Parse a port from a raw env string, falling back to the default when unset.
  * An explicitly-set but invalid value is a misconfiguration and throws, rather
@@ -75,36 +74,6 @@ function parseBool(raw, fallback, key) {
     }
     throw new Error(`invalid ${key}: ${raw} (expected one of true, false, 1, 0)`);
 }
-/**
- * Parse a comma-separated hostname allowlist, trimming each entry and dropping
- * empties (so `"a,,b"` or a trailing comma doesn't produce a spurious `""`
- * entry that would never exact-match a real hostname). Unset/empty env ⇒ `[]`
- * — fail-closed default for `MCP_UPLOAD_ALLOWED_HOSTS`.
- */
-function parseAllowedHosts(raw) {
-    if (raw === undefined) {
-        return [];
-    }
-    return raw
-        .split(',')
-        .map((h) => h.trim())
-        .filter((h) => h.length > 0);
-}
-/**
- * Parse a positive byte count from a raw env string, falling back to the default
- * when unset. Shares `parseMaxBodyBytes`'s fail-loud semantics under its own
- * env-var name so the error message names the right key.
- */
-function parseUploadMaxFetchBytes(raw, fallback) {
-    if (raw === undefined || raw === '') {
-        return fallback;
-    }
-    const value = Number(raw);
-    if (!Number.isInteger(value) || value < 1) {
-        throw new Error(`invalid MCP_UPLOAD_MAX_FETCH_BYTES: ${raw} (expected a positive integer of bytes)`);
-    }
-    return value;
-}
 /**
  * Build the config from a given environment map (defaults to process.env).
  * Pure and side-effect-free so tests can drive it with a synthetic env.
@@ -121,8 +90,6 @@ export function loadConfig(env = process.env) {
         enableTelemetry: parseBool(env.ENABLE_TELEMETRY, false, 'ENABLE_TELEMETRY'),
         otelExporterOtlpEndpoint: otelEndpoint || undefined,
         otelServiceName,
-        uploadAllowedHosts: Object.freeze(parseAllowedHosts(env.MCP_UPLOAD_ALLOWED_HOSTS)),
-        uploadMaxFetchBytes: parseUploadMaxFetchBytes(env.MCP_UPLOAD_MAX_FETCH_BYTES, DEFAULT_UPLOAD_MAX_FETCH_BYTES),
     });
 }
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/spec/enum-policy.js

@@ -0,0 +1,83 @@
+// Enum policy allow-lists — the two sanctioned escapes the enum-parity gate
+// (Task 1.3) consults when a curated tool's Zod field deliberately diverges from
+// the OpenAPI spec's declaration.
+//
+// THE POLICY (full prose + audit table: docs/enum-policy.md)
+// A curated tool models a field as a CLOSED Zod enum only for a closed,
+// slow-moving algebra — comparison operators, context cardinality (1:1|1:N|N:M),
+// fee normalization (NET|GROSS), lifecycle status transitions, fee-rule sides,
+// sort orders, and the like. Anything that GROWS — business-day calendars,
+// metadata field names, connection/config names, exception reason codes, format
+// tokens that expand — is typed as a free `string` whose `.describe()` enumerates
+// the CURRENT known values as a hint. Rationale: a closed enum that lags the
+// backend REJECTS A VALID BACKEND VALUE at the client — strictly worse than a
+// free string that lets the backend do final validation.
+//
+// HOW THE GATE USES THESE
+// The parity gate compares each curated tool field against the spec. Two
+// divergences are legitimate and must be declared here or the gate fails:
+//   - INTENTIONALLY_OPEN_FIELDS: the spec declares an enum but the tool
+//     deliberately types the field as a free string (a growing taxonomy).
+//   - INTENTIONALLY_OMITTED_FIELDS: a spec request-body/query field the curated
+//     tool deliberately does not expose (curation is opinionated). `reason` is
+//     required so the omission is a considered call, not an oversight.
+//
+// Both lists are EMPTY BY DEFAULT — add an entry only with a real, reasoned case.
+// `operationId` is compile-time constrained to a real curated operation.
+import { CURATED_OPERATION_IDS } from './curated-operations.js';
+/**
+ * Spec-enum fields the curated tools deliberately type as a free string because
+ * the underlying value set GROWS. Kept in sync with the tool source, which
+ * carries the same rationale inline at each field.
+ *
+ * NB: both current entries are OUT OF the request-body parity gate's scope —
+ * listExceptions.reason is a query param (GET, no request body) and
+ * uploadFile.format rides a multipart body (no application/json). So the parity
+ * gate never consults these entries; they are policy documentation. The
+ * free-string behavior is instead enforced by the tools' own unit tests
+ * (exception/list.test.ts and ingestion/upload.test.ts each safeParse an
+ * out-of-list value). If either field is ever moved onto a JSON request body,
+ * its entry here becomes gate-live automatically.
+ */
+export const INTENTIONALLY_OPEN_FIELDS = [
+    // Exception reason codes are minted per new engine capability (AGED_BREAK,
+    // OVER_SETTLED, FX_RATE_VARIANCE were recent). A closed filter enum would lag
+    // and reject a valid reason. -> src/tools/exception/list.ts
+    { operationId: 'listExceptions', fieldPath: 'reason' },
+    // Ingestion formats grow with the connector-parity roadmap (new parsers). A
+    // closed enum would block uploading a newly-supported format.
+    // -> src/tools/ingestion/upload.ts
+    { operationId: 'uploadFile', fieldPath: 'format' },
+];
+/**
+ * Spec request fields the curated tools deliberately do not expose. Each carries
+ * a required reason so the omission reads as a considered call, not an oversight.
+ */
+export const INTENTIONALLY_OMITTED_FIELDS = [
+    // context_create models inline `rules[]` and `sources[]` as permissive
+    // passthrough records (z.array(z.record(...))) rather than reproducing the full
+    // nested CreateMatchRule/CreateSource sub-schemas — the tool documents "prefer
+    // context_create with no rules then match_rule_create / source_create for
+    // richer control", and matcher is the authoritative validator of the inline
+    // payload. The array fields THEMSELVES are exposed; only their nested leaves are
+    // omitted here. A brand-new nested field the backend adds will still surface as
+    // a fresh drift (it won't be on this list), keeping the gate's teeth.
+    // -> src/tools/context/create.ts
+    { operationId: 'createContext', fieldPath: 'rules[].priority', reason: 'inline rules[] passed through as an opaque record; matcher validates' },
+    { operationId: 'createContext', fieldPath: 'rules[].type', reason: 'inline rules[] passed through as an opaque record; matcher validates' },
+    { operationId: 'createContext', fieldPath: 'rules[].config', reason: 'inline rules[] passed through as an opaque record; matcher validates' },
+    { operationId: 'createContext', fieldPath: 'sources[].name', reason: 'inline sources[] passed through as an opaque record; matcher validates' },
+    { operationId: 'createContext', fieldPath: 'sources[].type', reason: 'inline sources[] passed through as an opaque record; matcher validates' },
+    { operationId: 'createContext', fieldPath: 'sources[].side', reason: 'inline sources[] passed through as an opaque record; matcher validates' },
+    { operationId: 'createContext', fieldPath: 'sources[].config', reason: 'inline sources[] passed through as an opaque record; matcher validates' },
+    { operationId: 'createContext', fieldPath: 'sources[].mapping', reason: 'inline sources[] passed through as an opaque record; matcher validates' },
+];
+/**
+ * Spec-required fields the curated tools satisfy by INJECTING the value in the
+ * dispatch code rather than exposing a (required) Zod field. Empty by default —
+ * the curated tools mirror the spec's required scalars directly, so nothing is
+ * injected today. Add an entry only when a tool genuinely fills a spec-required
+ * field itself (and cite the injection site), never to silence a real gap.
+ */
+export const INTENTIONALLY_INJECTED_REQUIRED_FIELDS = [];
+//# sourceMappingURL=enum-policy.js.map

package/dist/spec/enum-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enum-policy.js","sourceRoot":"","sources":["../../src/spec/enum-policy.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,iFAAiF;AACjF,kCAAkC;AAClC,EAAE;AACF,6DAA6D;AAC7D,wEAAwE;AACxE,iFAAiF;AACjF,+EAA+E;AAC/E,2EAA2E;AAC3E,gFAAgF;AAChF,kFAAkF;AAClF,6EAA6E;AAC7E,8EAA8E;AAC9E,yDAAyD;AACzD,EAAE;AACF,0BAA0B;AAC1B,yEAAyE;AACzE,0EAA0E;AAC1E,wEAAwE;AACxE,0EAA0E;AAC1E,gFAAgF;AAChF,+EAA+E;AAC/E,uEAAuE;AACvE,EAAE;AACF,kFAAkF;AAClF,yEAAyE;AAEzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAA;AAuC/D;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAsC;IAC1E,2EAA2E;IAC3E,8EAA8E;IAC9E,4DAA4D;IAC5D,EAAE,WAAW,EAAE,gBAAgB,EAAE,SAAS,EAAE,QAAQ,EAAE;IACtD,4EAA4E;IAC5E,8DAA8D;IAC9D,mCAAmC;IACnC,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE;CACnD,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAyC;IAChF,uEAAuE;IACvE,gFAAgF;IAChF,+EAA+E;IAC/E,0EAA0E;IAC1E,4EAA4E;IAC5E,iFAAiF;IACjF,gFAAgF;IAChF,sEAAsE;IACtE,iCAAiC;IACjC,EAAE,WAAW,EAAE,eAAe,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,EAAE,sEAAsE,EAAE;IAC/I,EAAE,WAAW,EAAE,eAAe,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,EAAE,sEAAsE,EAAE;IAC3I,EAAE,WAAW,EAAE,eAAe,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,EAAE,sEAAsE,EAAE;IAC7I,EAAE,WAAW,EAAE,eAAe,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,EAAE,wEAAwE,EAAE;IAC/I,EAAE,WAAW,EAAE,eAAe,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,EAAE,wEAAwE,EAAE;IAC/I,EAAE,WAAW,EAAE,eAAe,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,EAAE,wEAAwE,EAAE;IAC/I,EAAE,WAAW,EAAE,eAAe,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,EAAE,wEAAwE,EAAE;IACjJ,EAAE,WAAW,EAAE,eAAe,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,EAAE,wEAAwE,EAAE;CACnJ,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sCAAsC,GACjD,EAAE,CAAA"}

package/dist/spec/openapi.yaml

@@ -810,6 +810,11 @@ components:
           type: string
         targetSystem:
           description: Target system to dispatch to
+          enum:
+            - JIRA
+            - SERVICENOW
+            - WEBHOOK
+            - MANUAL
           examples:
             - JIRA
           maxLength: 255
@@ -1648,7 +1653,7 @@ components:
       properties:
         config:
           additionalProperties: {}
-          description: Source-specific configuration object (connection and parsing settings).
+          description: Source-specific configuration object (connection and parsing settings). Optional; defaults to an empty object when omitted.
           type: object
         mapping:
           additionalProperties: {}
@@ -1684,7 +1689,6 @@ components:
         - name
         - type
         - side
-        - config
       type: object
     CreateExportJobRequest:
       additionalProperties: false
@@ -1702,19 +1706,16 @@ components:
           format: date
           type: string
         format:
-          description: Export file format (server normalizes to uppercase)
+          description: Export file format (uppercase only).
           enum:
             - CSV
             - JSON
             - XML
-            - csv
-            - json
-            - xml
           examples:
             - CSV
           type: string
         reportType:
-          description: Report type to export
+          description: Report type to export (uppercase only).
           enum:
             - MATCHED
             - UNMATCHED
@@ -1723,13 +1724,6 @@ components:
             - EXCEPTIONS
             - MATCHES
             - UNMATCHED_TRANSACTIONS
-            - matched
-            - unmatched
-            - summary
-            - variance
-            - exceptions
-            - matches
-            - unmatched_transactions
           examples:
             - MATCHED
           type: string
@@ -2089,7 +2083,7 @@ components:
       properties:
         config:
           additionalProperties: {}
-          description: Source-specific configuration object (connection and parsing settings).
+          description: Source-specific configuration object (connection and parsing settings). Optional; defaults to an empty object when omitted.
           type: object
         name:
           description: Human-readable name of the source.
@@ -2121,7 +2115,6 @@ components:
         - name
         - type
         - side
-        - config
       type: object
     CredentialMetadata:
       additionalProperties: false
@@ -3838,6 +3831,11 @@ components:
           examples:
             - file appears semicolon-delimited but the source declares comma; declare delimiter semicolon in the source dialect
           type: string
+        droppedDuplicateReason:
+          description: "Display-only explanation of why droppedDuplicateRows rows were dropped: names the (source, external_id) collapsing key and the field mapping to check so the count does not read as silent data loss. Empty unless droppedDuplicateRows > 0"
+          examples:
+            - Rows repeated a (source, external_id) key already present in this source and were dropped under the keep-first policy.
+          type: string
         droppedDuplicateRows:
           description: Number of rows dropped as duplicates under the keep-first policy (same external_id within the upload or already persisted)
           examples:
@@ -7395,10 +7393,7 @@ components:
             - true
           type: boolean
         feeNormalization:
-          description: Fee normalization mode. NET compares amounts after fees are deducted; GROSS compares amounts before fees.
-          enum:
-            - NET
-            - GROSS
+          description: "Fee normalization mode. NET compares amounts after fees are deducted; GROSS compares amounts before fees. Send an empty string to clear the mode; omit to leave it unchanged. (No enum constraint: unlike create, the update path accepts the empty string to clear.)"
           examples:
             - NET
           type: string

package/dist/spec/schema-parity.js

@@ -0,0 +1,393 @@
+// Curated-tool ⇄ OpenAPI request-body parity — the client-side sibling of the Go
+// `check-huma-spec` gate.
+//
+// WHY THIS EXISTS
+// A curated Zod tool (src/tools/<family>/*.ts) hand-writes its input shape and
+// dispatches a fixed method+path. `curated-operations.test.ts` already pins that
+// each tool's operation still EXISTS in the spec (structural drift). This file
+// goes one layer deeper: it diffs each curated tool's declared Zod request shape
+// against the spec's request-body JSON Schema and fails when the TOOL IS BEHIND —
+// a body property the spec added that the tool never exposes, or a closed Zod
+// enum that lags the spec's enum values. Either way an operator driving the tool
+// blind (the .describe() text is the whole product) would be unable to send a
+// field the backend accepts, or would be rejected client-side for a value the
+// backend allows. The enum-policy allow-lists (enum-policy.ts) carve out the two
+// sanctioned divergences (spec-enum→free-string, and deliberately-omitted field).
+//
+// SCOPE — A DECISION, NOT AN OVERSIGHT
+// This gate covers REQUEST-BODY parity only. Query- and path-parameter drift is
+// deliberately OUT OF SCOPE here: path params ride URL builders (a rename there
+// breaks the dispatched path, which `curated-operations.test.ts`'s method+path
+// reconciliation already guards), and the query surface is thin and mostly
+// pagination. Body shape is where a curated tool silently rots against a growing
+// backend contract, so that is what we pin.
+//
+// TOOL-AHEAD IS NOT A FAILURE
+// Extra tool properties the spec lacks (or a tool enum with MORE values than the
+// spec) are not flagged — a curated tool may intentionally lead the spec. Only
+// the tool falling BEHIND the spec bites.
+//
+// ZOD 4 INTROSPECTION
+// Dependency-free (no zod-to-json-schema). Zod 4 exposes `schema._def.type` as
+// the discriminator and `_def.innerType` for the single-child wrappers
+// (optional / default / nullable / readonly / catch / nonoptional); ZodPipe
+// (transform/refine-with-effect) carries `_def.in`; ZodEnum carries
+// `_def.entries`; ZodArray carries `_def.element`; ZodObject exposes `.shape`.
+// The self-test fixtures in schema-parity.test.ts are the correctness proof for
+// these unwrap wrinkles.
+// --- Zod side --------------------------------------------------------------
+/** Access the Zod 4 internal def, tolerating either accessor. */
+function defOf(schema) {
+    if (schema === null || typeof schema !== 'object') {
+        return undefined;
+    }
+    const s = schema;
+    const d = s._def ?? s.def;
+    return d !== null && typeof d === 'object'
+        ? d
+        : undefined;
+}
+/**
+ * Peel the transparent single-child wrappers (optional / default / nullable /
+ * readonly / catch / nonoptional via `innerType`; transform/pipe via `in`) until
+ * a "core" schema (object / array / enum / scalar / record) is reached.
+ */
+function unwrap(schema) {
+    let current = schema;
+    for (let hops = 0; hops < 50; hops += 1) {
+        const d = defOf(current);
+        if (d === undefined) {
+            return current;
+        }
+        if (d['type'] === 'pipe' && d['in'] !== undefined) {
+            current = d['in'];
+            continue;
+        }
+        if (d['innerType'] !== undefined) {
+            current = d['innerType'];
+            continue;
+        }
+        return current;
+    }
+    return current;
+}
+/**
+ * Whether a Zod field is GUARANTEED to appear in the parsed payload.
+ * Peels wrappers outermost-first: the first wrapper that decides presence wins.
+ * `optional` → 'optional' (may be absent); `default`/`catch`/`prefault` →
+ * 'guaranteed' (a value is filled when the caller omits it); `nonoptional` →
+ * 'guaranteed' (explicitly strips optionality); `nullable`/`readonly`/`pipe`
+ * are transparent for presence and are peeled through. A bare scalar/object/
+ * array with no wrapper is required.
+ */
+function presenceOf(schema) {
+    let current = schema;
+    for (let hops = 0; hops < 50; hops += 1) {
+        const d = defOf(current);
+        if (d === undefined) {
+            return 'guaranteed';
+        }
+        const type = d['type'];
+        if (type === 'optional') {
+            return 'optional';
+        }
+        if (type === 'default' || type === 'catch' || type === 'prefault') {
+            return 'guaranteed';
+        }
+        if (type === 'nonoptional') {
+            return 'guaranteed';
+        }
+        if (type === 'pipe' && d['in'] !== undefined) {
+            current = d['in'];
+            continue;
+        }
+        if (d['innerType'] !== undefined) {
+            current = d['innerType'];
+            continue;
+        }
+        return 'guaranteed';
+    }
+    return 'guaranteed';
+}
+/** Recurse a Zod schema, appending property paths and closed enums to `out`. */
+function walkZod(schema, path, out) {
+    const core = unwrap(schema);
+    const d = defOf(core);
+    const type = d?.['type'];
+    if (type === 'object') {
+        const shape = core.shape ?? {};
+        for (const [key, child] of Object.entries(shape)) {
+            const childPath = path ? `${path}.${key}` : key;
+            out.propertyPaths.add(childPath);
+            if (presenceOf(child) === 'guaranteed') {
+                out.requiredPaths.add(childPath);
+            }
+            walkZod(child, childPath, out);
+        }
+        return;
+    }
+    if (type === 'array') {
+        const element = core.element ?? d?.['element'];
+        if (element !== undefined) {
+            walkZod(element, `${path}[]`, out);
+        }
+        return;
+    }
+    if (type === 'enum' && path) {
+        const entries = d?.['entries'];
+        if (entries !== null && typeof entries === 'object') {
+            out.closedEnums.set(path, new Set(Object.values(entries).map(String)));
+        }
+        return;
+    }
+    // record / string / number / boolean / unknown → leaf; nothing to add.
+}
+/**
+ * Introspect a curated tool's `ZodRawShape` into its property paths and closed
+ * enums. Wrapper types are unwrapped; arrays recurse into their element under a
+ * `[]` segment; enums surface their `.options`.
+ */
+export function introspectShape(shape) {
+    const out = {
+        propertyPaths: new Set(),
+        closedEnums: new Map(),
+        requiredPaths: new Set(),
+    };
+    for (const [key, schema] of Object.entries(shape)) {
+        out.propertyPaths.add(key);
+        if (presenceOf(schema) === 'guaranteed') {
+            out.requiredPaths.add(key);
+        }
+        walkZod(schema, key, out);
+    }
+    return out;
+}
+// --- Spec side -------------------------------------------------------------
+/**
+ * Recurse an (already-dereferenced) JSON Schema fragment into `out`.
+ *
+ * FLAT-SCHEMA-ONLY (invariant, not a bug): traverses `properties`/`items`/`enum`
+ * only. Composition keywords (allOf/oneOf/anyOf) are NOT descended into — Huma
+ * emits flat schemas and the shipped spec has zero of them (a schema-parity.test
+ * canary asserts this stays true). If the generator ever emits a composed body,
+ * a property/enum under the composition would be invisible here (fail-OPEN), so
+ * the canary trips RED first, forcing composition traversal to be added.
+ */
+function walkSpec(node, path, out) {
+    if (node === null || typeof node !== 'object') {
+        return;
+    }
+    const obj = node;
+    const enumVals = obj['enum'];
+    if (Array.isArray(enumVals) && path) {
+        out.closedEnums.set(path, new Set(enumVals.map(String)));
+    }
+    // `required` lists property NAMES required at THIS object level; project each
+    // onto the same dot/bracket path notation as its property entry below.
+    const required = obj['required'];
+    if (Array.isArray(required)) {
+        for (const name of required) {
+            if (typeof name === 'string') {
+                out.requiredPaths.add(path ? `${path}.${name}` : name);
+            }
+        }
+    }
+    const properties = obj['properties'];
+    if (properties !== null && typeof properties === 'object') {
+        for (const [key, child] of Object.entries(properties)) {
+            const childPath = path ? `${path}.${key}` : key;
+            out.propertyPaths.add(childPath);
+            walkSpec(child, childPath, out);
+        }
+    }
+    const items = obj['items'];
+    if (items !== undefined) {
+        walkSpec(items, `${path}[]`, out);
+    }
+}
+/**
+ * Introspect a spec request-body JSON Schema (as produced by the loader, refs
+ * already inlined) into its property paths and enums — same path notation as
+ * {@link introspectShape} so the two are directly comparable.
+ */
+export function introspectSpecSchema(schema) {
+    const out = {
+        propertyPaths: new Set(),
+        closedEnums: new Map(),
+        requiredPaths: new Set(),
+    };
+    walkSpec(schema, '', out);
+    return out;
+}
+/**
+ * Diff a curated tool's Zod shape against a spec request-body schema, honoring
+ * the per-op allow-lists. Returns every gap where the TOOL IS BEHIND the spec.
+ * Pure — the gate and the self-test both drive it.
+ */
+export function compareShapeToSpec(shape, specSchema, allow) {
+    const tool = introspectShape(shape);
+    const spec = introspectSpecSchema(specSchema);
+    const findings = [];
+    // (1) Spec property the tool never exposes → missing, unless omitted-allow-listed.
+    for (const fieldPath of spec.propertyPaths) {
+        if (tool.propertyPaths.has(fieldPath)) {
+            continue;
+        }
+        if (allow.omittedFields.has(fieldPath)) {
+            continue;
+        }
+        findings.push({ kind: 'missing-property', fieldPath });
+    }
+    // (2)/(3) Spec enums vs the tool's modeling of the same field.
+    for (const [fieldPath, specValues] of spec.closedEnums) {
+        if (!tool.propertyPaths.has(fieldPath)) {
+            // Absent entirely — already reported (or allow-listed) by pass (1).
+            continue;
+        }
+        const toolValues = tool.closedEnums.get(fieldPath);
+        if (toolValues !== undefined) {
+            // (2) Closed tool enum must be a superset of the spec's values.
+            const missing = [...specValues].filter((v) => !toolValues.has(v));
+            if (missing.length > 0) {
+                findings.push({ kind: 'enum-missing-values', fieldPath, missing });
+            }
+            continue;
+        }
+        // (3) Spec enum, but the tool types it as a free string — only OK if declared.
+        if (!allow.openFields.has(fieldPath)) {
+            findings.push({ kind: 'enum-modeled-as-string', fieldPath });
+        }
+    }
+    return findings;
+}
+/** A required path is unconditional only at the top level (no parent container). */
+function isTopLevel(fieldPath) {
+    return !fieldPath.includes('.') && !fieldPath.includes('[');
+}
+/**
+ * Diff the required-ness of a curated tool's fields against a spec request body.
+ * Returns every gap, its `kind` carrying the severity the gate applies:
+ * `spec-required-*` FAIL, `tool-required-spec-optional` WARN. Pure — the gate
+ * and the self-test both drive it.
+ */
+export function compareRequiredArrays(shape, specSchema, allow) {
+    const tool = introspectShape(shape);
+    const spec = introspectSpecSchema(specSchema);
+    const findings = [];
+    // FAIL direction: every spec-required field must be guaranteed by the tool.
+    for (const fieldPath of spec.requiredPaths) {
+        if (tool.requiredPaths.has(fieldPath)) {
+            continue; // tool guarantees it (non-optional or has a default)
+        }
+        if (allow.injectedFields.has(fieldPath)) {
+            continue; // tool code fills it before dispatch — invisible but accounted for
+        }
+        if (tool.propertyPaths.has(fieldPath)) {
+            // Exposed but optional → caller can omit a required field.
+            findings.push({ kind: 'spec-required-tool-optional', fieldPath });
+            continue;
+        }
+        // Not exposed at all. Absence of a NON-allow-listed field is coverage's job
+        // (compareShapeToSpec's missing-property). We only add value for the case
+        // coverage can't see: a TOP-LEVEL required field suppressed by the omitted
+        // allow-list — an unconditional 422 on every call. Nested paths under an
+        // optional/opaque container are conditional and passed through, so skip them.
+        if (isTopLevel(fieldPath) && allow.omittedFields.has(fieldPath)) {
+            findings.push({ kind: 'spec-required-tool-omitted', fieldPath });
+        }
+    }
+    // WARN direction: a tool-required field the spec exposes but marks optional.
+    for (const fieldPath of tool.requiredPaths) {
+        if (!spec.propertyPaths.has(fieldPath)) {
+            continue; // tool-ahead extra the spec lacks — not an over-constraint of it
+        }
+        if (!spec.requiredPaths.has(fieldPath)) {
+            findings.push({ kind: 'tool-required-spec-optional', fieldPath });
+        }
+    }
+    return findings;
+}
+// --- The shape table -------------------------------------------------------
+//
+// Each curated operation whose spec entry declares an application/json request
+// body maps here to the tool's exported input shape. The completeness guard in
+// the test derives the required key set from CURATED_OPERATION_IDS ∩ (spec ops
+// with a JSON body). So for any op ALREADY in CURATED_OPERATION_IDS, adding or
+// retargeting its curated body-tool without wiring the shape here fails the gate
+// (missing on one side, extra on the other).
+//
+// SCOPE LIMIT (do not overstate this): because the required set is filtered
+// through the hand-maintained CURATED_OPERATION_IDS, this parity gate does NOT
+// see an op that has a JSON body but is left in GENERIC_ONLY_OPERATION_IDS —
+// hand-curate a Zod body-tool for such an op without promoting it into
+// CURATED_OPERATION_IDS (and without wiring it here) and no field-parity test
+// runs for it. That promotion/triage is guarded separately by
+// curated-operations.test.ts (curated⇄generic disjointness + frozen counts +
+// inverse spec coverage), not by field parity here. GET/list/delete ops (no
+// body) and uploadFile (multipart, no application/json body) are absent by design.
+import { addCommentInputShape } from '../tools/exception/add-comment.js';
+import { adjustEntryInputShape } from '../tools/exception/adjust-entry.js';
+import { bulkAssignInputShape } from '../tools/exception/bulk-assign.js';
+import { bulkDispatchInputShape } from '../tools/exception/bulk-dispatch.js';
+import { bulkResolveInputShape } from '../tools/exception/bulk-resolve.js';
+import { closeDisputeInputShape } from '../tools/dispute/close.js';
+import { createContextInputShape } from '../tools/context/create.js';
+import { createFeeRuleInputShape } from '../tools/fee-rule/create.js';
+import { createFeeScheduleInputShape } from '../tools/fee-schedule/create.js';
+import { createFieldMapInputShape } from '../tools/field-map/create.js';
+import { createMatchRuleInputShape } from '../tools/match-rule/create.js';
+import { createSourceInputShape } from '../tools/source/create.js';
+import { dispatchExceptionInputShape } from '../tools/exception/dispatch.js';
+import { forceMatchInputShape } from '../tools/exception/force-match.js';
+import { ignoreTransactionInputShape } from '../tools/ingestion/transaction-ignore.js';
+import { openDisputeInputShape } from '../tools/exception/open-dispute.js';
+import { reorderMatchRulesInputShape } from '../tools/match-rule/reorder.js';
+import { simulateFeeScheduleInputShape } from '../tools/fee-schedule/simulate.js';
+import { startMatchRunInputShape } from '../tools/matching/start.js';
+import { submitEvidenceInputShape } from '../tools/dispute/submit-evidence.js';
+import { updateContextInputShape } from '../tools/context/update.js';
+import { updateFeeRuleInputShape } from '../tools/fee-rule/update.js';
+import { updateFeeScheduleInputShape } from '../tools/fee-schedule/update.js';
+import { updateFieldMapInputShape } from '../tools/field-map/update.js';
+import { updateMatchRuleInputShape } from '../tools/match-rule/update.js';
+import { updateSourceInputShape } from '../tools/source/update.js';
+/** operationId → the curated tool's request-body input shape. */
+export const TOOL_SHAPE_BY_OPERATION_ID = {
+    // fee-schedule
+    createFeeSchedule: createFeeScheduleInputShape,
+    simulateFeeSchedule: simulateFeeScheduleInputShape,
+    updateFeeSchedule: updateFeeScheduleInputShape,
+    // fee-rule
+    createFeeRule: createFeeRuleInputShape,
+    updateFeeRule: updateFeeRuleInputShape,
+    // match-rule
+    createMatchRule: createMatchRuleInputShape,
+    reorderMatchRules: reorderMatchRulesInputShape,
+    updateMatchRule: updateMatchRuleInputShape,
+    // context
+    createContext: createContextInputShape,
+    updateContext: updateContextInputShape,
+    // source
+    createSource: createSourceInputShape,
+    updateSource: updateSourceInputShape,
+    // field-map
+    createFieldMap: createFieldMapInputShape,
+    updateFieldMap: updateFieldMapInputShape,
+    // matching
+    runMatch: startMatchRunInputShape,
+    // exception
+    addComment: addCommentInputShape,
+    adjustEntryException: adjustEntryInputShape,
+    bulkAssignExceptions: bulkAssignInputShape,
+    bulkDispatchExceptions: bulkDispatchInputShape,
+    bulkResolveExceptions: bulkResolveInputShape,
+    dispatchException: dispatchExceptionInputShape,
+    forceMatchException: forceMatchInputShape,
+    openDispute: openDisputeInputShape,
+    // dispute
+    closeDispute: closeDisputeInputShape,
+    submitEvidence: submitEvidenceInputShape,
+    // ingestion
+    ignoreTransaction: ignoreTransactionInputShape,
+};
+//# sourceMappingURL=schema-parity.js.map