@lerianstudio/matcher-mcp 5.0.0-beta.13 → 5.0.0-beta.130

package/dist/spec/openapi.yaml

@@ -184,6 +184,9 @@ components:
           type: string
         direction:
           description: "Direction of the entry: DEBIT explains a shortfall (moves the outstanding variance up, toward zero), CREDIT explains a surplus (moves it down)"
+          enum:
+            - DEBIT
+            - CREDIT
           examples:
             - DEBIT
           type: string
@@ -209,6 +212,12 @@ components:
           type: string
         type:
           description: "Adjustment type: BANK_FEE (bank charge), FX_DIFFERENCE (currency conversion variance), ROUNDING (minor-unit rounding), WRITE_OFF (uncollectible balance), or MISCELLANEOUS (other)"
+          enum:
+            - BANK_FEE
+            - FX_DIFFERENCE
+            - ROUNDING
+            - WRITE_OFF
+            - MISCELLANEOUS
           examples:
             - BANK_FEE
           type: string
@@ -230,6 +239,33 @@ components:
         - createdAt
         - updatedAt
       type: object
+    AdminAssignPlanInputBody:
+      additionalProperties: false
+      properties:
+        plan:
+          description: "The plan code to assign. ONLY \"enterprise\" is accepted: self-serve plans are bought through checkout and converged from the live subscription's price, so assigning one here would be a payment-processor bypass the next processor delivery silently reverts. Any other code is refused with 409."
+          maxLength: 64
+          type: string
+      required:
+        - plan
+      type: object
+    AdminAssignPlanResult:
+      additionalProperties: false
+      properties:
+        billingStatus:
+          description: The commercial standing the workspace now holds. An enterprise contract is in good standing the moment it is signed, so this is always "active".
+          type: string
+        plan:
+          description: The plan the workspace now holds.
+          type: string
+        slug:
+          description: The workspace assigned.
+          type: string
+      required:
+        - slug
+        - plan
+        - billingStatus
+      type: object
     AdminWorkspaceBilling:
       additionalProperties: false
       properties:
@@ -321,10 +357,15 @@ components:
       additionalProperties: false
       properties:
         accountRef:
-          description: Stored opaque vendor account reference (Pluggy itemId, Belvo link id)
+          description: Stored opaque vendor account reference (Pluggy itemId, Belvo link id); empty while the connection is awaiting consent
           examples:
             - a1b2c3d4-5678-90ab-cdef-1234567890ab
           type: string
+        awaitingConsent:
+          description: Whether the connection is still awaiting the end customer's vendor consent (no vendor item/link bound yet)
+          examples:
+            - false
+          type: boolean
         baseUrl:
           description: Stored vendor API base URL
           examples:
@@ -342,7 +383,7 @@ components:
             - a1b2c3d4-5678-90ab-cdef-1234567890ab
           type: string
         testable:
-          description: Whether Matcher can run a connectivity test for this connection's aggregator vendor
+          description: Whether Matcher can run a connectivity test for this connection right now (its vendor has a test path AND it is bound to a vendor item/link)
           examples:
             - true
           type: boolean
@@ -361,6 +402,7 @@ components:
         - baseUrl
         - accountRef
         - testable
+        - awaitingConsent
       type: object
     AggregatorConnectionListResponse:
       additionalProperties: false
@@ -400,10 +442,9 @@ components:
       additionalProperties: false
       properties:
         accountRef:
-          description: Opaque vendor account reference (Pluggy itemId, Belvo link id) the webhook pull threads onto its request
+          description: Opaque vendor account reference (Pluggy itemId, Belvo link id) the webhook pull threads onto its request. Omit to create a connection awaiting consent — the connect flow binds it after the end customer authorizes.
           examples:
             - a1b2c3d4-5678-90ab-cdef-1234567890ab
-          minLength: 1
           type: string
         baseUrl:
           description: Vendor API base URL, stored as the connection host
@@ -438,7 +479,6 @@ components:
         - vendor
         - configName
         - baseUrl
-        - accountRef
         - clientId
         - secret
       type: object
@@ -446,10 +486,15 @@ components:
       additionalProperties: false
       properties:
         accountRef:
-          description: Stored opaque vendor account reference (Pluggy itemId, Belvo link id)
+          description: Stored opaque vendor account reference (Pluggy itemId, Belvo link id); empty while the connection is awaiting consent
           examples:
             - a1b2c3d4-5678-90ab-cdef-1234567890ab
           type: string
+        awaitingConsent:
+          description: Whether the connection is still awaiting the end customer's vendor consent (no vendor item/link bound yet)
+          examples:
+            - false
+          type: boolean
         baseUrl:
           description: Stored vendor API base URL
           examples:
@@ -474,6 +519,52 @@ components:
         - configName
         - baseUrl
         - accountRef
+        - awaitingConsent
+      type: object
+    AggregatorConsentTokenResponse:
+      additionalProperties: false
+      properties:
+        accountRef:
+          description: Vendor item/link id this token was scoped to (the stored binding); empty on a first consent. Pass it to the vendor widget's update mode alongside the token — do not substitute a locally cached value.
+          examples:
+            - a1b2c3d4-5678-90ab-cdef-1234567890ab
+          type: string
+        configName:
+          description: Config name of the connection the token was minted for
+          examples:
+            - pluggy-main
+          type: string
+        expiresAt:
+          description: UTC instant after which the vendor rejects this consent token
+          examples:
+            - "2026-08-23T12:30:00Z"
+          format: date-time
+          type: string
+        reconsent:
+          description: Whether the token re-authorizes the connection's existing vendor item/link (true) or will create a new one (false)
+          examples:
+            - false
+          type: boolean
+        token:
+          description: Short-lived, widget-ready consent token. Returned exactly once and never stored — pass it to the vendor widget and discard it.
+          examples:
+            - eyJhbGciOi...
+          type: string
+        vendor:
+          description: Aggregator vendor the consent token was minted against
+          enum:
+            - pluggy
+            - belvo
+          examples:
+            - pluggy
+          type: string
+      required:
+        - vendor
+        - configName
+        - token
+        - expiresAt
+        - reconsent
+        - accountRef
       type: object
     ApproveExtractionResponse:
       additionalProperties: false
@@ -638,6 +729,12 @@ components:
             - 0
           format: int64
           type: integer
+        fromSeq:
+          description: "Effective verification floor: the first tenant_seq eligible for inspection (1 when fromSeq was omitted). Resume a truncated run at fromSeq + verifiedCount"
+          examples:
+            - 1
+          format: int64
+          type: integer
         intact:
           description: True when every inspected record links to the previous one and matches its stored hash
           examples:
@@ -656,6 +753,7 @@ components:
           type: integer
       required:
         - intact
+        - fromSeq
         - verifiedCount
         - truncated
       type: object
@@ -937,7 +1035,15 @@ components:
       additionalProperties: false
       properties:
         canonicalKey:
-          description: Canonical field-map key (e.g. amount, external_id, currency, date)
+          description: Canonical field-map key. The closed vocabulary is the required keys (external_id, amount, currency, date) plus the optional ones (description, fee_amount, fee_currency); the extractor drops any key outside it before a candidate is persisted
+          enum:
+            - external_id
+            - amount
+            - currency
+            - date
+            - description
+            - fee_amount
+            - fee_currency
           examples:
             - amount
           type: string
@@ -1007,6 +1113,11 @@ components:
           type: string
         ruleType:
           description: Strategy of the rule that produced the best score
+          enum:
+            - EXACT
+            - TOLERANCE
+            - DATE_LAG
+            - FUZZY
           examples:
             - EXACT
           type: string
@@ -1065,6 +1176,9 @@ components:
             - "null"
         source:
           description: "Extraction lane that produced this candidate: text_layer (PDF text, higher trust) or vision (OCR/vision model, lower trust)"
+          enum:
+            - text_layer
+            - vision
           examples:
             - text_layer
           type: string
@@ -1779,6 +1893,14 @@ components:
           type:
             - array
             - "null"
+        signConvention:
+          description: "How this context's data carries sign. SAME: a payment carries the same sign as what it settles, so a negative amount is a reversal. OPPOSITE: a payment carries the opposite sign of the invoice it settles. Defaults to SAME."
+          enum:
+            - SAME
+            - OPPOSITE
+          examples:
+            - SAME
+          type: string
         sources:
           description: Sources to create inline with the context.
           items:
@@ -1806,7 +1928,91 @@ components:
       properties:
         config:
           additionalProperties: {}
-          description: "Source-specific configuration object (connection and parsing settings). Optional; defaults to an empty object when omitted. Reserved key duplicate_key: the ordered list of mapped fields that make two rows the same row — any of external_id, amount, currency, date, description, fee_amount, fee_currency. Omit it and rows are deduplicated on external_id alone. A field this source's field map does not fill is refused, because a key over a field that is always empty makes every row a duplicate of every other. A source bound to an aggregator connection (reserved key connection_config_name) cannot carry a duplicate key of its own: the aggregator retracts a movement by naming its external id, so that id has to stay this source's row identity. A config holding both is refused in either direction — drop duplicate_key from a bound source, or disconnect the aggregator connection first. Reserved read-only key duplicate_key_changed_at: the RFC 3339 moment duplicate-key detection last changed meaning on this source, set by the server; a value sent by a client is discarded. It moves for either change that re-keys future rows — editing duplicate_key, or the field map remapping the column a declared field reads (a source keyed on description whose description column moves derives a different key for the same movement). Reserved key duplicate_policy: what happens to a row repeating the duplicate key — FLAG_AS_EXCEPTION (the default: the repeat is kept out of the import and raised as a duplicate exception on the row it repeated), KEEP_FIRST (the repeat is dropped and nothing is raised), or REJECT (the repeat is counted as an import error). Changing duplicate_key governs later imports only — rows already imported keep the key they were deduplicated under."
+          description: "Source-specific configuration object. Cross-key rules the schema cannot express: a duplicate_key component this source's field map does not fill is refused, because a key over an always-empty field makes every row a duplicate of every other; a source bound to an aggregator connection (reserved key connection_config_name) cannot carry a duplicate_key of its own, and a config holding both is refused in either direction; and editing duplicate_key governs later imports only — rows already imported keep the key they were deduplicated under, so a duplicate straddling the change is knowingly not detected."
+          properties:
+            blank_external_id:
+              description: What happens to a row whose mapped external id is blank. REJECT (the default when the key is absent) fails the row. NEEDS_REVIEW imports it under a synthetic reference with status PENDING_REVIEW, so a blank reference becomes a reviewable import instead of an import failure.
+              enum:
+                - REJECT
+                - NEEDS_REVIEW
+              type: string
+            camt053:
+              additionalProperties: false
+              description: How this source's camt.053 files map onto the canonical fields. Every other field is fixed by ISO 20022 itself. An absent object, or an absent sub-key, keeps the ISO defaults (booking, ntry_ref).
+              properties:
+                date_basis:
+                  description: "Entry date element: booking is BookgDt/Dt, valuation is ValDt/Dt. Default booking."
+                  enum:
+                    - booking
+                    - valuation
+                  type: string
+                external_id_source:
+                  description: "Entry reference element: ntry_ref is NtryRef, end_to_end_id is NtryDtls/TxDtls/Refs/EndToEndId, tx_id is NtryDtls/TxDtls/Refs/TxId. Default ntry_ref."
+                  enum:
+                    - ntry_ref
+                    - end_to_end_id
+                    - tx_id
+                  type: string
+              type: object
+            dialect:
+              additionalProperties: false
+              description: How this source's delimited files are encoded and formatted. Declaration-driven only — there is no auto-detection. An absent object, or an absent sub-key, keeps the defaults (utf-8, comma, dot, iso).
+              properties:
+                date_style:
+                  enum:
+                    - iso
+                    - iso_offset
+                    - dmy
+                    - mdy
+                  type: string
+                decimal_style:
+                  description: dot is 1234.56, comma is 1.234,56.
+                  enum:
+                    - dot
+                    - comma
+                  type: string
+                delimiter:
+                  enum:
+                    - comma
+                    - semicolon
+                    - tab
+                    - pipe
+                  type: string
+                encoding:
+                  enum:
+                    - utf-8
+                    - utf-8-sig
+                    - cp1252
+                    - iso-8859-1
+                  type: string
+              type: object
+            duplicate_key:
+              description: The ordered list of mapped fields that make two rows the same row. Absent means external_id alone. On a source bound to an aggregator connection the aggregator retracts a movement by naming its external id, so that id has to stay the row identity.
+              items:
+                enum:
+                  - external_id
+                  - amount
+                  - currency
+                  - date
+                  - description
+                  - fee_amount
+                  - fee_currency
+                type: string
+              minItems: 1
+              type: array
+              uniqueItems: true
+            duplicate_policy:
+              description: What happens to a row that repeats this source's duplicate key. FLAG_AS_EXCEPTION (the default when the key is absent) keeps the repeat out of the import and raises a duplicate exception on the row it repeated. KEEP_FIRST drops the repeat and raises nothing, so a collision leaves no trace anyone can act on. REJECT counts the repeat as an import error.
+              enum:
+                - FLAG_AS_EXCEPTION
+                - KEEP_FIRST
+                - REJECT
+              type: string
+            fail_on_error_rate_percent:
+              description: "Fail the whole import when the percentage of failed rows exceeds this whole number. Absent means never auto-fail. The ceiling is 99, not 100: the comparison is strict, so 100 could never fire."
+              maximum: 99
+              minimum: 1
+              type: integer
           type: object
         mapping:
           additionalProperties: {}
@@ -1976,10 +2182,10 @@ components:
           type: integer
         structure:
           additionalProperties: {}
-          description: "Type-specific structure. FLAT: {\"amount\":\"1.50\"}. PERCENTAGE: {\"rate\":\"0.029\"} where rate is a 0..1 fraction of the base amount (0.029 means 2.9%), not a percent value. TIERED: {\"tiers\":[{\"rate\":\"0.01\",\"upTo\":\"1000\"},...]} with the same 0..1 fraction semantics per tier rate. EXPRESSION: {\"expression\":\"gross - desconto + multa + juros_dia * days_late(due_date, pay_date)\"} a formula over metadata fields (+ - * /, parentheses, and the functions days_late, days_between, max, min, abs, clamp)."
+          description: "Type-specific structure. FLAT: {\"amount\":\"1.50\"}. PERCENTAGE: {\"rate\":\"0.029\"} where rate is a 0..1 fraction of the base amount (0.029 means 2.9%), not a percent value. TIERED: {\"tiers\":[{\"rate\":\"0.01\",\"upTo\":\"1000\"},...]} with the same 0..1 fraction semantics per tier rate. EXPRESSION: {\"expression\":\"gross - desconto + multa + juros_dia * days_late(due_date, pay_date)\"} a formula over metadata fields (+ - * /, parentheses, and the functions days_late, days_between, max, min, abs, clamp). A formula that is only the base amount times numeric literals is a percentage rate and is bounded 0..1: gross * 0.029 is 2.9%, gross * 2.9 is refused; any other formula is unbounded."
           type: object
         structureType:
-          description: Shape of the fee structure. FLAT is a fixed amount; PERCENTAGE is a rate of the base; TIERED applies different rates per amount tier; EXPRESSION computes the fee from a bounded arithmetic formula over transaction metadata.
+          description: Shape of the fee structure; the structure field documents the object each one takes.
           enum:
             - FLAT
             - PERCENTAGE
@@ -2236,7 +2442,91 @@ components:
       properties:
         config:
           additionalProperties: {}
-          description: "Source-specific configuration object (connection and parsing settings). Optional; defaults to an empty object when omitted. Reserved key duplicate_key: the ordered list of mapped fields that make two rows the same row — any of external_id, amount, currency, date, description, fee_amount, fee_currency. Omit it and rows are deduplicated on external_id alone. A field this source's field map does not fill is refused, because a key over a field that is always empty makes every row a duplicate of every other. A source bound to an aggregator connection (reserved key connection_config_name) cannot carry a duplicate key of its own: the aggregator retracts a movement by naming its external id, so that id has to stay this source's row identity. A config holding both is refused in either direction — drop duplicate_key from a bound source, or disconnect the aggregator connection first. Reserved read-only key duplicate_key_changed_at: the RFC 3339 moment duplicate-key detection last changed meaning on this source, set by the server; a value sent by a client is discarded. It moves for either change that re-keys future rows — editing duplicate_key, or the field map remapping the column a declared field reads (a source keyed on description whose description column moves derives a different key for the same movement). Reserved key duplicate_policy: what happens to a row repeating the duplicate key — FLAG_AS_EXCEPTION (the default: the repeat is kept out of the import and raised as a duplicate exception on the row it repeated), KEEP_FIRST (the repeat is dropped and nothing is raised), or REJECT (the repeat is counted as an import error). Changing duplicate_key governs later imports only — rows already imported keep the key they were deduplicated under."
+          description: "Source-specific configuration object. Cross-key rules the schema cannot express: a duplicate_key component this source's field map does not fill is refused, because a key over an always-empty field makes every row a duplicate of every other; a source bound to an aggregator connection (reserved key connection_config_name) cannot carry a duplicate_key of its own, and a config holding both is refused in either direction; and editing duplicate_key governs later imports only — rows already imported keep the key they were deduplicated under, so a duplicate straddling the change is knowingly not detected."
+          properties:
+            blank_external_id:
+              description: What happens to a row whose mapped external id is blank. REJECT (the default when the key is absent) fails the row. NEEDS_REVIEW imports it under a synthetic reference with status PENDING_REVIEW, so a blank reference becomes a reviewable import instead of an import failure.
+              enum:
+                - REJECT
+                - NEEDS_REVIEW
+              type: string
+            camt053:
+              additionalProperties: false
+              description: How this source's camt.053 files map onto the canonical fields. Every other field is fixed by ISO 20022 itself. An absent object, or an absent sub-key, keeps the ISO defaults (booking, ntry_ref).
+              properties:
+                date_basis:
+                  description: "Entry date element: booking is BookgDt/Dt, valuation is ValDt/Dt. Default booking."
+                  enum:
+                    - booking
+                    - valuation
+                  type: string
+                external_id_source:
+                  description: "Entry reference element: ntry_ref is NtryRef, end_to_end_id is NtryDtls/TxDtls/Refs/EndToEndId, tx_id is NtryDtls/TxDtls/Refs/TxId. Default ntry_ref."
+                  enum:
+                    - ntry_ref
+                    - end_to_end_id
+                    - tx_id
+                  type: string
+              type: object
+            dialect:
+              additionalProperties: false
+              description: How this source's delimited files are encoded and formatted. Declaration-driven only — there is no auto-detection. An absent object, or an absent sub-key, keeps the defaults (utf-8, comma, dot, iso).
+              properties:
+                date_style:
+                  enum:
+                    - iso
+                    - iso_offset
+                    - dmy
+                    - mdy
+                  type: string
+                decimal_style:
+                  description: dot is 1234.56, comma is 1.234,56.
+                  enum:
+                    - dot
+                    - comma
+                  type: string
+                delimiter:
+                  enum:
+                    - comma
+                    - semicolon
+                    - tab
+                    - pipe
+                  type: string
+                encoding:
+                  enum:
+                    - utf-8
+                    - utf-8-sig
+                    - cp1252
+                    - iso-8859-1
+                  type: string
+              type: object
+            duplicate_key:
+              description: The ordered list of mapped fields that make two rows the same row. Absent means external_id alone. On a source bound to an aggregator connection the aggregator retracts a movement by naming its external id, so that id has to stay the row identity.
+              items:
+                enum:
+                  - external_id
+                  - amount
+                  - currency
+                  - date
+                  - description
+                  - fee_amount
+                  - fee_currency
+                type: string
+              minItems: 1
+              type: array
+              uniqueItems: true
+            duplicate_policy:
+              description: What happens to a row that repeats this source's duplicate key. FLAG_AS_EXCEPTION (the default when the key is absent) keeps the repeat out of the import and raises a duplicate exception on the row it repeated. KEEP_FIRST drops the repeat and raises nothing, so a collision leaves no trace anyone can act on. REJECT counts the repeat as an import error.
+              enum:
+                - FLAG_AS_EXCEPTION
+                - KEEP_FIRST
+                - REJECT
+              type: string
+            fail_on_error_rate_percent:
+              description: "Fail the whole import when the percentage of failed rows exceeds this whole number. Absent means never auto-fail. The ceiling is 99, not 100: the comparison is strict, so 100 could never fire."
+              maximum: 99
+              minimum: 1
+              type: integer
           type: object
         name:
           description: Human-readable name of the source.
@@ -2432,6 +2722,11 @@ components:
         sla:
           $ref: "#/components/schemas/SLAStatsResponse"
           description: SLA compliance statistics for the window.
+        unmatchedByCurrency:
+          description: Unreconciled exposure split by currency; the amounts sum to volume.unmatchedAmount. Empty when no transaction in the window is UNMATCHED or PENDING_REVIEW; always an array, never null. volume.unmatchedAmount is the engine's arithmetic sum of those amounts across currencies, so it is a meaningful money figure only when this split carries a single currency. Clients must not render it as money when the split names more than one currency.
+          items:
+            $ref: "#/components/schemas/CurrencyExposureResponse"
+          type: array
         updatedAt:
           description: Timestamp when these aggregates were computed (RFC 3339, UTC).
           examples:
@@ -2445,6 +2740,7 @@ components:
         - volume
         - matchRate
         - sla
+        - unmatchedByCurrency
         - updatedAt
       type: object
     Detail:
@@ -2500,21 +2796,39 @@ components:
       properties:
         dateStyle:
           description: "Detected date convention: iso (YYYY-MM-DD), iso_offset (RFC 3339 with offset), dmy (DD/MM/YYYY), or mdy (MM/DD/YYYY)"
+          enum:
+            - iso
+            - iso_offset
+            - dmy
+            - mdy
           examples:
             - iso
           type: string
         decimalStyle:
           description: "Detected amount decimal convention: dot (1234.56) or comma (1234,56)"
+          enum:
+            - dot
+            - comma
           examples:
             - comma
           type: string
         delimiter:
           description: "Detected CSV field separator: comma, semicolon, tab, or pipe"
+          enum:
+            - comma
+            - semicolon
+            - tab
+            - pipe
           examples:
             - semicolon
           type: string
         encoding:
           description: "Detected file character encoding: utf-8, utf-8-sig (UTF-8 with BOM), cp1252 (Windows Latin-1), or iso-8859-1"
+          enum:
+            - utf-8
+            - utf-8-sig
+            - cp1252
+            - iso-8859-1
           examples:
             - utf-8
           type: string
@@ -2606,11 +2920,12 @@ components:
       additionalProperties: false
       properties:
         category:
-          description: "Dispute category: BANK_FEE_ERROR (incorrect fee), UNRECOGNIZED_CHARGE, DUPLICATE_TRANSACTION, or OTHER"
+          description: "Dispute category: BANK_FEE_ERROR (incorrect fee), UNRECOGNIZED_CHARGE, DUPLICATE_TRANSACTION, AMOUNT_MISMATCH, or OTHER"
           enum:
             - BANK_FEE_ERROR
             - UNRECOGNIZED_CHARGE
             - DUPLICATE_TRANSACTION
+            - AMOUNT_MISMATCH
             - OTHER
           examples:
             - BANK_FEE_ERROR
@@ -2770,7 +3085,7 @@ components:
       additionalProperties: false
       properties:
         amount:
-          description: "Enrichment: the exception transaction's amount as a decimal string in the transaction's currency. Present on list rows whose transaction still exists; absent on the get-by-id/resolution paths and when the transaction was deleted."
+          description: "Enrichment: the exception transaction's amount as a decimal string in the transaction's currency. Present on list rows and get-by-id when the transaction still exists."
           examples:
             - "1250.50"
           type: string
@@ -2780,7 +3095,7 @@ components:
             - user@example.com
           type: string
         contextId:
-          description: "Enrichment: id of the reconciliation context the exception's source belongs to (UUID). Present on list rows whose transaction and source still exist; powers the global triage queue's context attribution."
+          description: "Enrichment: id of the reconciliation context the exception's source belongs to (UUID). Present on list rows and get-by-id when the transaction and source still exist; powers the global triage queue's context attribution."
           examples:
             - 550e8400-e29b-41d4-a716-446655440004
           type: string
@@ -2790,7 +3105,7 @@ components:
             - "2025-01-15T10:30:00Z"
           type: string
         currency:
-          description: "Enrichment: ISO 4217 currency code of the exception transaction's amount. Present on list rows whose transaction still exists."
+          description: "Enrichment: ISO 4217 currency code of the exception transaction's amount. Present on list rows and get-by-id when the transaction still exists."
           examples:
             - USD
           type: string
@@ -2852,6 +3167,9 @@ components:
           examples:
             - 550e8400-e29b-41d4-a716-446655440002
           type: string
+        settlement:
+          $ref: "#/components/schemas/ExceptionSettlementResponse"
+          description: Settlement figures for a fee break (expected vs credited and the signed difference), derived from the live fee-variance snapshot recorded for the exception's transaction. Present on get-by-id only, and only when the snapshot and the transaction amount are both available in the same currency.
         severity:
           description: "Severity level: LOW and MEDIUM are informational, HIGH needs prompt review, CRITICAL requires immediate action"
           enum:
@@ -2863,21 +3181,27 @@ components:
             - HIGH
           type: string
         sourceId:
-          description: "Enrichment: id of the reconciliation source the exception transaction belongs to (UUID). Present on list rows whose transaction still exists."
+          description: "Enrichment: id of the reconciliation source the exception transaction belongs to (UUID). Present on list rows and get-by-id when the transaction still exists."
           examples:
             - 550e8400-e29b-41d4-a716-446655440003
           type: string
+        sourceName:
+          description: "Enrichment: display name of the reconciliation source. Present on get-by-id when the transaction and its source still exist."
+          examples:
+            - Bank feed
+          type: string
         status:
-          description: "Lifecycle status: OPEN (unhandled), ASSIGNED (owned by a user), RESOLVED (closed out)"
+          description: "Lifecycle status: OPEN (unhandled), ASSIGNED (owned by a user), PENDING_RESOLUTION (a resolution is in flight), RESOLVED (closed out)"
           enum:
             - OPEN
             - ASSIGNED
+            - PENDING_RESOLUTION
             - RESOLVED
           examples:
             - OPEN
           type: string
         transactionDate:
-          description: "Enrichment: the exception transaction's value date as an RFC 3339 timestamp. Present on list rows whose transaction still exists."
+          description: "Enrichment: the exception transaction's value date as an RFC 3339 timestamp. Present on list rows and get-by-id when the transaction still exists."
           examples:
             - "2025-01-14T00:00:00Z"
           type: string
@@ -2899,6 +3223,35 @@ components:
         - createdAt
         - updatedAt
       type: object
+    ExceptionSettlementResponse:
+      additionalProperties: false
+      properties:
+        credited:
+          description: Amount actually credited (the transaction amount), as a decimal string
+          examples:
+            - "95.00"
+          type: string
+        currency:
+          description: ISO 4217 currency code of the settlement amounts (the transaction's currency)
+          examples:
+            - BRL
+          type: string
+        difference:
+          description: Signed difference credited minus expected, as a decimal string; negative when the credit fell short
+          examples:
+            - "-2.00"
+          type: string
+        expected:
+          description: Amount the transaction should have credited under the expected fee, as a decimal string
+          examples:
+            - "97.00"
+          type: string
+      required:
+        - expected
+        - credited
+        - difference
+        - currency
+      type: object
     ExportCountResponse:
       additionalProperties: false
       properties:
@@ -3074,6 +3427,8 @@ components:
           type: string
         status:
           description: Lifecycle status of the queued review (always PENDING_REVIEW on enqueue)
+          enum:
+            - PENDING_REVIEW
           examples:
             - PENDING_REVIEW
           type: string
@@ -3228,6 +3583,10 @@ components:
           type: string
         status:
           description: "Review lifecycle: PENDING_REVIEW (awaiting decision), APPROVED (candidates ingested), REJECTED (discarded)"
+          enum:
+            - PENDING_REVIEW
+            - APPROVED
+            - REJECTED
           examples:
             - PENDING_REVIEW
           type: string
@@ -3367,7 +3726,7 @@ components:
           type: integer
         structure:
           additionalProperties: {}
-          description: "Type-specific structure. FLAT: {\"amount\":\"1.50\"}. PERCENTAGE: {\"rate\":\"0.029\"} where rate is a 0..1 fraction of the base amount (0.029 means 2.9%), not a percent value. TIERED: {\"tiers\":[{\"rate\":\"0.01\",\"upTo\":\"1000\"},...]} with the same 0..1 fraction semantics per tier rate. EXPRESSION: {\"expression\":\"gross - desconto + multa + juros_dia * days_late(due_date, pay_date)\"} a formula over metadata fields (+ - * /, parentheses, and the functions days_late, days_between, max, min, abs, clamp)."
+          description: "Type-specific structure. FLAT: {\"amount\":\"1.50\"}. PERCENTAGE: {\"rate\":\"0.029\"} where rate is a 0..1 fraction of the base amount (0.029 means 2.9%), not a percent value. TIERED: {\"tiers\":[{\"rate\":\"0.01\",\"upTo\":\"1000\"},...]} with the same 0..1 fraction semantics per tier rate. EXPRESSION: {\"expression\":\"gross - desconto + multa + juros_dia * days_late(due_date, pay_date)\"} a formula over metadata fields (+ - * /, parentheses, and the functions days_late, days_between, max, min, abs, clamp). A formula that is only the base amount times numeric literals is a percentage rate and is bounded 0..1: gross * 0.029 is 2.9%, gross * 2.9 is refused; any other formula is unbounded."
           type: object
         structureType:
           description: Shape of the fee structure. FLAT is a fixed amount; PERCENTAGE is a rate of the base; TIERED applies different rates per amount tier; EXPRESSION computes the fee from a bounded arithmetic formula over transaction metadata.
@@ -3680,7 +4039,15 @@ components:
       additionalProperties: false
       properties:
         canonicalKey:
-          description: Canonical field-map key the proposal targets
+          description: Canonical field-map key the proposal targets. The closed vocabulary is the required keys (external_id, amount, currency, date) plus the optional ones (description, fee_amount, fee_currency); the advisor drops any key outside it before the proposal is returned
+          enum:
+            - external_id
+            - amount
+            - currency
+            - date
+            - description
+            - fee_amount
+            - fee_currency
           examples:
             - amount
           type: string
@@ -3993,9 +4360,13 @@ components:
             - TXN-12345
           type: string
         extractionStatus:
-          description: "Field-extraction status: PENDING (queued), EXTRACTED (fields parsed), FAILED (extraction error)"
+          description: "Field-extraction status: PENDING (queued), COMPLETE (fields parsed), FAILED (extraction error)"
+          enum:
+            - PENDING
+            - COMPLETE
+            - FAILED
           examples:
-            - EXTRACTED
+            - COMPLETE
           type: string
         id:
           description: Unique identifier for the transaction
@@ -4020,9 +4391,14 @@ components:
           format: uuid
           type: string
         status:
-          description: "Matching status: PENDING (not yet evaluated), MATCHED (reconciled), UNMATCHED (no match found)"
+          description: "Matching status: UNMATCHED (no match found), MATCHED (reconciled), IGNORED (excluded from reconciliation by an operator), PENDING_REVIEW (imported under the blank-external-id review policy and awaiting an operator decision)"
+          enum:
+            - UNMATCHED
+            - MATCHED
+            - IGNORED
+            - PENDING_REVIEW
           examples:
-            - PENDING
+            - UNMATCHED
           type: string
       required:
         - id
@@ -4142,6 +4518,11 @@ components:
           type: string
         status:
           description: "Job lifecycle status: QUEUED (awaiting a worker), PROCESSING (parsing/normalizing rows), COMPLETED (finished), FAILED (aborted wholesale)"
+          enum:
+            - QUEUED
+            - PROCESSING
+            - COMPLETED
+            - FAILED
           examples:
             - PROCESSING
           type: string
@@ -4212,7 +4593,11 @@ components:
       additionalProperties: false
       properties:
         kind:
-          description: "Value type: string (raw text), decimal (money/numeric verbatim token, parsed downstream), or date. A money column MUST be decimal"
+          description: "Value type: string (raw text), decimal (money/numeric verbatim token, parsed downstream), or date. A money column MUST be decimal — declaring it string or date is refused by the server-side submission gate, which the schema enum does not replace"
+          enum:
+            - string
+            - decimal
+            - date
           examples:
             - decimal
           type: string
@@ -4244,6 +4629,10 @@ components:
       properties:
         kind:
           description: "Value type: string (raw text), decimal (money/numeric verbatim token, parsed downstream), or date"
+          enum:
+            - string
+            - decimal
+            - date
           examples:
             - decimal
           type: string
@@ -5209,7 +5598,12 @@ components:
             - 550e8400-e29b-41d4-a716-446655440000
           type: string
         status:
-          description: "Current status of the group: PROPOSED (awaiting review), CONFIRMED (accepted), or REJECTED (broken/unmatched)"
+          description: "Current status of the group: PROPOSED (awaiting review), CONFIRMED (accepted), REJECTED (a proposed group discarded before confirmation), or REVOKED (a confirmed group whose confirmation was later undone by an unmatch; the original confirmation timestamp is kept for audit)"
+          enum:
+            - PROPOSED
+            - CONFIRMED
+            - REJECTED
+            - REVOKED
           examples:
             - PROPOSED
           type: string
@@ -5268,6 +5662,9 @@ components:
           type: string
         side:
           description: "Reconciliation side of the item's source: LEFT or RIGHT. Resolved from the transaction's source; absent when the source side could not be resolved"
+          enum:
+            - LEFT
+            - RIGHT
           examples:
             - LEFT
           type: string
@@ -5426,6 +5823,9 @@ components:
           type: string
         mode:
           description: "Execution mode: DRY_RUN evaluates rules without committing matches; COMMIT persists matches"
+          enum:
+            - DRY_RUN
+            - COMMIT
           examples:
             - DRY_RUN
           type: string
@@ -5445,10 +5845,10 @@ components:
           additionalProperties:
             format: int64
             type: integer
-          description: Aggregate run statistics as an open key-value map; consumers must tolerate unknown keys and treat a missing key as unknown rather than zero. Known keys include matches, candidates_left, candidates_right, unmatched_left, unmatched_right, unmatched_external, auto_matched_left, auto_matched_right, pending_review_left, pending_review_right, proposed_left, proposed_right, exceptions_raised (newly created), exceptions_updated (re-touched), plus per-rule families rule_matched:<ruleID> and rule_meta:<ruleID>:<TYPE>
+          description: Aggregate run statistics as an open key-value map; consumers must tolerate unknown keys and treat a missing key as unknown rather than zero. Known keys include matches, candidates_left, candidates_right, unmatched_left, unmatched_right, unmatched_external, auto_matched_left, auto_matched_right, pending_review_left, pending_review_right, proposed_left, proposed_right, exceptions_raised (newly created), exceptions_updated (re-touched), plus per-rule families rule_matched:<ruleID> and rule_meta:<ruleID>:<TYPE>. A run recovered after an interruption reports the exception rows its earlier attempt created under exceptions_updated, not exceptions_raised
           type: object
         status:
-          description: "Current status of the run: QUEUED (async submit, awaiting worker pickup), PROCESSING (in flight), FINALIZING (a transient finishing-up state — a poll MAY briefly observe it between PROCESSING and COMPLETED, and it is also observable while a run is recovered after a crash; treat it as in-flight, not terminal), COMPLETED (finished), or FAILED (errored)"
+          description: "Current status of the run: QUEUED (async submit, awaiting worker pickup), PROCESSING (in flight), FINALIZING (a transient finishing-up state — a poll MAY briefly observe it between PROCESSING and COMPLETED, and it is also observable while a run is recovered after a crash; treat it as in-flight, not terminal), COMPLETED (finished), or FAILED (errored). An async run in flight when its pod stops goes back from PROCESSING to QUEUED and is picked up again with a new startedAt"
           enum:
             - QUEUED
             - PROCESSING
@@ -5493,14 +5893,18 @@ components:
             - 550e8400-e29b-41d4-a716-446655440000
           type: string
         type:
-          description: "Rule type at run time: EXACT (strict equality), TOLERANCE (within an amount band), DATE_LAG (allowing a settlement-date offset), or FUZZY (normalized/similarity-scored references, always proposes)"
+          description: "Rule type at run time: EXACT (strict equality), TOLERANCE (within an amount band), DATE_LAG (allowing a settlement-date offset), or FUZZY (normalized/similarity-scored references, always proposes). Absent when the run recorded a match count for the rule without its metadata sibling"
+          enum:
+            - EXACT
+            - TOLERANCE
+            - DATE_LAG
+            - FUZZY
           examples:
             - EXACT
           type: string
       required:
         - ruleId
         - priority
-        - type
         - matched
       type: object
     MatchedItemResponse:
@@ -5713,6 +6117,12 @@ components:
           type: string
         status:
           description: "Lifecycle status: OPEN (fresh residual), PARTIALLY_CLEARED (a leg netted but a residual remains), CLEARED (netted within tolerance), AGED (exceeded its aging threshold while still open), or WITHDRAWN (the confirmed match that opened it was un-matched, so the obligation was taken back with it)"
+          enum:
+            - OPEN
+            - PARTIALLY_CLEARED
+            - CLEARED
+            - AGED
+            - WITHDRAWN
           examples:
             - PARTIALLY_CLEARED
           type: string
@@ -5995,6 +6405,14 @@ components:
           examples:
             - Bank Reconciliation Q1
           type: string
+        signConvention:
+          description: "How this context's data carries sign. SAME: a payment carries the same sign as what it settles, so a negative amount is a reversal. OPPOSITE: a payment carries the opposite sign of the invoice it settles."
+          enum:
+            - SAME
+            - OPPOSITE
+          examples:
+            - SAME
+          type: string
         status:
           description: Lifecycle status. DRAFT is being configured; ACTIVE runs; PAUSED is suspended; ARCHIVED is retired.
           enum:
@@ -6034,6 +6452,7 @@ components:
         - feeToleranceAbs
         - feeTolerancePct
         - autoMatchOnUpload
+        - signConvention
         - createdAt
         - updatedAt
       type: object
@@ -6047,7 +6466,96 @@ components:
           type: string
         config:
           additionalProperties: {}
-          description: Source-specific configuration object (connection and parsing settings). duplicate_key holds the ordered list of mapped fields that make two rows the same row; absent means rows are deduplicated on external_id alone. duplicate_key_changed_at is the server-set RFC 3339 moment duplicate-key detection last changed meaning on this source — either that list changing, or the field map remapping the column a declared field reads; rows imported before it keep the key they were deduplicated under.
+          description: "Source-specific configuration object. Cross-key rules the schema cannot express: a duplicate_key component this source's field map does not fill is refused, because a key over an always-empty field makes every row a duplicate of every other; a source bound to an aggregator connection (reserved key connection_config_name) cannot carry a duplicate_key of its own, and a config holding both is refused in either direction; and editing duplicate_key governs later imports only — rows already imported keep the key they were deduplicated under, so a duplicate straddling the change is knowingly not detected."
+          properties:
+            blank_external_id:
+              description: What happens to a row whose mapped external id is blank. REJECT (the default when the key is absent) fails the row. NEEDS_REVIEW imports it under a synthetic reference with status PENDING_REVIEW, so a blank reference becomes a reviewable import instead of an import failure.
+              enum:
+                - REJECT
+                - NEEDS_REVIEW
+              type: string
+            camt053:
+              additionalProperties: false
+              description: How this source's camt.053 files map onto the canonical fields. Every other field is fixed by ISO 20022 itself. An absent object, or an absent sub-key, keeps the ISO defaults (booking, ntry_ref).
+              properties:
+                date_basis:
+                  description: "Entry date element: booking is BookgDt/Dt, valuation is ValDt/Dt. Default booking."
+                  enum:
+                    - booking
+                    - valuation
+                  type: string
+                external_id_source:
+                  description: "Entry reference element: ntry_ref is NtryRef, end_to_end_id is NtryDtls/TxDtls/Refs/EndToEndId, tx_id is NtryDtls/TxDtls/Refs/TxId. Default ntry_ref."
+                  enum:
+                    - ntry_ref
+                    - end_to_end_id
+                    - tx_id
+                  type: string
+              type: object
+            dialect:
+              additionalProperties: false
+              description: How this source's delimited files are encoded and formatted. Declaration-driven only — there is no auto-detection. An absent object, or an absent sub-key, keeps the defaults (utf-8, comma, dot, iso).
+              properties:
+                date_style:
+                  enum:
+                    - iso
+                    - iso_offset
+                    - dmy
+                    - mdy
+                  type: string
+                decimal_style:
+                  description: dot is 1234.56, comma is 1.234,56.
+                  enum:
+                    - dot
+                    - comma
+                  type: string
+                delimiter:
+                  enum:
+                    - comma
+                    - semicolon
+                    - tab
+                    - pipe
+                  type: string
+                encoding:
+                  enum:
+                    - utf-8
+                    - utf-8-sig
+                    - cp1252
+                    - iso-8859-1
+                  type: string
+              type: object
+            duplicate_key:
+              description: The ordered list of mapped fields that make two rows the same row. Absent means external_id alone. On a source bound to an aggregator connection the aggregator retracts a movement by naming its external id, so that id has to stay the row identity.
+              items:
+                enum:
+                  - external_id
+                  - amount
+                  - currency
+                  - date
+                  - description
+                  - fee_amount
+                  - fee_currency
+                type: string
+              minItems: 1
+              type: array
+              uniqueItems: true
+            duplicate_key_changed_at:
+              description: SERVER-OWNED. The moment duplicate-key detection last changed meaning on this source, either because duplicate_key was edited or because the field map remapped the column a declared component reads. Rows imported before it keep the key they were deduplicated under. A value sent by a client is discarded.
+              format: date-time
+              readOnly: true
+              type: string
+            duplicate_policy:
+              description: What happens to a row that repeats this source's duplicate key. FLAG_AS_EXCEPTION (the default when the key is absent) keeps the repeat out of the import and raises a duplicate exception on the row it repeated. KEEP_FIRST drops the repeat and raises nothing, so a collision leaves no trace anyone can act on. REJECT counts the repeat as an import error.
+              enum:
+                - FLAG_AS_EXCEPTION
+                - KEEP_FIRST
+                - REJECT
+              type: string
+            fail_on_error_rate_percent:
+              description: "Fail the whole import when the percentage of failed rows exceeds this whole number. Absent means never auto-fail. The ceiling is 99, not 100: the comparison is strict, so 100 could never fire."
+              maximum: 99
+              minimum: 1
+              type: integer
           type: object
         contextId:
           description: Identifier of the context this source belongs to.
@@ -6223,7 +6731,11 @@ components:
             - near-miss amounts cluster under 1%
           type: string
         type:
-          description: "Proposed rule type from the closed vocabulary: EXACT (strict equality), TOLERANCE (within an amount band), or DATE_LAG (allowing a settlement-date offset)"
+          description: "Proposed rule type from the closed vocabulary: EXACT (strict equality), TOLERANCE (within an amount band), or DATE_LAG (allowing a settlement-date offset). FUZZY is excluded on purpose: a fuzzy rule only ever proposes graded-confidence links a human must review, so an operator configures one deliberately rather than accepting it from a suggestion"
+          enum:
+            - EXACT
+            - TOLERANCE
+            - DATE_LAG
           examples:
             - TOLERANCE
           type: string
@@ -6302,6 +6814,10 @@ components:
           type: string
         status:
           description: "Lifecycle status: PENDING_REVIEW (awaiting human decision), APPROVED (rule created), or REJECTED (discarded)"
+          enum:
+            - PENDING_REVIEW
+            - APPROVED
+            - REJECTED
           examples:
             - PENDING_REVIEW
           type: string
@@ -6668,7 +7184,9 @@ components:
       required:
         - id
         - status
-      type: object
+      type:
+        - object
+        - "null"
     SetupProgressMatchRulesResponse:
       additionalProperties: false
       properties:
@@ -6730,7 +7248,9 @@ components:
         - method
         - path
         - requiredFields
-      type: object
+      type:
+        - object
+        - "null"
     SetupProgressReadinessResponse:
       additionalProperties: false
       properties:
@@ -7060,6 +7580,11 @@ components:
           type: string
         ruleType:
           description: Strategy of the previewed rule
+          enum:
+            - EXACT
+            - TOLERANCE
+            - DATE_LAG
+            - FUZZY
           examples:
             - EXACT
           type: string
@@ -7107,6 +7632,11 @@ components:
           type: object
         type:
           description: Rule strategy of the inline candidate rule
+          enum:
+            - EXACT
+            - TOLERANCE
+            - DATE_LAG
+            - FUZZY
           examples:
             - EXACT
           type: string
@@ -7373,7 +7903,96 @@ components:
           type: string
         config:
           additionalProperties: {}
-          description: Source-specific configuration object (connection and parsing settings). duplicate_key holds the ordered list of mapped fields that make two rows the same row; absent means rows are deduplicated on external_id alone. duplicate_key_changed_at is the server-set RFC 3339 moment duplicate-key detection last changed meaning on this source — either that list changing, or the field map remapping the column a declared field reads; rows imported before it keep the key they were deduplicated under.
+          description: "Source-specific configuration object. Cross-key rules the schema cannot express: a duplicate_key component this source's field map does not fill is refused, because a key over an always-empty field makes every row a duplicate of every other; a source bound to an aggregator connection (reserved key connection_config_name) cannot carry a duplicate_key of its own, and a config holding both is refused in either direction; and editing duplicate_key governs later imports only — rows already imported keep the key they were deduplicated under, so a duplicate straddling the change is knowingly not detected."
+          properties:
+            blank_external_id:
+              description: What happens to a row whose mapped external id is blank. REJECT (the default when the key is absent) fails the row. NEEDS_REVIEW imports it under a synthetic reference with status PENDING_REVIEW, so a blank reference becomes a reviewable import instead of an import failure.
+              enum:
+                - REJECT
+                - NEEDS_REVIEW
+              type: string
+            camt053:
+              additionalProperties: false
+              description: How this source's camt.053 files map onto the canonical fields. Every other field is fixed by ISO 20022 itself. An absent object, or an absent sub-key, keeps the ISO defaults (booking, ntry_ref).
+              properties:
+                date_basis:
+                  description: "Entry date element: booking is BookgDt/Dt, valuation is ValDt/Dt. Default booking."
+                  enum:
+                    - booking
+                    - valuation
+                  type: string
+                external_id_source:
+                  description: "Entry reference element: ntry_ref is NtryRef, end_to_end_id is NtryDtls/TxDtls/Refs/EndToEndId, tx_id is NtryDtls/TxDtls/Refs/TxId. Default ntry_ref."
+                  enum:
+                    - ntry_ref
+                    - end_to_end_id
+                    - tx_id
+                  type: string
+              type: object
+            dialect:
+              additionalProperties: false
+              description: How this source's delimited files are encoded and formatted. Declaration-driven only — there is no auto-detection. An absent object, or an absent sub-key, keeps the defaults (utf-8, comma, dot, iso).
+              properties:
+                date_style:
+                  enum:
+                    - iso
+                    - iso_offset
+                    - dmy
+                    - mdy
+                  type: string
+                decimal_style:
+                  description: dot is 1234.56, comma is 1.234,56.
+                  enum:
+                    - dot
+                    - comma
+                  type: string
+                delimiter:
+                  enum:
+                    - comma
+                    - semicolon
+                    - tab
+                    - pipe
+                  type: string
+                encoding:
+                  enum:
+                    - utf-8
+                    - utf-8-sig
+                    - cp1252
+                    - iso-8859-1
+                  type: string
+              type: object
+            duplicate_key:
+              description: The ordered list of mapped fields that make two rows the same row. Absent means external_id alone. On a source bound to an aggregator connection the aggregator retracts a movement by naming its external id, so that id has to stay the row identity.
+              items:
+                enum:
+                  - external_id
+                  - amount
+                  - currency
+                  - date
+                  - description
+                  - fee_amount
+                  - fee_currency
+                type: string
+              minItems: 1
+              type: array
+              uniqueItems: true
+            duplicate_key_changed_at:
+              description: SERVER-OWNED. The moment duplicate-key detection last changed meaning on this source, either because duplicate_key was edited or because the field map remapped the column a declared component reads. Rows imported before it keep the key they were deduplicated under. A value sent by a client is discarded.
+              format: date-time
+              readOnly: true
+              type: string
+            duplicate_policy:
+              description: What happens to a row that repeats this source's duplicate key. FLAG_AS_EXCEPTION (the default when the key is absent) keeps the repeat out of the import and raises a duplicate exception on the row it repeated. KEEP_FIRST drops the repeat and raises nothing, so a collision leaves no trace anyone can act on. REJECT counts the repeat as an import error.
+              enum:
+                - FLAG_AS_EXCEPTION
+                - KEEP_FIRST
+                - REJECT
+              type: string
+            fail_on_error_rate_percent:
+              description: "Fail the whole import when the percentage of failed rows exceeds this whole number. Absent means never auto-fail. The ceiling is 99, not 100: the comparison is strict, so 100 could never fire."
+              maximum: 99
+              minimum: 1
+              type: integer
           type: object
         contextId:
           description: Identifier of the context this source belongs to.
@@ -7692,9 +8311,13 @@ components:
             - TXN-12345
           type: string
         extractionStatus:
-          description: "Field-extraction status: PENDING (queued), EXTRACTED (fields parsed), FAILED (extraction error)"
+          description: "Field-extraction status: PENDING (queued), COMPLETE (fields parsed), FAILED (extraction error)"
+          enum:
+            - PENDING
+            - COMPLETE
+            - FAILED
           examples:
-            - EXTRACTED
+            - COMPLETE
           type: string
         id:
           description: Unique identifier for the transaction
@@ -7719,9 +8342,14 @@ components:
           format: uuid
           type: string
         status:
-          description: "Matching status: PENDING (not yet evaluated), MATCHED (reconciled), UNMATCHED (no match found)"
+          description: "Matching status: UNMATCHED (no match found), MATCHED (reconciled), IGNORED (excluded from reconciliation by an operator), PENDING_REVIEW (imported under the blank-external-id review policy and awaiting an operator decision)"
+          enum:
+            - UNMATCHED
+            - MATCHED
+            - IGNORED
+            - PENDING_REVIEW
           examples:
-            - PENDING
+            - UNMATCHED
           type: string
       required:
         - id
@@ -7868,34 +8496,27 @@ components:
       additionalProperties: false
       properties:
         accountRef:
-          description: Opaque vendor account reference (Pluggy itemId, Belvo link id) the webhook pull threads onto its request
+          description: Opaque vendor account reference (Pluggy itemId, Belvo link id). Supply it to bind (or re-bind) the connection after the vendor's consent widget returns one; omit it to leave the stored value untouched.
           examples:
             - a1b2c3d4-5678-90ab-cdef-1234567890ab
-          minLength: 1
           type: string
         baseUrl:
-          description: Vendor API base URL, stored as the connection host
+          description: Vendor API base URL, stored as the connection host. Omit it to leave the stored URL untouched.
           examples:
             - https://api.pluggy.ai
           format: uri
-          minLength: 1
           type: string
         clientId:
           description: Aggregator API client id (optional; supply with secret to rotate, omit both to keep the stored credential; sealed; never emitted)
           type: string
         configName:
-          description: Unique connection config name (tenant-scoped); the mint endpoint binds a token to this name
+          description: Unique connection config name (tenant-scoped); the mint endpoint binds a token to this name. Omit it to leave the stored name untouched.
           examples:
             - pluggy-main
-          minLength: 1
           type: string
         secret:
           description: Aggregator API client secret (optional; supply with clientId to rotate, omit both to keep the stored credential; sealed; never emitted)
           type: string
-      required:
-        - configName
-        - baseUrl
-        - accountRef
       type: object
     UpdateContextRequest:
       additionalProperties: false
@@ -7943,6 +8564,14 @@ components:
             - Bank Reconciliation Q2
           maxLength: 100
           type: string
+        signConvention:
+          description: "How this context's data carries sign. SAME: a payment carries the same sign as what it settles, so a negative amount is a reversal. OPPOSITE: a payment carries the opposite sign of the invoice it settles. Omit to leave it unchanged."
+          enum:
+            - SAME
+            - OPPOSITE
+          examples:
+            - OPPOSITE
+          type: string
         status:
           description: Lifecycle status to transition to. ACTIVE runs the context; PAUSED suspends scheduling; ARCHIVED retires it.
           enum:
@@ -8116,7 +8745,91 @@ components:
       properties:
         config:
           additionalProperties: {}
-          description: "Source-specific configuration object (connection and parsing settings). Reserved key duplicate_key: the ordered list of mapped fields that make two rows the same row — any of external_id, amount, currency, date, description, fee_amount, fee_currency. Send it empty of that key and rows are deduplicated on external_id alone. A field this source's field map does not fill is refused, because a key over a field that is always empty makes every row a duplicate of every other. A source bound to an aggregator connection (reserved key connection_config_name) cannot carry a duplicate key of its own: the aggregator retracts a movement by naming its external id, so that id has to stay this source's row identity. A config holding both is refused in either direction — drop duplicate_key from a bound source, or disconnect the aggregator connection first. Editing duplicate_key is allowed at any time and governs later imports only: rows already imported keep the key they were deduplicated under, and a duplicate straddling the change is knowingly not detected. Reserved read-only key duplicate_key_changed_at: the RFC 3339 moment duplicate-key detection last changed meaning on this source, set by the server; a value sent by a client is discarded. It moves for either change that re-keys future rows — editing duplicate_key, or the field map remapping the column a declared field reads (a source keyed on description whose description column moves derives a different key for the same movement). Reserved key duplicate_policy: what happens to a row repeating the duplicate key — FLAG_AS_EXCEPTION (the default: the repeat is kept out of the import and raised as a duplicate exception on the row it repeated), KEEP_FIRST (the repeat is dropped and nothing is raised), or REJECT (the repeat is counted as an import error)."
+          description: "Source-specific configuration object. Cross-key rules the schema cannot express: a duplicate_key component this source's field map does not fill is refused, because a key over an always-empty field makes every row a duplicate of every other; a source bound to an aggregator connection (reserved key connection_config_name) cannot carry a duplicate_key of its own, and a config holding both is refused in either direction; and editing duplicate_key governs later imports only — rows already imported keep the key they were deduplicated under, so a duplicate straddling the change is knowingly not detected."
+          properties:
+            blank_external_id:
+              description: What happens to a row whose mapped external id is blank. REJECT (the default when the key is absent) fails the row. NEEDS_REVIEW imports it under a synthetic reference with status PENDING_REVIEW, so a blank reference becomes a reviewable import instead of an import failure.
+              enum:
+                - REJECT
+                - NEEDS_REVIEW
+              type: string
+            camt053:
+              additionalProperties: false
+              description: How this source's camt.053 files map onto the canonical fields. Every other field is fixed by ISO 20022 itself. An absent object, or an absent sub-key, keeps the ISO defaults (booking, ntry_ref).
+              properties:
+                date_basis:
+                  description: "Entry date element: booking is BookgDt/Dt, valuation is ValDt/Dt. Default booking."
+                  enum:
+                    - booking
+                    - valuation
+                  type: string
+                external_id_source:
+                  description: "Entry reference element: ntry_ref is NtryRef, end_to_end_id is NtryDtls/TxDtls/Refs/EndToEndId, tx_id is NtryDtls/TxDtls/Refs/TxId. Default ntry_ref."
+                  enum:
+                    - ntry_ref
+                    - end_to_end_id
+                    - tx_id
+                  type: string
+              type: object
+            dialect:
+              additionalProperties: false
+              description: How this source's delimited files are encoded and formatted. Declaration-driven only — there is no auto-detection. An absent object, or an absent sub-key, keeps the defaults (utf-8, comma, dot, iso).
+              properties:
+                date_style:
+                  enum:
+                    - iso
+                    - iso_offset
+                    - dmy
+                    - mdy
+                  type: string
+                decimal_style:
+                  description: dot is 1234.56, comma is 1.234,56.
+                  enum:
+                    - dot
+                    - comma
+                  type: string
+                delimiter:
+                  enum:
+                    - comma
+                    - semicolon
+                    - tab
+                    - pipe
+                  type: string
+                encoding:
+                  enum:
+                    - utf-8
+                    - utf-8-sig
+                    - cp1252
+                    - iso-8859-1
+                  type: string
+              type: object
+            duplicate_key:
+              description: The ordered list of mapped fields that make two rows the same row. Absent means external_id alone. On a source bound to an aggregator connection the aggregator retracts a movement by naming its external id, so that id has to stay the row identity.
+              items:
+                enum:
+                  - external_id
+                  - amount
+                  - currency
+                  - date
+                  - description
+                  - fee_amount
+                  - fee_currency
+                type: string
+              minItems: 1
+              type: array
+              uniqueItems: true
+            duplicate_policy:
+              description: What happens to a row that repeats this source's duplicate key. FLAG_AS_EXCEPTION (the default when the key is absent) keeps the repeat out of the import and raises a duplicate exception on the row it repeated. KEEP_FIRST drops the repeat and raises nothing, so a collision leaves no trace anyone can act on. REJECT counts the repeat as an import error.
+              enum:
+                - FLAG_AS_EXCEPTION
+                - KEEP_FIRST
+                - REJECT
+              type: string
+            fail_on_error_rate_percent:
+              description: "Fail the whole import when the percentage of failed rows exceeds this whole number. Absent means never auto-fail. The ceiling is 99, not 100: the comparison is strict, so 100 could never fire."
+              maximum: 99
+              minimum: 1
+              type: integer
           type: object
         name:
           description: New human-readable name of the source.
@@ -8391,7 +9104,7 @@ components:
           format: int64
           type: integer
         monthlyLineAllowance:
-          description: Billable lines the plan includes per month, from the price list. Monthly on every plan regardless of billing interval. 0 when the stored plan code is not in the catalogue.
+          description: Billable lines the plan includes per month, from the price list. Monthly on every plan regardless of billing interval. 0 when the plan is unmetered (see volumeUnmetered) or the stored plan code is not in the catalogue.
           format: int64
           type: integer
         overageCreditBalanceCents:
@@ -8399,7 +9112,7 @@ components:
           format: int64
           type: integer
         overageRateCentsPerThousandLines:
-          description: What lines beyond the allowance cost, in integer BRL cents per THOUSAND lines (per-thousand because the entry rate is 0,4 cents a line and would truncate to zero). 0 when the stored plan code is not in the catalogue.
+          description: What lines beyond the allowance cost, in integer BRL cents per THOUSAND lines (per-thousand because the entry rate is 0,4 cents a line and would truncate to zero). 0 when the plan is unmetered (see volumeUnmetered) or the stored plan code is not in the catalogue.
           format: int64
           type: integer
         overageUncoveredCents:
@@ -8416,7 +9129,7 @@ components:
           description: "Setup lifecycle of the workspace: \"provisioning\" (still being built), \"active\" (ready to use), or \"failed\" (setup will not complete on its own — we have been told)."
           type: string
         provisioningStep:
-          description: "The setup step that is owed: \"create_tenant\", \"associate_service\", \"migrate_tenant\", \"provision_console\", or \"\" when nothing is owed. On a failed workspace this is the step it died on."
+          description: "The setup step that is owed: \"create_tenant\", \"associate_service\", \"migrate_tenant\", \"provision_console\", \"grant_admin\", or \"\" when nothing is owed. On a failed workspace this is the step it died on."
           type: string
         trialEndsAt:
           description: When the free trial ends (UTC). Omitted for a paid plan that never trialed.
@@ -8425,6 +9138,9 @@ components:
         trialExpired:
           description: Whether the trial is over on EITHER axis (time or volume), or the workspace is already suspended.
           type: boolean
+        volumeUnmetered:
+          description: "Whether this plan is unmetered: its volume ceiling and its overage price are contractual (enterprise) rather than from the price list. When true, monthlyLineAllowance and overageRateCentsPerThousandLines are both 0 because no figure applies — do NOT render them as terms, and do not read the zero rate as free overage."
+          type: boolean
       required:
         - plan
         - billingStatus
@@ -8437,6 +9153,7 @@ components:
         - provisioningState
         - provisioningStep
         - provisioningFailed
+        - volumeUnmetered
         - monthlyLineAllowance
         - overageRateCentsPerThousandLines
         - overageCreditBalanceCents
@@ -8473,7 +9190,22 @@ info:
     email: support@lerian.studio
     name: Lerian Studio Support
     url: https://discord.gg/DnhqKwkGv3
-  description: Reconciliation engine for the Lerian Studio ecosystem. Provides automated transaction matching between Midaz ledger and external systems.
+  description: |-
+    Reconciliation engine for the Lerian Studio ecosystem. Provides automated transaction matching between Midaz ledger and external systems.
+
+    ## Idempotency
+
+    POST, PUT and PATCH requests accept an optional `X-Idempotency` header. It is the one header a key travels in and it has no synonym: a mutating request that carries an older spelling and no `X-Idempotency` is refused with 400 rather than processed unkeyed. Keys are 1-128 characters of letters, digits, hyphen, underscore or colon, are scoped per tenant, caller, method and request target, and are strictly opt-in: a request sent without the header is never de-duplicated. A retry under a key whose first attempt completed replays that stored response and carries `X-Idempotency-Replayed: true`; a retry that arrives while the first attempt is still in flight is refused with 409.
+
+    A retry must repeat the original request. On an ordinary route the body is part of what identifies it, so a completed key re-sent with a DIFFERENT body is refused with 422 and nothing is applied — send the correction under a new key. The two file routes (`POST /v1/imports/contexts/{contextId}/sources/{sourceId}/upload` and the matching `/preview`) consume their body as a live stream and cannot re-read it, so there the key itself is the identity under that method and path: a completed key re-sent replays the first answer whatever file the retry carries.
+
+    A key is ONE attempt. A refusal the request earned is recorded like any other answer, and every resend under that key replays it for the retention window — a caller that wants to correct its request mints a new key. Three answers do NOT spend the key, because none of them is an answer to the request itself: a 429 from the rate limiter, a 402 from the volume quota, and a 502 with code `MTCH-0513`, where the dispatch target answered and DECLINED before anything was created there. Every other 5xx HOLDS the key, including that code's near neighbour, the dispatch whose outcome could not be confirmed (502, code `MTCH-0514`), whose exception may already exist in the target system: the outcome was not recorded, so every resend under that key is refused 409 and nothing is sent again. Deliberately attempting such an operation again therefore requires a NEW key.
+
+    `X-Idempotency-Fenced` rides every response whose outcome the guard could not receipt, a 2xx included. `true` means the hold landed: the key still protects the operation and every resend under it is refused 409. Only `false` means a resend would EXECUTE — the answer in hand may already have applied and the key no longer protects it, so check whether the first attempt took effect before sending anything again.
+
+    Two bounds close the contract. A response larger than about 1 MB is delivered to its caller in full, but it is not stored for replay: a duplicate under the same key is answered 409 instead of replayed. And an over-sized body is refused with 413 and spends nothing. On every route but one the service-wide request body limit refuses it before the key is read. The streaming upload (`POST /v1/imports/contexts/{contextId}/sources/{sourceId}/upload`) is exempt from that limit: the key is read first and ingestion enforces its own upload limit inside the handler, so its 413 is a fourth answer that releases the key, and a smaller file may be re-sent under it.
+
+    Secret mints are another, sharper exception. `POST /v1/discovery/aggregator-connections/{id}/connect-token`, `POST /v1/discovery/webhooks/tokens`, `POST /v1/exceptions/callbacks/credentials` and `POST /v1/exceptions/callbacks/credentials/{credentialId}/rotate` each return a raw credential exactly ONCE, and storing that answer would keep the secret re-readable for the life of the key — so those four routes IGNORE the idempotency header entirely. Nothing is stored, nothing is replayed, and `X-Idempotency-Replayed` is never sent on them. A retry under the same key MINTS AGAIN and leaves a second live credential behind, so treat a mint as non-idempotent: read the first attempt's response rather than resending it. A surplus callback credential can be revoked through its own operation; a surplus aggregator webhook token has no revoke operation today and stays live.
   license:
     name: Lerian Studio General License
   title: Matcher Reconciliation API
@@ -8558,6 +9290,43 @@ paths:
       summary: Read a workspace's invoicing identification (backoffice)
       tags:
         - Onboarding
+  /v1/admin/workspaces/{slug}/plan:
+    put:
+      description: "Puts a workspace on the contractual enterprise plan: persists plan=enterprise and billing_status=active together, then evicts the billing edge-gate and volume-resolver caches so the contractual ceiling applies immediately. ONLY \"enterprise\" is accepted. This is not a generic set-plan operation: self-serve plans are bought through hosted checkout and converged from the live subscription's price, so assigning one by hand would be a payment-processor bypass that the next processor delivery silently reverts — any other plan code returns 409. It REFUSES a workspace whose subscription the payment processor could still bill (409): the operator cancels there first, where the proration and refund decision gets human eyes, and this route never moves processor money. That refusal covers every subscription that is not permanently over — one awaiting card authentication or one that is paused is not charging today and resumes tomorrow, and it would revert this plan the moment it does; only a cancelled or expired subscription is assignable over. If the processor cannot be asked, the request is refused as retryable (503) rather than allowed through. A suspended workspace is refused (409) because this operation moves no access posture — reactivate it first, and the write is compare-and-swapped on the status read, so a suspension landing mid-request is refused rather than reversed. There is no reverse: removing the enterprise plan is not offered. The target slug comes from the URL path (backoffice operation, workspace admin action). An unknown workspace returns 404. Errors use RFC 9457 problem+json. Every refusal on this route carries its own product code, because the sentence of a 503 is scrubbed before it leaves the process and the code is then the whole answer: 409 MTCH-0803 (a subscription the processor can still bill — cancel it there first), 409 MTCH-0804 (a plan code other than enterprise), 409 MTCH-0805 (the workspace's billing status does not allow the change — reload it), 503 MTCH-0802 (the processor could not be asked — retry) and 503 MTCH-0801 (no payment processor is configured on this deployment — NO retry clears it; the lever is configuration). MTCH-0805 is the same code the suspend and reactivate routes answer for a refused billing-status transition."
+      operationId: admin-assign-workspace-plan
+      parameters:
+        - description: Slug of the workspace to assign the plan to.
+          in: path
+          name: slug
+          required: true
+          schema:
+            description: Slug of the workspace to assign the plan to.
+            maxLength: 255
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AdminAssignPlanInputBody"
+        required: true
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AdminAssignPlanResult"
+          description: OK
+        default:
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/Detail"
+          description: Error
+      security:
+        - BearerAuth: []
+      summary: Assign the enterprise plan to a workspace (backoffice)
+      tags:
+        - Onboarding
   /v1/admin/workspaces/{slug}/reactivate:
     put:
       description: "Restores a suspended workspace: persists billing_status=active, re-enables interactive console login at the IdP, reactivates the tenant at the Tenant Manager (best-effort), and evicts the billing edge-gate cache. The target slug comes from the URL path (backoffice operation, workspace admin action). Idempotent. Errors use RFC 9457 problem+json."
@@ -8622,7 +9391,7 @@ paths:
         - Onboarding
   /v1/billing/webhook:
     post:
-      description: "Receives a signed billing event from the payment processor and applies it to the workspace's commercial state. This route carries NO operator JWT and no tenant identifier of any kind: a processor event has no tenant until its customer id is resolved server-side. Authentication is the Stripe-Signature signature over the RAW request body, verified inside the processor's own tolerance window. It is fail-closed on configuration — with no signing secret configured every event is rejected, and there is no value that means accept anything. Delivery is idempotent by the processor's event id: a redelivery of an event already applied returns a quiet 200 and changes nothing, an event still being applied elsewhere returns 503 so the processor retries, and an event id reused with a DIFFERENT body is a 409 rather than an acknowledgement. A processing failure returns 5xx and never records the event as applied, so the processor's retry reclaims it. Errors use the RFC 9457 application/problem+json contract and never echo the signature, the secret or the body."
+      description: "Receives a signed billing event from the payment processor and applies it to the workspace's commercial state. This route carries NO operator JWT and no tenant identifier of any kind: a processor event has no tenant until its customer id is resolved server-side. Authentication is the Stripe-Signature signature over the RAW request body, verified inside the processor's own tolerance window. It is fail-closed on configuration — with no signing secret configured every event is rejected, and there is no value that means accept anything. Delivery is idempotent by the processor's event id: a redelivery of an event already applied returns a quiet 200 and changes nothing, an event still being applied elsewhere returns 503 so the processor retries, and an event id reused with a DIFFERENT body is a 409 rather than an acknowledgement. A processing failure returns 5xx and never records the event as applied, so the processor's retry reclaims it. Errors use the RFC 9457 application/problem+json contract and never echo the signature, the secret or the body. The divergent-replay conflict carries its own product code, 409 MTCH-0811."
       operationId: receiveBillingWebhook
       parameters:
         - description: The processor's signature over the raw body, verified inside the processor's own tolerance window.
@@ -10357,6 +11126,36 @@ paths:
       summary: Update aggregator connection
       tags:
         - Discovery
+  /v1/discovery/aggregator-connections/{id}/connect-token:
+    post:
+      description: "Mints the short-lived token the aggregator vendor's OWN consent widget (Pluggy Connect / the Belvo widget) consumes in the end customer's browser, using the connection's already-sealed credential. The token is returned exactly once: it is never persisted, never logged, and there is no endpoint that reads it back. Nothing is supplied in the request — the vendor is read off the stored connection, and the mode is derived from it: a connection already bound to a vendor item/link gets a RE-CONSENT token for that same item (`reconsent: true`, and `accountRef` echoes the exact item/link the token was scoped to), while a connection awaiting consent gets a first-consent token that mints a new one (`accountRef` empty). Pass the returned `accountRef` to the vendor widget's update mode rather than a locally cached value: the token is item-scoped, and pairing it with a stale id makes the vendor run the create flow and orphan the original item. The item/link id the widget returns is bound back through PUT /v1/discovery/aggregator-connections/{id} with `accountRef` (no credential needs re-supplying). A non-aggregator connection id returns 404; a vendor with no consent path on this deployment returns 422 MTCH-0213."
+      operationId: mintAggregatorConsentToken
+      parameters:
+        - description: Opaque aggregator connection id
+          in: path
+          name: id
+          required: true
+          schema:
+            description: Opaque aggregator connection id
+            type: string
+      responses:
+        "201":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AggregatorConsentTokenResponse"
+          description: Created
+        default:
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/Detail"
+          description: Error
+      security:
+        - BearerAuth: []
+      summary: Mint aggregator consent token
+      tags:
+        - Discovery
   /v1/discovery/connections:
     get:
       description: Returns all discovered Fetcher database connections.
@@ -11710,7 +12509,7 @@ paths:
         - Exception
   /v1/exceptions/{exceptionId}:
     get:
-      description: Retrieves a single exception by its ID.
+      description: Retrieves a single exception by its ID, including the amount/currency/date/source/context of its transaction and, for fee breaks, the expected vs credited settlement figures.
       operationId: getException
       parameters:
         - description: Exception ID (UUID)
@@ -11843,7 +12642,7 @@ paths:
             type: string
         - description: Idempotency key for deduplication
           in: header
-          name: X-Idempotency-Key
+          name: X-Idempotency
           required: true
           schema:
             description: Idempotency key for deduplication
@@ -13041,7 +13840,10 @@ paths:
         - Governance
   /v1/governance/audit-logs/verify:
     get:
-      description: "Re-verifies the calling tenant's tamper-evident audit hash chain and returns a structured verdict (intact, verified count, and the first broken tenant_seq when a break is found). The check is strictly read-only: it recomputes nothing into storage and never mutates an audit record. Use the optional maxRecords query parameter to bound how many records are inspected."
+      description: |-
+        Re-verifies the calling tenant's tamper-evident audit hash chain and returns a structured verdict (intact, verified count, and the first broken tenant_seq when a break is found). The check is strictly read-only: it recomputes nothing into storage and never mutates an audit record. Use the optional maxRecords query parameter to bound how many records are inspected.
+
+        Use the optional fromSeq query parameter to bind the verification floor: the first record inspected is the one with tenant_seq == fromSeq. A floor above 1 TRUSTS that record's stored prev_hash instead of validating it against the genesis hash, so tampering BELOW the floor is out of scope for that run and is not reported. Two uses follow from that: (1) resuming — when a verdict comes back truncated, re-run with fromSeq = fromSeq + verifiedCount to verify the remainder; (2) archived-partition tenants — once the archival worker has dropped the bottom partitions, verify from the current floor, because a run from seq 1 no longer has the records it would need. The verdict always echoes the effective fromSeq, so an empty range (verifiedCount 0 with a high fromSeq) is never mistaken for an intact chain verified from genesis.
       operationId: verifyAuditLogChain
       parameters:
         - description: Maximum number of records to inspect; clamped to the server bound. Omit to use the default bound.
@@ -13054,6 +13856,15 @@ paths:
             maximum: 10000
             minimum: 1
             type: integer
+        - description: "Verification floor: the first record inspected is the one with this tenant_seq. Omit to start at the chain start (seq 1)."
+          explode: false
+          in: query
+          name: fromSeq
+          schema:
+            description: "Verification floor: the first record inspected is the one with this tenant_seq. Omit to start at the chain start (seq 1)."
+            format: int64
+            minimum: 1
+            type: integer
       responses:
         "200":
           content:
@@ -13575,7 +14386,7 @@ paths:
         - Ingestion
   /v1/imports/contexts/{contextId}/sources/{sourceId}/extract-document:
     post:
-      description: "Stores the uploaded source document tenant-scoped, runs deterministic + AI extraction, and enqueues the resulting transaction CANDIDATES in a human-review queue. AI output is NEVER authoritative: no transaction is reconciled until a human approves the review. The lane is gated by a global kill-switch AND a per-tenant opt-in (fail-closed: a non-opted-in tenant gets 403). The tenant is resolved from the JWT and the context/source from the path — never from the body."
+      description: "Stores the uploaded source document tenant-scoped, runs deterministic + AI extraction, and enqueues the resulting transaction CANDIDATES in a human-review queue. AI output is NEVER authoritative: no transaction is reconciled until a human approves the review. The lane is gated by a global kill-switch AND one process-wide operator consent switch — NOT a per-customer opt-in: granting consent grants AI egress for EVERY customer at once, and while it is off every caller gets 403 (fail-closed). The tenant is resolved from the JWT and the context/source from the path — never from the body."
       operationId: extractDocument
       parameters:
         - description: Context ID
@@ -14475,7 +15286,7 @@ paths:
       tags:
         - Matching
     post:
-      description: "Builds AGGREGATE, privacy-safe history features for the context, asks the AI advisor for config-only candidate rules, and enqueues each surviving candidate in a human-review queue. AI output is NEVER authoritative: producing a suggestion CREATES NO rule. A rule is created only when a human APPROVES a suggestion. The lane is gated by a global advisor kill-switch AND a per-tenant opt-in (fail-closed: a non-opted-in tenant gets 403). Tenant from the JWT, context from the path. The egress payload is aggregates only — no raw transaction, money, or PII."
+      description: "Builds AGGREGATE, privacy-safe history features for the context, asks the AI advisor for config-only candidate rules, and enqueues each surviving candidate in a human-review queue. AI output is NEVER authoritative: producing a suggestion CREATES NO rule. A rule is created only when a human APPROVES a suggestion. The lane is gated by a global advisor kill-switch AND one process-wide operator consent switch — NOT a per-customer opt-in: granting consent grants AI egress for EVERY customer at once. Until consent is granted the endpoint fails closed with 403. Tenant from the JWT, context from the path. The egress payload is aggregates only — no raw transaction, money, or PII."
       operationId: suggestMatchRules
       parameters:
         - description: Context ID
@@ -16262,7 +17073,7 @@ paths:
         - Onboarding
   /v1/signup/verify:
     post:
-      description: "Completes email verification and starts self-service onboarding. This is a PUBLIC, anonymous, pre-tenant route: it exchanges the emailed verification token for a workspace whose setup is now under way, and returns the workspace handle. It does NOT wait for setup to finish — creating the environment includes a schema migration whose duration the server does not control, so a background worker drives it to completion and the response comes back immediately. It is idempotent: a repeat call records nothing new, and a token that no longer resolves (already used or expired) returns the same 200 response. The route is rate-limited per client IP."
+      description: "Completes email verification and starts self-service onboarding. This is a PUBLIC, anonymous, pre-tenant route: it exchanges the emailed verification token for a workspace whose setup is now under way, and returns the workspace handle. It does NOT wait for setup to finish — creating the environment includes a schema migration whose duration the server does not control, so a background worker drives it to completion and the response comes back immediately. It is idempotent: a repeat call records nothing new, and a token that no longer resolves (already used or expired) returns the same 200 response. The route is rate-limited per client IP. Its two conflicts carry their own product codes, and they are not the same answer: 409 MTCH-0812 (the workspace already exists and MAY be the caller's own — sign in, or sign up under another company name) and 409 MTCH-0813 (the name belongs to another account — only a different company name clears it)."
       operationId: signup-verify
       requestBody:
         content:
@@ -16311,7 +17122,7 @@ paths:
         - Onboarding
   /v1/workspace/billing-portal:
     post:
-      description: Opens the payment processor's hosted customer portal for the AUTHENTICATED tenant's own workspace and returns the URL to redirect the browser to. Card update, invoice history and cancellation live there, not here; cancellation takes effect at the end of the period already paid for. Errors use the RFC 9457 application/problem+json contract.
+      description: "Opens the payment processor's hosted customer portal for the AUTHENTICATED tenant's own workspace and returns the URL to redirect the browser to. Card update, invoice history and cancellation live there, not here; cancellation takes effect at the end of the period already paid for. Errors use the RFC 9457 application/problem+json contract. Its two refusals carry their own product codes: 409 MTCH-0806 (plan set by contract, so there is no self-serve subscription to manage) and 409 MTCH-0810 (no billing account yet — subscribe first)."
       operationId: workspace-billing-portal
       responses:
         "200":
@@ -16333,7 +17144,7 @@ paths:
         - Onboarding
   /v1/workspace/checkout:
     post:
-      description: "Opens a hosted checkout session that subscribes the AUTHENTICATED tenant's own workspace to a self-serve plan, and returns the URL to redirect the browser to. The workspace is resolved from the JWT tenant-slug claim: this endpoint never accepts a tenant identifier in the body, path, query or headers, and the session is bound to the caller's tenant. The billing interval selects the payment methods — monthly is card, annual is boleto and Pix — so a session is never created with an instrument the amount cannot clear. A plan that is not self-serve, an unknown plan or interval, and a workspace that already has a subscription are all refused before the processor is called. The return URLs carry no activation-bearing parameter: the plan is activated only by the verified webhook, and the return page reads the resulting state from GET /v1/workspace/billing. Errors use the RFC 9457 application/problem+json contract."
+      description: "Opens a hosted checkout session that subscribes the AUTHENTICATED tenant's own workspace to a self-serve plan, and returns the URL to redirect the browser to. The workspace is resolved from the JWT tenant-slug claim: this endpoint never accepts a tenant identifier in the body, path, query or headers, and the session is bound to the caller's tenant. The billing interval selects the payment methods — monthly is card, annual is boleto and Pix — so a session is never created with an instrument the amount cannot clear. A plan that is not self-serve, an unknown plan or interval, and a workspace that already has a subscription are all refused before the processor is called. The return URLs carry no activation-bearing parameter: the plan is activated only by the verified webhook, and the return page reads the resulting state from GET /v1/workspace/billing. Errors use the RFC 9457 application/problem+json contract. Each refusal carries its own product code so a client never has to read the sentence: 409 MTCH-0806 (plan set by contract), 409 MTCH-0807 (already subscribed), 409 MTCH-0808 (a checkout is open for a different plan or interval), 409 MTCH-0809 (a checkout is being opened right now — retry), 422 MTCH-0814 (the plan is not sold self-serve) and 400 MTCH-0001 (unknown plan or interval)."
       operationId: workspace-checkout
       requestBody:
         content:
@@ -16383,7 +17194,7 @@ paths:
         - Onboarding
   /v1/workspace/credit-purchase:
     post:
-      description: "Opens a ONE-OFF hosted payment session that buys prepaid overage credit for the AUTHENTICATED tenant's own workspace, and returns the URL to redirect the browser to. It is never a subscription. The workspace is resolved from the JWT tenant-slug claim: this endpoint never accepts a tenant identifier in the body, path, query or headers. Any workspace may buy — trialing, lapsed, monthly or annual — because the customer who has run out of allowance is the one being told to buy. Payment is by CARD on every plan, including annual: the instrument that funds overage credit is deliberately not the subscription's instrument, and the card is saved for future CREDIT purchases only. An amount outside the price list's minimum and maximum is refused before the processor is called. The credit balance moves ONLY when the processor confirms the payment through the verified webhook — never on the return page and never in this response. Errors use the RFC 9457 application/problem+json contract."
+      description: "Opens a ONE-OFF hosted payment session that buys prepaid overage credit for the AUTHENTICATED tenant's own workspace, and returns the URL to redirect the browser to. It is never a subscription. The workspace is resolved from the JWT tenant-slug claim: this endpoint never accepts a tenant identifier in the body, path, query or headers. Any workspace on a self-serve plan may buy — trialing, lapsed, monthly or annual — because the customer who has run out of allowance is the one being told to buy. A workspace on a CONTRACTUAL plan is refused with 409: its volume is not metered, so prepaid overage credit buys it nothing. Payment is by CARD on every plan, including annual: the instrument that funds overage credit is deliberately not the subscription's instrument, and the card is saved for future CREDIT purchases only. An amount outside the price list's minimum and maximum is refused before the processor is called. The credit balance moves ONLY when the processor confirms the payment through the verified webhook — never on the return page and never in this response. Errors use the RFC 9457 application/problem+json contract. Its two refusals carry their own product codes: 422 MTCH-0815 (the amount is outside the purchasable range) and 409 MTCH-0806 (plan set by contract, so volume is not metered and credit buys nothing)."
       operationId: workspace-credit-purchase
       requestBody:
         content: