@lerianstudio/matcher-mcp 5.0.0-beta.3 → 5.0.0-beta.31

package/dist/spec/openapi.yaml

@@ -230,6 +230,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 +348,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:
@@ -341,6 +373,11 @@ components:
           examples:
             - a1b2c3d4-5678-90ab-cdef-1234567890ab
           type: string
+        testable:
+          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
         vendor:
           description: Aggregator vendor the connection is bound to
           enum:
@@ -355,6 +392,8 @@ components:
         - configName
         - baseUrl
         - accountRef
+        - testable
+        - awaitingConsent
       type: object
     AggregatorConnectionListResponse:
       additionalProperties: false
@@ -394,10 +433,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
@@ -432,7 +470,6 @@ components:
         - vendor
         - configName
         - baseUrl
-        - accountRef
         - clientId
         - secret
       type: object
@@ -440,10 +477,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:
@@ -468,6 +510,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
@@ -632,6 +720,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:
@@ -650,6 +744,7 @@ components:
           type: integer
       required:
         - intact
+        - fromSeq
         - verifiedCount
         - truncated
       type: object
@@ -878,6 +973,11 @@ components:
     BulkFailure:
       additionalProperties: false
       properties:
+        code:
+          description: Stable product error code for this row, when the failure has one
+          examples:
+            - MTCH-0514
+          type: string
         error:
           description: Human-readable reason the exception could not be processed
           examples:
@@ -1795,7 +1895,7 @@ components:
       properties:
         config:
           additionalProperties: {}
-          description: Source-specific configuration object (connection and parsing settings). Optional; defaults to an empty object when omitted.
+          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."
           type: object
         mapping:
           additionalProperties: {}
@@ -1965,10 +2065,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
@@ -2225,7 +2325,7 @@ components:
       properties:
         config:
           additionalProperties: {}
-          description: Source-specific configuration object (connection and parsing settings). Optional; defaults to an empty object when omitted.
+          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."
           type: object
         name:
           description: Human-readable name of the source.
@@ -2595,11 +2695,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
@@ -2857,10 +2958,11 @@ components:
             - 550e8400-e29b-41d4-a716-446655440003
           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
@@ -3356,7 +3458,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.
@@ -3966,6 +4068,11 @@ components:
             - "2025-01-15T00:00:00Z"
           format: date-time
           type: string
+        dedupeKey:
+          description: "Read-only: the duplicate-key value this row was imported under, derived from the source's duplicate key declaration at import time. A source can change that declaration later, so this is the only place that says which identity THIS row carries. Prefixed v1 when the key spells out the fields it was derived from, v1h when those fields were hashed because the spelled-out key was too long to index."
+          examples:
+            - v1|external_id=9:TXN-12345
+          type: string
         description:
           description: Free-text description carried from the source
           examples:
@@ -4014,6 +4121,7 @@ components:
         - sourceId
         - contextId
         - externalId
+        - dedupeKey
         - amount
         - currency
         - date
@@ -4048,17 +4156,17 @@ components:
           format: date-time
           type: string
         diagnosis:
-          description: Safe one-line diagnosis for a FAILED job (dialect diagnosis, rate-policy message, or generic safe message); empty for partial completed-with-errors jobs — internal error detail is never surfaced here
+          description: Safe one-line diagnosis of anything the parser found worth reporting about the file (dialect mismatch, degraded settlement re-join, zero-detail file), the rate-policy message for policy-FAILED jobs, or a generic safe message for other FAILED jobs. Present on COMPLETED jobs too, including ones with zero failed rows; empty when there is nothing to report — internal error detail is never surfaced here
           examples:
             - file appears semicolon-delimited but the source declares comma; declare delimiter semicolon in the source dialect
           type: string
         droppedDuplicateReason:
-          description: "Display-only explanation of why droppedDuplicateRows rows were dropped: names the (source, external_id) collapsing key and the field mapping to check so the count does not read as silent data loss. Empty unless droppedDuplicateRows > 0"
+          description: "Display-only explanation of why droppedDuplicateRows rows were kept out of the import: names the source's duplicate key as the identity that collided, says the repeats were attached as exceptions to the rows they repeated when the job flagged any (repeats of one row share one exception, so the queue holds one item per repeated row), and names the repeats that raised nothing when fewer were flagged than dropped, so the count does not read as silent data loss and the customer is sent to the configuration that decides it. Empty unless droppedDuplicateRows > 0"
           examples:
-            - Rows repeated a (source, external_id) key already present in this source and were dropped as duplicates. If unexpected, verify the field mapped to external_id is unique per row (a coarse or truncated mapping collapses distinct rows onto one key).
+            - "Rows repeated the duplicate key this source deduplicates on and were kept out of the import. This source flags duplicates, so each repeat whose original was found was attached to that original as a duplicate exception in the exceptions queue. Repeats of the same original share one exception, so the queue holds one item per repeated row, not one per repeat. The rest found no imported row to attach to (another import of this source may still have been in progress), so no exception was raised for them and they are not in the queue: re-upload those rows once every import of this source has finished. If unexpected, review the source's duplicate key and the fields it names (a coarse or truncated mapping collapses distinct rows onto one key)."
           type: string
         droppedDuplicateRows:
-          description: Number of rows dropped as duplicates under the keep-first policy (same external_id within the upload or already persisted)
+          description: Number of rows kept out of the import as duplicates (rows repeating the source's duplicate key within the upload or already persisted); see flaggedDuplicateRows for how many were also raised as exceptions
           examples:
             - 60
           format: int64
@@ -4085,7 +4193,7 @@ components:
             - transactions_2024.csv
           type: string
         flaggedDuplicateRows:
-          description: Number of dropped duplicates flagged as DUPLICATE_TRANSACTION exceptions under the FLAG_AS_EXCEPTION duplicate policy (subset of droppedDuplicateRows)
+          description: "Number of dropped duplicate ROWS raised as DUPLICATE_TRANSACTION exceptions on the transaction they repeated, under the FLAG_AS_EXCEPTION duplicate policy — the default (subset of droppedDuplicateRows). Not a queue-item count: repeats of the same transaction share one exception, which carries how many times it was repeated"
           examples:
             - 15
           format: int64
@@ -6030,7 +6138,7 @@ components:
           type: string
         config:
           additionalProperties: {}
-          description: Source-specific configuration object (connection and parsing settings).
+          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.
           type: object
         contextId:
           description: Identifier of the context this source belongs to.
@@ -6651,7 +6759,9 @@ components:
       required:
         - id
         - status
-      type: object
+      type:
+        - object
+        - "null"
     SetupProgressMatchRulesResponse:
       additionalProperties: false
       properties:
@@ -6713,7 +6823,9 @@ components:
         - method
         - path
         - requiredFields
-      type: object
+      type:
+        - object
+        - "null"
     SetupProgressReadinessResponse:
       additionalProperties: false
       properties:
@@ -7356,7 +7468,7 @@ components:
           type: string
         config:
           additionalProperties: {}
-          description: Source-specific configuration object (connection and parsing settings).
+          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.
           type: object
         contextId:
           description: Identifier of the context this source belongs to.
@@ -7574,16 +7686,7 @@ components:
             - pluggy-main
           minLength: 1
           type: string
-        vendor:
-          description: "Aggregator vendor: pluggy or belvo"
-          enum:
-            - pluggy
-            - belvo
-          examples:
-            - pluggy
-          type: string
       required:
-        - vendor
         - configName
       type: object
     TestAggregatorConnectionResponse:
@@ -7668,6 +7771,11 @@ components:
             - "2025-01-15T00:00:00Z"
           format: date-time
           type: string
+        dedupeKey:
+          description: "Read-only: the duplicate-key value this row was imported under, derived from the source's duplicate key declaration at import time. A source can change that declaration later, so this is the only place that says which identity THIS row carries. Prefixed v1 when the key spells out the fields it was derived from, v1h when those fields were hashed because the spelled-out key was too long to index."
+          examples:
+            - v1|external_id=9:TXN-12345
+          type: string
         description:
           description: Free-text description carried from the source
           examples:
@@ -7716,6 +7824,7 @@ components:
         - sourceId
         - contextId
         - externalId
+        - dedupeKey
         - amount
         - currency
         - date
@@ -7854,34 +7963,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
@@ -8102,7 +8204,7 @@ components:
       properties:
         config:
           additionalProperties: {}
-          description: Source-specific configuration object (connection and parsing settings).
+          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)."
           type: object
         name:
           description: New human-readable name of the source.
@@ -8377,7 +8479,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:
@@ -8385,7 +8487,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:
@@ -8402,7 +8504,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.
@@ -8411,6 +8513,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
@@ -8423,6 +8528,7 @@ components:
         - provisioningState
         - provisioningStep
         - provisioningFailed
+        - volumeUnmetered
         - monthlyLineAllowance
         - overageRateCentsPerThousandLines
         - overageCreditBalanceCents
@@ -8459,7 +8565,16 @@ 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 `Idempotency-Key` header (`X-Idempotency-Key` is also honoured, and wins if both are sent). 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 `Idempotency-Replayed: true`; a retry that arrives while the first attempt is still in flight is refused with 409.
+
+    A request that FAILED normally releases its key, so a caller can correct the cause and retry under the same key. The exception is a dispatch whose outcome could not be confirmed (502, code `MTCH-0514`): the exception may already have been created in the target system, so that answer HOLDS its key — every retry under it replays the same 502 and no second dispatch is sent. Deliberately attempting that dispatch again therefore requires a NEW idempotency key. A dispatch the target answered and rejected (502, code `MTCH-0513`) created nothing there and releases its key as usual.
+
+    Secret mints are the other, 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 `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
@@ -8544,6 +8659,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."
+      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."
@@ -10079,7 +10231,7 @@ paths:
       tags:
         - Configuration
     post:
-      description: "Creates a field map for a source within a context. Mapping keys form a closed vocabulary: required keys are external_id, amount, currency, date; optional keys are description, fee_amount, fee_currency. Values name source columns and must be non-empty strings."
+      description: "Creates a field map for a source within a context. A source holds at most one field map: creating a second is rejected with a 409 carrying the configuration has-field-map code, and the caller should update the existing map instead. Mapping keys form a closed vocabulary: required keys are external_id, amount, currency, date; optional keys are description, fee_amount, fee_currency. Values name source columns and must be non-empty strings."
       operationId: createFieldMap
       parameters:
         - description: Context ID
@@ -10159,7 +10311,7 @@ paths:
         - Configuration
   /v1/discovery/aggregator-connections:
     get:
-      description: "Returns a cursor-paginated list of the tenant's Open-Finance data-aggregator (Pluggy/Belvo) connections, ordered by config name. The list is secret-free by construction: no credential material (clientId/secret/ciphertext) is ever returned."
+      description: "Returns a cursor-paginated list of the tenant's Open-Finance data-aggregator (Pluggy/Belvo) connections, ordered by config name. The list is secret-free by construction: no credential material (clientId/secret/ciphertext) is ever returned. Each row carries `testable`, derived from the stored vendor, so a client knows whether the connectivity-test action can run at all without keeping its own vendor list."
       operationId: listAggregatorConnections
       parameters:
         - description: Maximum number of records to return
@@ -10227,7 +10379,7 @@ paths:
         - Discovery
   /v1/discovery/aggregator-connections/test:
     post:
-      description: "Runs a live connectivity check for an existing Open-Finance data-aggregator (Pluggy/Belvo) connection using its already-sealed credential, addressed by (vendor, configName). No credential is supplied or returned: the result is the secret-free boolean health of the connection."
+      description: "Runs a live connectivity check for an existing Open-Finance data-aggregator (Pluggy/Belvo) connection using its already-sealed credential, addressed by configName. The vendor is read from the stored connection, not from the request. No credential is supplied or returned: the result is the secret-free boolean health of the connection. Two refusals are deliberately distinct: a config name matching no connection is 404 MTCH-0005, while a connection whose stored vendor Matcher has no test path for yet (Belvo today) is 422 MTCH-0210 and no test runs. The list endpoint's per-connection `testable` flag tells a client which is which before it offers the action."
       operationId: testAggregatorConnection
       requestBody:
         content:
@@ -10343,6 +10495,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.
@@ -13027,7 +13209,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.
@@ -13040,6 +13225,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:
@@ -16369,7 +16563,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."
       operationId: workspace-credit-purchase
       requestBody:
         content: