@celigo/api-specs 0.2.83 → 0.2.85

package/dist/tool.yml

@@ -402,8 +402,14 @@ paths:
         | `/name` | Tool display name |
         | `/description` | Tool description |
         | `/aiDescription` | AI-generated description object |
+        | `/input/debugUntil` | Debug-capture expiry for the Tool Input stage (ISO-8601, at most 3600 seconds from now) |
+        | `/output/debugUntil` | Debug-capture expiry for the Tool Output stage (ISO-8601, at most 3600 seconds from now) |
 
-        All other paths are rejected with 422 (`not a whitelisted property`).
+        All other paths are rejected with 422 (`not a whitelisted property`). A
+        `debugUntil` more than 3600 seconds ahead is rejected with 422
+        `update_not_allowed` and nothing is saved; `remove` on an absent
+        `debugUntil` succeeds (204). Changing a `debugUntil` needs the Tool
+        update permission on the Tool's integration, like every other path.
 
         PATCH is the intended way to update these fields without accidentally
         resetting other tool configuration via `PUT`.
@@ -2624,9 +2630,24 @@ paths:
       description: |-
         Lists the debug request records captured for a specific step of a tool.
         These are the raw request/response payloads the step processed, retained
-        for troubleshooting while debug capture is active for the step. Use the
-        `key` of an entry with `GET /v1/tools/{_id}/{_stepId}/requests/{key}` to
-        fetch the full detail of a single captured request.
+        for troubleshooting while debug capture is active for the step — a future
+        `debugUntil` on the step's export or import document, or `input.debugUntil`
+        / `output.debugUntil` on the tool for the Tool Input and Tool Output
+        stages. Capture runs in every execution context (a standalone invoke at
+        any `x-log-mode`, an AI agent or MCP caller, a flow or API that calls the
+        tool, a parent tool); test runs write nothing here. Use the `key` of an
+        entry with `GET /v1/tools/{_id}/{_stepId}/requests/{key}` to fetch the
+        full detail of a single captured request.
+
+        HTTP and NetSuite steps record one entry per request they send. The
+        `tool_input` stage records one entry per incoming record (`200` when the
+        record passes the input schema, `422` with the validation errors when it
+        does not); the `tool_output` stage records one entry per output
+        validation. Routers, filters and scripts never record.
+
+        An account owner or administrator lists every entry. A shared user sees
+        only entries from runs invoked under integrations they can access
+        (standalone invokes are recorded under the tool's own integration).
 
         When more records match than fit in one page, `nextPageURL` returns the
         relative URL for the next page.
@@ -2656,15 +2677,21 @@ paths:
           required: true
           description: |-
             The step whose captured logs to list: the ObjectId of an export or
-            import step defined directly in this tool's routers. Steps nested
-            inside a child tool are addressed on that child tool's id. Any other
-            value — including reserved path segments such as `invocations`,
-            `invoke`, and `test` — returns `400` `invalid_ref`.
+            import step defined directly in this tool's routers, or one of the
+            two virtual stage ids `tool_input` (the record entering the tool,
+            validated against the input schema) and `tool_output` (the
+            post-mapped record, validated against the output schema). Steps
+            nested inside a child tool are addressed on that child tool's id;
+            an ObjectId that is not a direct step of this tool returns `404`
+            `invalid_ref`. Any other value — including reserved path segments
+            such as `invocations`, `invoke`, and `test` — returns `400`
+            `invalid_ref`.
           schema:
             type: string
-            format: objectId
             examples:
               - 67ee026136f4d1eeb529ad63
+              - tool_input
+              - tool_output
         - name: time_gt
           in: query
           required: false
@@ -2771,7 +2798,11 @@ paths:
                           description: Response status code of the captured request.
                         stage:
                           type: string
-                          description: Processing stage the record was captured in.
+                          description: |-
+                            Processing stage the record was captured in, such as
+                            `lookup` for a lookup step's request. Present on
+                            records written by HTTP and NetSuite steps; absent on
+                            `tool_input` and `tool_output` records.
                       additionalProperties: true
                   nextPageURL:
                     type: string
@@ -2789,16 +2820,60 @@ paths:
                   summary: Captured debug requests for a tool step
                   value:
                     requests:
-                      - key: 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST
+                      - key: 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-GET-lookup-60a2c4e6f321d800129a1a3c
                         time: 1776917346304
+                        method: GET
+                        statusCode: '200'
+                        stage: lookup
+                tool_input:
+                  summary: Captured Tool Input records — one passed, one failed the input schema
+                  value:
+                    requests:
+                      - key: 5466610903705-847304f37d2041a79b9e657ea9a45d68-200-POST--60a2c4e6f321d800129a1a3c
+                        time: 1791507496295
                         method: POST
                         statusCode: '200'
+                      - key: 5466610902616-0d4aa1266fcb4ae4be5a7f316ff5e01c-422-POST--60a2c4e6f321d800129a1a3c
+                        time: 1791507497384
+                        method: POST
+                        statusCode: '422'
+        '400':
+          description: |-
+            `_stepId` is neither an ObjectId nor `tool_input` / `tool_output`.
+            Error code: `invalid_ref`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                unknown_virtual_id:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _expOrImpId.
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '403':
           $ref: '#/components/responses/403-forbidden'
         '404':
-          $ref: '#/components/responses/404-not-found'
+          description: |-
+            The tool does not exist, or `_stepId` is an ObjectId that is not a
+            step defined directly in this tool. Error code: `invalid_ref`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                tool_not_found:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Tool not found.
+                step_not_in_tool:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Export/Import not found.
         '422':
           description: 'Invalid time filter parameters. Error code: `invalid_or_missing_field`.'
           content:
@@ -2822,12 +2897,16 @@ paths:
       description: |-
         Deletes captured debug request records for a specific step of a tool, by
         their `key` values from `GET /v1/tools/{_id}/{_stepId}/requests`. Between
-        1 and 1000 keys can be deleted per call.
+        1 and 1000 keys can be deleted per call; the deletion is synchronous and
+        scoped to this step only.
 
         The response lists the keys that were deleted and, separately, any keys
-        that failed to delete along with the failure reason.
+        that failed to delete along with the failure reason. A key that no longer
+        exists is reported under `deleted`, not `errors`.
 
-        Requires the `manage:tool:logs:deletion` permission.
+        Requires the `manage:tool:logs:deletion` permission. A shared user's
+        delete removes only records from runs invoked under integrations they can
+        access.
       operationId: deleteToolStepRequests
       tags:
         - Tools
@@ -2847,12 +2926,16 @@ paths:
           required: true
           description: |-
             The step whose captured logs to delete: the ObjectId of an export or
-            import step defined directly in this tool's routers.
+            import step defined directly in this tool's routers, or the virtual
+            stage id `tool_input` or `tool_output`. Any other value returns
+            `400` `invalid_ref`; an ObjectId that is not a direct step of this
+            tool returns `404` `invalid_ref`.
           schema:
             type: string
-            format: objectId
             examples:
               - 67ee026136f4d1eeb529ad63
+              - tool_input
+              - tool_output
       requestBody:
         required: true
         content:
@@ -2919,13 +3002,43 @@ paths:
                       - 5481201048878-b21bf2bef9ff588b958882d2f4827f47-422-POST
                     errors: []
         '400':
-          $ref: '#/components/responses/400-bad-request'
+          description: |-
+            The body carries no `keys` array (error code `invalid_url`), or
+            `_stepId` is neither an ObjectId nor `tool_input` / `tool_output`
+            (error code `invalid_ref`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                missing_keys:
+                  value:
+                    errors:
+                      - code: invalid_url
+                        message: keys is not valid.
+                unknown_virtual_id:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _expOrImpId.
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '403':
           $ref: '#/components/responses/403-forbidden'
         '404':
-          $ref: '#/components/responses/404-not-found'
+          description: |-
+            The tool does not exist, or `_stepId` is an ObjectId that is not a
+            step defined directly in this tool. Error code: `invalid_ref`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                step_not_in_tool:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Export/Import not found.
   /v1/tools/{_id}/{_stepId}/requests/{key}:
     get:
       x-internal: false
@@ -2935,8 +3048,15 @@ paths:
         step, identified by its `key`. Obtain the `key` from
         `GET /v1/tools/{_id}/{_stepId}/requests`.
 
-        The record carries the adaptor HTTP request/response the step issued,
-        with credentials masked, plus the `key`, record `id`, and capture `time`.
+        For an HTTP or NetSuite step the record carries the adaptor HTTP
+        request/response the step issued, with credentials masked and the
+        bodies as strings. For the `tool_input` and `tool_output` stages (and a
+        ToolImport step) the record is synthetic: `request.body` is the JSON
+        record entering the stage, `response.body` is the validated JSON record
+        (`statusCode` 200) or the validation errors (`statusCode` 422), the
+        request carries no `url`, and `context` names the run that produced it.
+        Synthetic bodies are stored unmasked. Every record carries the `key`,
+        record `id`, and capture `time`.
 
         Requires the `manage:tool:logs` permission.
       operationId: getToolStepRequest
@@ -2958,15 +3078,18 @@ paths:
           required: true
           description: |-
             The step the captured request belongs to: the ObjectId of an export
-            or import step defined directly in this tool's routers. Steps nested
-            inside a child tool are addressed on that child tool's id. Any other
-            value — including reserved path segments such as `invocations`,
-            `invoke`, and `test` — returns `400` `invalid_ref`.
+            or import step defined directly in this tool's routers, or the
+            virtual stage id `tool_input` or `tool_output`. Steps nested inside
+            a child tool are addressed on that child tool's id; an ObjectId that
+            is not a direct step of this tool returns `404` `invalid_ref`. Any
+            other value — including reserved path segments such as
+            `invocations`, `invoke`, and `test` — returns `400` `invalid_ref`.
           schema:
             type: string
-            format: objectId
             examples:
               - 67ee026136f4d1eeb529ad63
+              - tool_input
+              - tool_output
         - name: key
           in: path
           required: true
@@ -2998,51 +3121,84 @@ paths:
                     description: Epoch milliseconds when this pair was stored.
                   request:
                     type: object
-                    description: The HTTP request the step's export or import sent.
+                    description: |-
+                      The HTTP request the step's export or import sent, or — for
+                      the `tool_input`, `tool_output` and ToolImport stages — the
+                      record entering the stage, wrapped as a `POST` with no `url`.
                     properties:
                       method:
                         type: string
-                        description: HTTP method (`GET`, `POST`, …).
+                        description: HTTP method (`GET`, `POST`, …); always `POST` on synthetic records.
                         examples:
                           - POST
                       url:
                         type: string
-                        description: Fully-resolved URL the request was sent to.
+                        description: Fully-resolved URL the request was sent to. Absent on synthetic records.
                         examples:
                           - https://httpbin.org/post
                       headers:
                         type: object
-                        description: Headers sent with the request; credential values are masked.
+                        description: Headers sent with the request; credential values are masked. Empty on synthetic records.
                         additionalProperties: true
                       body:
-                        type: string
-                        description: Request body as sent, verbatim.
+                        type:
+                          - string
+                          - object
+                        description: |-
+                          Request body as sent, verbatim, for an HTTP step (absent on a
+                          body-less method such as `GET`); the JSON record entering the
+                          stage on a synthetic record.
                         examples:
                           - '{"orderId":"SO-1042"}'
                   response:
                     type: object
-                    description: The HTTP response the step received.
+                    description: |-
+                      The HTTP response the step received, or — on synthetic
+                      records — the outcome of the stage: the validated record
+                      with `statusCode` 200, or the validation errors with 422.
                     properties:
                       statusCode:
                         type: integer
-                        description: HTTP status code the target system returned.
+                        description: HTTP status code the target system returned, or 200 / 422 for a synthetic record.
                         examples:
                           - 200
                       headers:
                         type: object
-                        description: Response headers as received.
+                        description: Response headers as received. Empty on synthetic records.
                         additionalProperties: true
                       body:
-                        type: string
-                        description: Response body as received; parse per the `content-type` header.
+                        type:
+                          - string
+                          - object
+                        description: |-
+                          For an HTTP or NetSuite step: the response body as received, a
+                          string the caller parses per the `content-type` header. On a
+                          synthetic record: the validated JSON record as an object, or
+                          `{errors: [{code, message, …}]}` when validation failed.
                         examples:
                           - '{"ok":true}'
+                      receivedAt:
+                        type: integer
+                        format: int64
+                        description: Epoch milliseconds when the pair was captured.
+                  context:
+                    type: object
+                    description: |-
+                      The run that produced a synthetic record. Absent on records
+                      written by HTTP and NetSuite steps.
+                    properties:
+                      _rootContainerId:
+                        type: string
+                        description: Owning flow, API, or tool id of the run that produced this capture.
+                      _jobId:
+                        type: string
+                        description: Job id of the run that produced this capture.
                 additionalProperties: true
               examples:
                 adaptor_http:
                   summary: Captured HTTP request of a lookup step
                   value:
-                    key: 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST
+                    key: 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST-lookup-60a2c4e6f321d800129a1a3c
                     id: a10af1ade8fe477a847771c1e3716e36
                     time: 1776917346304
                     request:
@@ -3056,12 +3212,67 @@ paths:
                       headers:
                         content-type: application/json
                       body: '{"ok":true}'
+                      receivedAt: 1776917346302
+                tool_input_failed:
+                  summary: Synthetic Tool Input record — the record failed the input schema
+                  value:
+                    key: 5466610902616-0d4aa1266fcb4ae4be5a7f316ff5e01c-422-POST--60a2c4e6f321d800129a1a3c
+                    id: 0d4aa1266fcb4ae4be5a7f316ff5e01c
+                    time: 1791507497384
+                    request:
+                      method: POST
+                      headers: {}
+                      body: {}
+                    response:
+                      statusCode: 422
+                      headers: {}
+                      receivedAt: 1791507497384
+                      body:
+                        errors:
+                          - code: tool_input_schema_validation_failed
+                            message: 'Tool input validation failed: must have required property ''q'''
+                            source: tool_input
+                            stage: tool_input_schema_validation
+                    context:
+                      _rootContainerId: 69d462d5b9c28ea0b7f82522
+                      _jobId: 6ac83c299205d177fa25df54
+        '400':
+          description: |-
+            `_stepId` is neither an ObjectId nor `tool_input` / `tool_output`.
+            Error code: `invalid_ref`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                unknown_virtual_id:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _expOrImpId.
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '403':
           $ref: '#/components/responses/403-forbidden'
         '404':
-          $ref: '#/components/responses/404-not-found'
+          description: |-
+            The tool or the step does not exist (`invalid_ref`), or no record
+            carries this `key` (`file_not_found`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                unknown_key:
+                  value:
+                    errors:
+                      - code: file_not_found
+                        message: We are unable to find the file for the given fileName.
+                step_not_in_tool:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Export/Import not found.
 components:
   securitySchemes:
     bearerAuth:
@@ -3373,7 +3584,8 @@ components:
             Explicit JSON `null` is itself a valid fallback: the destination field is written as
             JSON null when the extract yields nothing (the Mapper UI's "Use null as default value"
             action). Omitting the key entirely means no fallback — the field is left out of the
-            output when the extract is empty (the UI's "Do nothing" action).
+            output when the extract is empty (the UI's "Do nothing" action). Failing the record
+            instead is `conditional.when: fail_record_when_empty`, which excludes a default.
           x-celigo-ai-guidance:
             - |-
               `"default": null` and `"default": ""` are distinct saved values, not
@@ -3382,6 +3594,12 @@ components:
               Preserve them verbatim when editing or migrating a mapping — dropping
               the key changes runtime behavior from "use null/empty string as
               default value" to "do nothing" (field omitted from the output).
+            - |-
+              The four "Action to take if source field has no value" choices map to:
+              do nothing → no `default` key (optionally `conditional.when:
+              extract_not_empty`); use null → `"default": null`; use empty string or
+              a custom value → `"default": "<value>"`; cause the record to fail →
+              `conditional.when: fail_record_when_empty` with no `default` key.
           examples:
             - N/A
             - '0'
@@ -3714,6 +3932,22 @@ components:
                   - $.order.lineItems[*]
                   - $.parents[*].children[*]
                   - $
+              name:
+                type: string
+                maxLength: 200
+                description: |
+                  Display label for this source object in the mapper, so the sources of
+                  an object array can be told apart instead of all showing as `$`.
+                  Has no effect at runtime; stored only when non-empty.
+                x-celigo-ai-guidance:
+                  - |-
+                    Carry an existing `name` through every edit — it is the user's label
+                    for the tab, and an entry sent without it loses the label. Duplicate
+                    names across entries are allowed. Set one only when the user names
+                    the source object; never invent labels.
+                examples:
+                  - Billing address
+                  - Shipping address
               sourceDataType:
                 type: string
                 description: |
@@ -3762,17 +3996,31 @@ components:
                 type: object
                 description: |
                   Defines conditional rules for including each array element in the result.
+                x-celigo-ai-guidance:
+                  - |-
+                    Judged against this entry's own `extract` (the array source). The
+                    design scopes the UI's tab-level "Action to take if source field has
+                    no value" to copy-as-is tabs (no child `mappings`); the API accepts
+                    `fail_record_when_empty` on a mapped entry as well, and the mapper
+                    processor honors it there — the record fails when that array is
+                    missing or empty (`errors[]` entry `code: extract_empty`, `fatal:
+                    true`, message `<generate>: Source field has no value`; probed
+                    2026-10-09). Say so when writing it on a mapped entry: the user may
+                    not find the setting in the mapper's tab. To fail on an empty field
+                    inside each element, set the action on that child mapping instead.
                 properties:
                   when:
                     type: string
                     description: |
-                      Specifies the condition that must be met for an array element to be included.
-
-                      'extract_not_empty' only includes elements where the extract field returns a value.
+                      Condition judged on the entry's extract — skip the elements the
+                      extract does not return, or fail the whole record when the source
+                      array is missing or empty.
                     enum:
                       - extract_not_empty
+                      - fail_record_when_empty
                     x-enumDescriptions:
-                      extract_not_empty: Include the array element only when the extract field returns a non-empty value.
+                      extract_not_empty: Include an array element only when the extract returns a non-empty value for it
+                      fail_record_when_empty: Fail the record when the entry's source array is missing or empty
                     examples:
                       - extract_not_empty
               mappings:
@@ -3872,6 +4120,20 @@ components:
                       extract: $.price
                       dataType: number
                       status: Active
+            if:
+              properties:
+                conditional:
+                  properties:
+                    when:
+                      const: fail_record_when_empty
+                  required:
+                    - when
+              required:
+                - conditional
+            then:
+              not:
+                required:
+                  - default
         status:
           type: string
           description: |
@@ -3879,9 +4141,10 @@ components:
             Required on every mapping entry. Controls whether the mapping is applied.
 
             **Guidance**
-            Emit `"Active"` for mappings that should run; `"Draft"` saves an
-            in-progress mapping without the Active-only field validations. The
-            API rejects a mapping missing this field
+            Only `Active` rows run. `Draft` and `Inactive` rows keep their
+            configuration, are saved with minimal validation, and are skipped at
+            runtime and in preview; a non-Active parent skips its whole subtree
+            whatever its children say. The API rejects a mapping missing this field
             (validation error: "Mapping object must have status field present.").
           x-celigo-ai-guidance:
             - |-
@@ -3890,12 +4153,28 @@ components:
               field validations. The value is case-sensitive. The API rejects:
               - Missing field: `[status_field_absent] Mapping object must have status field present.`
               - Wrong case (e.g. `"active"`): `[invalid_status_enums] active is not a valid enum for status field.`
+            - |-
+              `"Inactive"` is the user's "Set inactive" on a row: use it only when
+              asked to disable or park a row, never to mean incomplete (that is
+              `"Draft"`). Setting a parent `Inactive` means no `Active` row may
+              remain under it — the save rejects an `Active` row under an
+              `Inactive` parent (`[inactive_parent_active_child]` on `mappings`,
+              no message text) and never cascades or promotes on its own; `Draft`
+              descendants are kept as they are, and a `Draft` parent does not gate
+              its children. The UI's Set inactive on a parent marks the parent and
+              every child `Inactive` (IO-166197). Re-enabling a child
+              means re-enabling its ancestors in the same payload. Edits that keep
+              existing rows must carry their stored status forward — rewriting a
+              `Draft` or `Inactive` row to `Active` turns a row the user parked
+              back on.
           enum:
             - Active
             - Draft
+            - Inactive
           x-enumDescriptions:
-            Active: The mapping is enabled and applied during processing.
-            Draft: In-progress mapping; saved without the Active-only field validations.
+            Active: The mapping is enabled and applied during processing
+            Draft: In-progress mapping; saved without the Active-only field validations and skipped at runtime
+            Inactive: Disabled by the user; configuration kept, skipped at runtime and in preview
           examples:
             - Active
         conditional:
@@ -3924,6 +4203,10 @@ components:
             - `extract_not_empty`: Apply only when the extract field returns a value
               Useful for conditional mapping based on input data availability
 
+            - `fail_record_when_empty`: Fail the record when the extract field returns
+              no value (the UI's "Cause record to fail" action when the source field
+              has no value)
+
             **Example**
             ```json
             {
@@ -3936,28 +4219,75 @@ components:
               }
             }
             ```
+          x-celigo-ai-guidance:
+            - |-
+              `when` holds one value, and two different settings share it: the
+              composite-import operation gate (`record_created` / `record_updated`,
+              the UI's "Only perform mapping when") and the empty-source action
+              (`extract_not_empty` / `fail_record_when_empty`, the UI's "Action to
+              take if source field has no value"). A row cannot carry both — writing
+              one replaces the other and the save succeeds, so a composite import
+              row that needs both has to choose. Never author `fail_record_when_empty`
+              on a row that already carries `record_created` or `record_updated`.
           properties:
             when:
               type: string
               description: |
-                Specifies the condition that triggers application of this mapping:
-                - record_created: Apply only when creating a new record
-                - record_updated: Apply only when updating an existing record
-                - extract_not_empty: Apply only when the extract field returns a value
+                Condition that gates this mapping — either an operation gate on a
+                composite (create-or-update) import or the action to take when the
+                extract returns no value. Empty means null, undefined or an empty
+                string; `0`, `false` and whitespace are values.
+              x-celigo-ai-guidance:
+                - |-
+                  `fail_record_when_empty` is the fourth "Action to take if source field
+                  has no value" and is mutually exclusive with the other three: send it
+                  with no `default` key. A `default`, a `lookupName` or a `hardCodedValue`
+                  on the same row — or a `default` on a `buildArrayHelper` entry — is
+                  rejected at save with `[unsupported_mapping] "<key>" and conditional.when
+                  "fail_record_when_empty" cannot be present in mapping simultaneously.`
+                  (the lookup variant adds `Use lookup "allowFailures" instead.`);
+                  lookups fail through `allowFailures: false`, and a hard-coded row
+                  always has a value. At runtime an empty extract fails the record with
+                  an `errors[]` entry `{code: "extract_empty", fatal: true, source:
+                  "mapping", message: "<generate>: Source field has no value"}`
+                  ("Input field has no value" in a Transformation 2.0); `0` and `false`
+                  are values and map through.
               enum:
                 - record_created
                 - record_updated
                 - extract_not_empty
+                - fail_record_when_empty
               x-enumDescriptions:
-                record_created: Apply this mapping only when creating a new record.
-                record_updated: Apply this mapping only when updating an existing record.
-                extract_not_empty: Apply this mapping only when the extract field returns a non-empty value.
+                record_created: Apply this mapping only when creating a new record
+                record_updated: Apply this mapping only when updating an existing record
+                extract_not_empty: Apply this mapping only when the extract field returns a non-empty value
+                fail_record_when_empty: Fail the record when the extract field returns no value
               examples:
                 - record_created
                 - record_updated
                 - extract_not_empty
+                - fail_record_when_empty
       required:
         - dataType
+      if:
+        properties:
+          conditional:
+            properties:
+              when:
+                const: fail_record_when_empty
+            required:
+              - when
+        required:
+          - conditional
+      then:
+        not:
+          anyOf:
+            - required:
+                - default
+            - required:
+                - lookupName
+            - required:
+                - hardCodedValue
     Mappings:
       type: array
       description: |
@@ -3981,6 +4311,20 @@ components:
 
         The system will process these nested structures recursively during runtime, ensuring proper construction
         of complex hierarchical data while maintaining excellent performance.
+
+        On save, a leaf row with neither a source (`extract`, `hardCodedValue`, `lookupName`) nor a
+        destination (`generate`) is dropped silently, at every nesting level, and so is an object or
+        object-array row left with no source, no destination and no remaining child `mappings` or
+        `buildArrayHelper` entries; a row with only one of the two, and a source-less, destination-less
+        wrapper that still has children, are kept.
+      x-celigo-ai-guidance:
+        - |-
+          Rows that exist in the saved document — including `Draft` and `Inactive` rows and
+          rows with only a source or only a destination — are the user's state: an edit that
+          re-sends the tree must carry them through unchanged unless the user asked to change
+          them. Only a row with neither source nor destination — and, for an object or
+          object-array row, no remaining children — can be left out; the save would drop it
+          anyway. A wrapper with children but no `generate` is kept by the save, so keep it.
       items:
         type: object
         properties:
@@ -4260,7 +4604,8 @@ components:
               Explicit JSON `null` is itself a valid fallback: the destination field is written as
               JSON null when the extract yields nothing (the Mapper UI's "Use null as default value"
               action). Omitting the key entirely means no fallback — the field is left out of the
-              output when the extract is empty (the UI's "Do nothing" action).
+              output when the extract is empty (the UI's "Do nothing" action). Failing the record
+              instead is `conditional.when: fail_record_when_empty`, which excludes a default.
             x-celigo-ai-guidance:
               - |-
                 `"default": null` and `"default": ""` are distinct saved values, not
@@ -4269,6 +4614,12 @@ components:
                 Preserve them verbatim when editing or migrating a mapping — dropping
                 the key changes runtime behavior from "use null/empty string as
                 default value" to "do nothing" (field omitted from the output).
+              - |-
+                The four "Action to take if source field has no value" choices map to:
+                do nothing → no `default` key (optionally `conditional.when:
+                extract_not_empty`); use null → `"default": null`; use empty string or
+                a custom value → `"default": "<value>"`; cause the record to fail →
+                `conditional.when: fail_record_when_empty` with no `default` key.
             examples:
               - N/A
               - '0'
@@ -4601,6 +4952,22 @@ components:
                     - $.order.lineItems[*]
                     - $.parents[*].children[*]
                     - $
+                name:
+                  type: string
+                  maxLength: 200
+                  description: |
+                    Display label for this source object in the mapper, so the sources of
+                    an object array can be told apart instead of all showing as `$`.
+                    Has no effect at runtime; stored only when non-empty.
+                  x-celigo-ai-guidance:
+                    - |-
+                      Carry an existing `name` through every edit — it is the user's label
+                      for the tab, and an entry sent without it loses the label. Duplicate
+                      names across entries are allowed. Set one only when the user names
+                      the source object; never invent labels.
+                  examples:
+                    - Billing address
+                    - Shipping address
                 sourceDataType:
                   type: string
                   description: |
@@ -4649,17 +5016,31 @@ components:
                   type: object
                   description: |
                     Defines conditional rules for including each array element in the result.
+                  x-celigo-ai-guidance:
+                    - |-
+                      Judged against this entry's own `extract` (the array source). The
+                      design scopes the UI's tab-level "Action to take if source field has
+                      no value" to copy-as-is tabs (no child `mappings`); the API accepts
+                      `fail_record_when_empty` on a mapped entry as well, and the mapper
+                      processor honors it there — the record fails when that array is
+                      missing or empty (`errors[]` entry `code: extract_empty`, `fatal:
+                      true`, message `<generate>: Source field has no value`; probed
+                      2026-10-09). Say so when writing it on a mapped entry: the user may
+                      not find the setting in the mapper's tab. To fail on an empty field
+                      inside each element, set the action on that child mapping instead.
                   properties:
                     when:
                       type: string
                       description: |
-                        Specifies the condition that must be met for an array element to be included.
-
-                        'extract_not_empty' only includes elements where the extract field returns a value.
+                        Condition judged on the entry's extract — skip the elements the
+                        extract does not return, or fail the whole record when the source
+                        array is missing or empty.
                       enum:
                         - extract_not_empty
+                        - fail_record_when_empty
                       x-enumDescriptions:
-                        extract_not_empty: Include the array element only when the extract field returns a non-empty value.
+                        extract_not_empty: Include an array element only when the extract returns a non-empty value for it
+                        fail_record_when_empty: Fail the record when the entry's source array is missing or empty
                       examples:
                         - extract_not_empty
                 mappings:
@@ -4759,6 +5140,20 @@ components:
                         extract: $.price
                         dataType: number
                         status: Active
+              if:
+                properties:
+                  conditional:
+                    properties:
+                      when:
+                        const: fail_record_when_empty
+                    required:
+                      - when
+                required:
+                  - conditional
+              then:
+                not:
+                  required:
+                    - default
           status:
             type: string
             description: |
@@ -4766,9 +5161,10 @@ components:
               Required on every mapping entry. Controls whether the mapping is applied.
 
               **Guidance**
-              Emit `"Active"` for mappings that should run; `"Draft"` saves an
-              in-progress mapping without the Active-only field validations. The
-              API rejects a mapping missing this field
+              Only `Active` rows run. `Draft` and `Inactive` rows keep their
+              configuration, are saved with minimal validation, and are skipped at
+              runtime and in preview; a non-Active parent skips its whole subtree
+              whatever its children say. The API rejects a mapping missing this field
               (validation error: "Mapping object must have status field present.").
             x-celigo-ai-guidance:
               - |-
@@ -4777,12 +5173,28 @@ components:
                 field validations. The value is case-sensitive. The API rejects:
                 - Missing field: `[status_field_absent] Mapping object must have status field present.`
                 - Wrong case (e.g. `"active"`): `[invalid_status_enums] active is not a valid enum for status field.`
+              - |-
+                `"Inactive"` is the user's "Set inactive" on a row: use it only when
+                asked to disable or park a row, never to mean incomplete (that is
+                `"Draft"`). Setting a parent `Inactive` means no `Active` row may
+                remain under it — the save rejects an `Active` row under an
+                `Inactive` parent (`[inactive_parent_active_child]` on `mappings`,
+                no message text) and never cascades or promotes on its own; `Draft`
+                descendants are kept as they are, and a `Draft` parent does not gate
+                its children. The UI's Set inactive on a parent marks the parent and
+                every child `Inactive` (IO-166197). Re-enabling a child
+                means re-enabling its ancestors in the same payload. Edits that keep
+                existing rows must carry their stored status forward — rewriting a
+                `Draft` or `Inactive` row to `Active` turns a row the user parked
+                back on.
             enum:
               - Active
               - Draft
+              - Inactive
             x-enumDescriptions:
-              Active: The mapping is enabled and applied during processing.
-              Draft: In-progress mapping; saved without the Active-only field validations.
+              Active: The mapping is enabled and applied during processing
+              Draft: In-progress mapping; saved without the Active-only field validations and skipped at runtime
+              Inactive: Disabled by the user; configuration kept, skipped at runtime and in preview
             examples:
               - Active
           conditional:
@@ -4811,6 +5223,10 @@ components:
               - `extract_not_empty`: Apply only when the extract field returns a value
                 Useful for conditional mapping based on input data availability
 
+              - `fail_record_when_empty`: Fail the record when the extract field returns
+                no value (the UI's "Cause record to fail" action when the source field
+                has no value)
+
               **Example**
               ```json
               {
@@ -4823,28 +5239,75 @@ components:
                 }
               }
               ```
+            x-celigo-ai-guidance:
+              - |-
+                `when` holds one value, and two different settings share it: the
+                composite-import operation gate (`record_created` / `record_updated`,
+                the UI's "Only perform mapping when") and the empty-source action
+                (`extract_not_empty` / `fail_record_when_empty`, the UI's "Action to
+                take if source field has no value"). A row cannot carry both — writing
+                one replaces the other and the save succeeds, so a composite import
+                row that needs both has to choose. Never author `fail_record_when_empty`
+                on a row that already carries `record_created` or `record_updated`.
             properties:
               when:
                 type: string
                 description: |
-                  Specifies the condition that triggers application of this mapping:
-                  - record_created: Apply only when creating a new record
-                  - record_updated: Apply only when updating an existing record
-                  - extract_not_empty: Apply only when the extract field returns a value
+                  Condition that gates this mapping — either an operation gate on a
+                  composite (create-or-update) import or the action to take when the
+                  extract returns no value. Empty means null, undefined or an empty
+                  string; `0`, `false` and whitespace are values.
+                x-celigo-ai-guidance:
+                  - |-
+                    `fail_record_when_empty` is the fourth "Action to take if source field
+                    has no value" and is mutually exclusive with the other three: send it
+                    with no `default` key. A `default`, a `lookupName` or a `hardCodedValue`
+                    on the same row — or a `default` on a `buildArrayHelper` entry — is
+                    rejected at save with `[unsupported_mapping] "<key>" and conditional.when
+                    "fail_record_when_empty" cannot be present in mapping simultaneously.`
+                    (the lookup variant adds `Use lookup "allowFailures" instead.`);
+                    lookups fail through `allowFailures: false`, and a hard-coded row
+                    always has a value. At runtime an empty extract fails the record with
+                    an `errors[]` entry `{code: "extract_empty", fatal: true, source:
+                    "mapping", message: "<generate>: Source field has no value"}`
+                    ("Input field has no value" in a Transformation 2.0); `0` and `false`
+                    are values and map through.
                 enum:
                   - record_created
                   - record_updated
                   - extract_not_empty
+                  - fail_record_when_empty
                 x-enumDescriptions:
-                  record_created: Apply this mapping only when creating a new record.
-                  record_updated: Apply this mapping only when updating an existing record.
-                  extract_not_empty: Apply this mapping only when the extract field returns a non-empty value.
+                  record_created: Apply this mapping only when creating a new record
+                  record_updated: Apply this mapping only when updating an existing record
+                  extract_not_empty: Apply this mapping only when the extract field returns a non-empty value
+                  fail_record_when_empty: Fail the record when the extract field returns no value
                 examples:
                   - record_created
                   - record_updated
                   - extract_not_empty
+                  - fail_record_when_empty
         required:
           - dataType
+        if:
+          properties:
+            conditional:
+              properties:
+                when:
+                  const: fail_record_when_empty
+              required:
+                - when
+          required:
+            - conditional
+        then:
+          not:
+            anyOf:
+              - required:
+                  - default
+              - required:
+                  - lookupName
+              - required:
+                  - hardCodedValue
     Lookups:
       type: array
       description: |
@@ -5621,6 +6084,20 @@ components:
               ("requires at least one double stash expression"), and an unbalanced `{{record.id`
               fails with 422 "Failed to compile handlebars template". An empty string clears the
               field.
+        debugUntil:
+          type: string
+          format: date-time
+          description: |-
+            Turns on debug capture for the Tool Input stage until this time: while it lies in
+            the future, every record entering the tool is written to
+            `GET /v1/tools/{_id}/tool_input/requests` with its input-schema outcome, in every
+            execution context (standalone invoke, AI agent or MCP caller, flow or API). At
+            most 3600 seconds ahead — a later value is rejected with `422` `update_not_allowed`
+            and nothing is saved. Written by PUT or by `PATCH /v1/tools/{_id}` on
+            `/input/debugUntil`; `remove` (or a past time) stops capture. Capture is not
+            retroactive and does not change record retention.
+          examples:
+            - '2026-08-25T12:30:00.000Z'
         mockInput:
           type: object
           description: |
@@ -5793,6 +6270,20 @@ components:
                   examples:
                     - postProcessOutput
                     - validateOutput
+        debugUntil:
+          type: string
+          format: date-time
+          description: |-
+            Turns on debug capture for the Tool Output stage until this time: while it lies in
+            the future, every post-mapped record is written to
+            `GET /v1/tools/{_id}/tool_output/requests` with its output-schema outcome, in every
+            execution context (standalone invoke, AI agent or MCP caller, flow or API). At
+            most 3600 seconds ahead — a later value is rejected with `422` `update_not_allowed`
+            and nothing is saved. Written by PUT or by `PATCH /v1/tools/{_id}` on
+            `/output/debugUntil`; `remove` (or a past time) stops capture. Capture is not
+            retroactive and does not change record retention.
+          examples:
+            - '2026-08-25T12:30:00.000Z'
         mockInput:
           type: object
           description: |
@@ -24585,7 +25076,13 @@ components:
               type: string
               format: date-time
               readOnly: true
-              description: Timestamp until which debug logging is enabled for this import.
+              description: |-
+                Turns on step debug capture until this time: while it lies in the future, every
+                request this import sends — or, for a `ToolImport`, every record passing through
+                it with the tool's output — is recorded in the step's debug log
+                (`GET /v1/{flows|apis|tools}/{containerId}/{_id}/requests`). Read-only on PUT —
+                written only by `PATCH /v1/imports/{_id}` on `/debugUntil`, at most 3600 seconds
+                ahead (`422` `update_not_allowed` beyond that); `remove` stops capture.
     GroupBy:
       type: array
       description: |
@@ -36426,7 +36923,12 @@ components:
               type: string
               format: date-time
               readOnly: true
-              description: Timestamp until which debug logging is enabled for this export.
+              description: |-
+                Turns on step debug capture until this time: while it lies in the future, every
+                request this export sends is recorded in the step's debug log
+                (`GET /v1/{flows|apis|tools}/{containerId}/{_id}/requests`). Read-only on PUT —
+                written only by `PATCH /v1/exports/{_id}` on `/debugUntil`, at most 3600 seconds
+                ahead (`422` `update_not_allowed` beyond that); `remove` stops capture.
     ClonePreviewResponse:
       type: object
       description: |