@celigo/api-specs 0.2.113 → 0.2.115

package/dist/api.yml

@@ -6470,6 +6470,7 @@ components:
             but a decimal is rejected with 422 `invalid_field_value` on every write (the same rule applies to every
             adaptor's `concurrencyLevel` and `targetConcurrencyLevel`, and to `ftp.multiThreadCount`).
             Platform-managed while `autoRecoverRateLimitErrors` is true — a PUT ignores the value and the recovery machinery moves it toward the target; set `targetConcurrencyLevel` instead.
+            At level 1 an import's pages run one at a time, so a record's existence lookup and write finish before the next record's start (measured on a single import); the import's `idLockTemplate` serializes only same-key records and leaves the rest parallel.
           minimum: 1
           maximum: 50
           default: 25

package/dist/connection.yml

@@ -5581,6 +5581,7 @@ components:
             but a decimal is rejected with 422 `invalid_field_value` on every write (the same rule applies to every
             adaptor's `concurrencyLevel` and `targetConcurrencyLevel`, and to `ftp.multiThreadCount`).
             Platform-managed while `autoRecoverRateLimitErrors` is true — a PUT ignores the value and the recovery machinery moves it toward the target; set `targetConcurrencyLevel` instead.
+            At level 1 an import's pages run one at a time, so a record's existence lookup and write finish before the next record's start (measured on a single import); the import's `idLockTemplate` serializes only same-key records and leaves the rest parallel.
           minimum: 1
           maximum: 50
           default: 25

package/dist/enduser.yml

@@ -3682,6 +3682,7 @@ components:
             but a decimal is rejected with 422 `invalid_field_value` on every write (the same rule applies to every
             adaptor's `concurrencyLevel` and `targetConcurrencyLevel`, and to `ftp.multiThreadCount`).
             Platform-managed while `autoRecoverRateLimitErrors` is true — a PUT ignores the value and the recovery machinery moves it toward the target; set `targetConcurrencyLevel` instead.
+            At level 1 an import's pages run one at a time, so a record's existence lookup and write finish before the next record's start (measured on a single import); the import's `idLockTemplate` serializes only same-key records and leaves the rest parallel.
           minimum: 1
           maximum: 50
           default: 25

package/dist/export.yml

@@ -2074,6 +2074,7 @@ components:
           x-celigo-ai-guidance:
             - 'Set this only when the records sit inside an object (`{"data": {"items": [...]}}` → `data.items`). A sender that already posts a top-level array needs nothing here; a sender that posts an object with no path configured delivers exactly one record per request — the whole object — which is also the way to make one request one record on purpose.'
             - 'Records are paged per request at the export''s `pageSize` (default 20) before any hook, filter, or downstream step runs: a 25-element array is a page of 20 records followed by a page of 5, and a `preSavePage` hook receives one page (up to `pageSize` records) per call. A hook that groups rows by order therefore groups only the rows on the same page — an order whose rows span two pages comes out as two grouped records, the second after the first was already processed. To keep a request''s rows together, have the sender wrap them in an object (one record, rows under `record.<path>`) or raise `pageSize` above the largest request — never `groupByFields`, which the listener applies per page after paging.'
+            - 'Requests that arrive together, or while the listener''s current run is still collecting, become additional pages of that same run; a request that arrives after the run has stopped collecting starts a new run. Nothing on the listener de-duplicates: a sender that fires the same event twice (a retry, a button clicked twice) delivers two records, and the step that writes the effect has to be made idempotent — `ignoreExisting` or a keyed upsert under the import''s `idLockTemplate`.'
           examples:
             - events
             - data.items
@@ -16060,9 +16061,25 @@ components:
             Handlebars template that overrides how each record's unique trace key is generated, used
             to track records through the flow and match retries to prior errors (e.g.
             `{{join "_" record.customerId record.orderId}}`). When omitted, the system picks a unique
-            field automatically. If a transform reshapes the data first, omit the `record.` prefix.
-            Trace keys are capped at 256 characters; a longer key is stored truncated from the middle,
-            keeping the beginning and end of the value.
+            field automatically from the record's top level, by exact field name (`GET
+            /v1/flows/{_id}/traceKey` serves the pattern). The rendered value of a template is stamped
+            on each record as `io_custom_trace_key` and travels downstream with it. If a transform
+            reshapes the data first, omit the `record.` prefix. Trace keys are capped at 256 characters;
+            a longer key is stored truncated from the middle, keeping the beginning and end of the
+            value. Downstream imports use the trace key as their default concurrency lock key (a blank
+            key means no lock); it never de-duplicates — a record emitted twice with the same key is
+            processed twice.
+          x-celigo-ai-guidance:
+            - |-
+              The default derivation reads these top-level fields in order and takes the first present
+              (a record carrying `id` and `internalId` is keyed on `id` alone) — `id`, `Id`, `ID`,
+              `internalid`, `Internalid`, `internalId`, `InternalId`, `INTERNALID`, `_id`, `_Id`, `_ID`,
+              `internal_id`, `internal_Id`, `Internal_id`, `Internal_Id`, `INTERNAL_ID`, `identifier`,
+              `IDENTIFIER` — then a `*anything` rule the platform does not document.
+            - |-
+              A record in flight through the flow carries `io_custom_trace_key` when a template is set
+              — that value is the downstream imports' default lock key; without a template the record
+              carries no trace-key field (the key is derived, not stored on the record).
           examples:
             - '{{record.id}}'
             - '{{join "_" record.customerId record.orderId}}'

package/dist/flow.yml

@@ -835,8 +835,10 @@ paths:
         To trace a run end-to-end, arm debug logging before calling this, then use the returned
         `_jobId` with the execution-log endpoints. For delta backfills, prefer passing explicit
         `startDate`/`endDate` over editing the export's `lastExportDateTime` — the override is
-        scoped to one run. A 200 with `_jobId` absent means the request was accepted but no job
-        was queued, usually because another run is already in progress.
+        scoped to one run. A flow runs one instance at a time: a run requested while another
+        instance is queued or running is refused with `409 job_already_queued` ("Another instance
+        for this flow is already queued or running"), and a run-next-flow trigger that arrives in
+        that state is dropped rather than queued.
       parameters:
         - name: _id
           in: path
@@ -890,6 +892,20 @@ paths:
           $ref: '#/components/responses/401-unauthorized'
         '404':
           $ref: '#/components/responses/404-not-found'
+        '409':
+          description: |-
+            Another instance of this flow is already queued or running. Wait for it to
+            finish (poll `GET /v1/flows/{_id}/jobs/latest`) and request the run again.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                default:
+                  value:
+                    errors:
+                      - code: job_already_queued
+                        message: Another instance for this flow is already queued or running. Please try again later.
         '422':
           $ref: '#/components/responses/422-unprocessable-entity'
   /v1/flows/{_flowId}/runs/stats:
@@ -5531,7 +5547,9 @@ components:
           description: |-
             Flow IDs to trigger after this flow completes successfully. Accepts null as
             equivalent to an empty list (the server also serves null on documents saved
-            that way).
+            that way). The trigger starts the next flow from its own source steps and passes
+            it no records; a trigger that fires while the next flow is already queued or running
+            is dropped, not queued, so several completions in quick succession start it once.
           items:
             type: string
             format: objectId

package/dist/import.yml

@@ -5639,12 +5639,20 @@ components:
           type:
             - string
             - 'null'
-          description: Name of the lookup used to determine which records to ignore when ignore-existing is enabled.
+          description: |-
+            Name of an entry in `lookups` that probes the database per record to decide whether it
+            already exists, so `ignoreExisting` can skip it (or `ignoreMissing` can skip records with
+            no match). Use it when existence must be read from the database; use `ignoreExtract` when
+            the incoming record already carries the field that signals existence.
         ignoreExtract:
           type:
             - string
             - 'null'
-          description: Path used to extract the value that determines whether a record is ignored when ignore-existing is enabled.
+          description: |-
+            Path to a field on the incoming record whose presence decides the skip: with
+            `ignoreExisting`, a populated value marks the record as existing and it is skipped; with
+            `ignoreMissing`, an empty value marks it as missing and it is skipped. Zero per-record
+            overhead; set exactly one of `ignoreExtract` / `ignoreLookupName`.
       if:
         not:
           propertyNames:
@@ -15925,17 +15933,49 @@ components:
           type: boolean
           description: |-
             When true, records that do not already exist in the destination system are silently
-            skipped instead of producing errors — used for update-only operations.
+            skipped instead of producing errors — used for update-only operations. Existing records
+            are identified the same way as for `ignoreExisting`: the adaptor's ignore lookup
+            (`ignoreLookupName`) or a populated `ignoreExtract` field on the incoming record.
         idLockTemplate:
           type:
             - string
             - 'null'
           description: |-
-            Handlebars template that generates a lock key for each record so records resolving to
-            the same key are not submitted concurrently, preventing duplicate or conflicting writes
-            to the same target record.
+            Handlebars template that generates a concurrency lock key for each record: records that
+            render the same key are never submitted at the same time, while records with different
+            keys are processed in parallel. When omitted, the record's trace key is the lock key (a
+            blank trace key means no lock; a custom `traceKeyTemplate` upstream arrives on the record
+            as `io_custom_trace_key`); a template replaces that default rather than adding to it.
+            The template is rendered from the record as it arrives at the import — before the import's
+            own lookups and mapping run — so a key built from one of the import's lookup results
+            (`{{lookup.<name>}}`) or from a mapped field renders empty, and an empty key is no lock at
+            all; a field added upstream by a lookup step's response mapping is on the record and works.
+          x-celigo-ai-guidance:
+            - |-
+              The lock is scoped to this import resource across every page and every concurrent run
+              that submits through it — including other flows sharing the import — not to one page,
+              and not to the connection: two different imports rendering the same key on the same
+              connection still run in parallel. Records within a single page are
+              sent one at a time regardless, so the lock matters when same-key records sit in different
+              pages or runs.
+            - |-
+              With `ignoreExisting` and an ignore lookup, the existence lookup runs inside the lock:
+              lookup-then-write for one key does not interleave with another record's lookup-then-write
+              for the same key. That pairing is the duplicate-prevention pattern for destinations that
+              can be queried but do not reject duplicates — key the lock on the business identifier the
+              write is keyed on. With the check but no lock, concurrent same-key pages all read a miss
+              before any write lands and all create. Connection `concurrencyLevel: 1` also closes that
+              race for the import (measured on a single import: its pages ran one at a time and the
+              same-key pages created once) — the lock is the per-key tool that leaves unrelated records
+              parallel.
+            - |-
+              Key it on a field the record carries when it reaches this import (`{{{record.externalId}}}-GR`,
+              or a field an upstream lookup step added through its response mapping), never on one of
+              this import's own lookup results; the key must render non-empty for the records that
+              matter, or those records have no lock.
           examples:
             - '{{record.customerId}}'
+            - '{{{record.externalId}}}-GR'
         dataURITemplate:
           type:
             - string
@@ -16055,7 +16095,9 @@ components:
             Handlebars template that overrides how each record's unique trace key is generated,
             used to track records through the flow and match errors to records. Trace keys are
             capped at 256 characters; a longer key is stored truncated from the middle, keeping
-            the beginning and end of the value.
+            the beginning and end of the value. The trace key is also the import's default
+            concurrency lock key when `idLockTemplate` is not set; it never de-duplicates — a record
+            that arrives twice with the same key is processed twice.
           x-celigo-ai-guidance:
             - |-
               ## CRITICAL: ONLY VALID WHEN ``oneToMany: true``

package/dist/lookupcache.yml

@@ -410,7 +410,12 @@ paths:
       summary: Upsert entries into a lookup cache
       description: |-
         Writes key-value entries to a lookup cache. Keys that already exist are
-        overwritten; new keys are created. Values may be null, numbers, booleans,
+        overwritten; new keys are created. There is no insert-only, create-if-absent or
+        compare-and-set mode — a write never fails because the key exists, so a
+        "first writer wins" claim cannot be built on this call alone: make the claim
+        on the flow's import step instead (`ignoreExisting` with a `getData` lookup on
+        the key, under `idLockTemplate` on the same key), which serializes
+        read-then-write per key. Values may be null, numbers, booleans,
         strings, or objects — arrays at the top level are rejected (wrap them in an
         object). One invalid entry fails the entire batch and nothing in it is written:
         a bad value returns `400 invalid_value`, and an empty, missing, or over-length

package/dist/mcp-server.yml

@@ -5507,6 +5507,7 @@ components:
             but a decimal is rejected with 422 `invalid_field_value` on every write (the same rule applies to every
             adaptor's `concurrencyLevel` and `targetConcurrencyLevel`, and to `ftp.multiThreadCount`).
             Platform-managed while `autoRecoverRateLimitErrors` is true — a PUT ignores the value and the recovery machinery moves it toward the target; set `targetConcurrencyLevel` instead.
+            At level 1 an import's pages run one at a time, so a record's existence lookup and write finish before the next record's start (measured on a single import); the import's `idLockTemplate` serializes only same-key records and leaves the rest parallel.
           minimum: 1
           maximum: 50
           default: 25

package/dist/tool.yml

@@ -8836,6 +8836,7 @@ components:
             but a decimal is rejected with 422 `invalid_field_value` on every write (the same rule applies to every
             adaptor's `concurrencyLevel` and `targetConcurrencyLevel`, and to `ftp.multiThreadCount`).
             Platform-managed while `autoRecoverRateLimitErrors` is true — a PUT ignores the value and the recovery machinery moves it toward the target; set `targetConcurrencyLevel` instead.
+            At level 1 an import's pages run one at a time, so a record's existence lookup and write finish before the next record's start (measured on a single import); the import's `idLockTemplate` serializes only same-key records and leaves the rest parallel.
           minimum: 1
           maximum: 50
           default: 25
@@ -16949,12 +16950,20 @@ components:
           type:
             - string
             - 'null'
-          description: Name of the lookup used to determine which records to ignore when ignore-existing is enabled.
+          description: |-
+            Name of an entry in `lookups` that probes the database per record to decide whether it
+            already exists, so `ignoreExisting` can skip it (or `ignoreMissing` can skip records with
+            no match). Use it when existence must be read from the database; use `ignoreExtract` when
+            the incoming record already carries the field that signals existence.
         ignoreExtract:
           type:
             - string
             - 'null'
-          description: Path used to extract the value that determines whether a record is ignored when ignore-existing is enabled.
+          description: |-
+            Path to a field on the incoming record whose presence decides the skip: with
+            `ignoreExisting`, a populated value marks the record as existing and it is skipped; with
+            `ignoreMissing`, an empty value marks it as missing and it is skipped. Zero per-record
+            overhead; set exactly one of `ignoreExtract` / `ignoreLookupName`.
       if:
         not:
           propertyNames:
@@ -24792,17 +24801,49 @@ components:
           type: boolean
           description: |-
             When true, records that do not already exist in the destination system are silently
-            skipped instead of producing errors — used for update-only operations.
+            skipped instead of producing errors — used for update-only operations. Existing records
+            are identified the same way as for `ignoreExisting`: the adaptor's ignore lookup
+            (`ignoreLookupName`) or a populated `ignoreExtract` field on the incoming record.
         idLockTemplate:
           type:
             - string
             - 'null'
           description: |-
-            Handlebars template that generates a lock key for each record so records resolving to
-            the same key are not submitted concurrently, preventing duplicate or conflicting writes
-            to the same target record.
+            Handlebars template that generates a concurrency lock key for each record: records that
+            render the same key are never submitted at the same time, while records with different
+            keys are processed in parallel. When omitted, the record's trace key is the lock key (a
+            blank trace key means no lock; a custom `traceKeyTemplate` upstream arrives on the record
+            as `io_custom_trace_key`); a template replaces that default rather than adding to it.
+            The template is rendered from the record as it arrives at the import — before the import's
+            own lookups and mapping run — so a key built from one of the import's lookup results
+            (`{{lookup.<name>}}`) or from a mapped field renders empty, and an empty key is no lock at
+            all; a field added upstream by a lookup step's response mapping is on the record and works.
+          x-celigo-ai-guidance:
+            - |-
+              The lock is scoped to this import resource across every page and every concurrent run
+              that submits through it — including other flows sharing the import — not to one page,
+              and not to the connection: two different imports rendering the same key on the same
+              connection still run in parallel. Records within a single page are
+              sent one at a time regardless, so the lock matters when same-key records sit in different
+              pages or runs.
+            - |-
+              With `ignoreExisting` and an ignore lookup, the existence lookup runs inside the lock:
+              lookup-then-write for one key does not interleave with another record's lookup-then-write
+              for the same key. That pairing is the duplicate-prevention pattern for destinations that
+              can be queried but do not reject duplicates — key the lock on the business identifier the
+              write is keyed on. With the check but no lock, concurrent same-key pages all read a miss
+              before any write lands and all create. Connection `concurrencyLevel: 1` also closes that
+              race for the import (measured on a single import: its pages ran one at a time and the
+              same-key pages created once) — the lock is the per-key tool that leaves unrelated records
+              parallel.
+            - |-
+              Key it on a field the record carries when it reaches this import (`{{{record.externalId}}}-GR`,
+              or a field an upstream lookup step added through its response mapping), never on one of
+              this import's own lookup results; the key must render non-empty for the records that
+              matter, or those records have no lock.
           examples:
             - '{{record.customerId}}'
+            - '{{{record.externalId}}}-GR'
         dataURITemplate:
           type:
             - string
@@ -24922,7 +24963,9 @@ components:
             Handlebars template that overrides how each record's unique trace key is generated,
             used to track records through the flow and match errors to records. Trace keys are
             capped at 256 characters; a longer key is stored truncated from the middle, keeping
-            the beginning and end of the value.
+            the beginning and end of the value. The trace key is also the import's default
+            concurrency lock key when `idLockTemplate` is not set; it never de-duplicates — a record
+            that arrives twice with the same key is processed twice.
           x-celigo-ai-guidance:
             - |-
               ## CRITICAL: ONLY VALID WHEN ``oneToMany: true``
@@ -26682,6 +26725,7 @@ components:
           x-celigo-ai-guidance:
             - 'Set this only when the records sit inside an object (`{"data": {"items": [...]}}` → `data.items`). A sender that already posts a top-level array needs nothing here; a sender that posts an object with no path configured delivers exactly one record per request — the whole object — which is also the way to make one request one record on purpose.'
             - 'Records are paged per request at the export''s `pageSize` (default 20) before any hook, filter, or downstream step runs: a 25-element array is a page of 20 records followed by a page of 5, and a `preSavePage` hook receives one page (up to `pageSize` records) per call. A hook that groups rows by order therefore groups only the rows on the same page — an order whose rows span two pages comes out as two grouped records, the second after the first was already processed. To keep a request''s rows together, have the sender wrap them in an object (one record, rows under `record.<path>`) or raise `pageSize` above the largest request — never `groupByFields`, which the listener applies per page after paging.'
+            - 'Requests that arrive together, or while the listener''s current run is still collecting, become additional pages of that same run; a request that arrives after the run has stopped collecting starts a new run. Nothing on the listener de-duplicates: a sender that fires the same event twice (a retry, a button clicked twice) delivers two records, and the step that writes the effect has to be made idempotent — `ignoreExisting` or a keyed upsert under the import''s `idLockTemplate`.'
           examples:
             - events
             - data.items
@@ -36913,9 +36957,25 @@ components:
             Handlebars template that overrides how each record's unique trace key is generated, used
             to track records through the flow and match retries to prior errors (e.g.
             `{{join "_" record.customerId record.orderId}}`). When omitted, the system picks a unique
-            field automatically. If a transform reshapes the data first, omit the `record.` prefix.
-            Trace keys are capped at 256 characters; a longer key is stored truncated from the middle,
-            keeping the beginning and end of the value.
+            field automatically from the record's top level, by exact field name (`GET
+            /v1/flows/{_id}/traceKey` serves the pattern). The rendered value of a template is stamped
+            on each record as `io_custom_trace_key` and travels downstream with it. If a transform
+            reshapes the data first, omit the `record.` prefix. Trace keys are capped at 256 characters;
+            a longer key is stored truncated from the middle, keeping the beginning and end of the
+            value. Downstream imports use the trace key as their default concurrency lock key (a blank
+            key means no lock); it never de-duplicates — a record emitted twice with the same key is
+            processed twice.
+          x-celigo-ai-guidance:
+            - |-
+              The default derivation reads these top-level fields in order and takes the first present
+              (a record carrying `id` and `internalId` is keyed on `id` alone) — `id`, `Id`, `ID`,
+              `internalid`, `Internalid`, `internalId`, `InternalId`, `INTERNALID`, `_id`, `_Id`, `_ID`,
+              `internal_id`, `internal_Id`, `Internal_id`, `Internal_Id`, `INTERNAL_ID`, `identifier`,
+              `IDENTIFIER` — then a `*anything` rule the platform does not document.
+            - |-
+              A record in flight through the flow carries `io_custom_trace_key` when a template is set
+              — that value is the downstream imports' default lock key; without a template the record
+              carries no trace-key field (the key is derived, not stored on the record).
           examples:
             - '{{record.id}}'
             - '{{join "_" record.customerId record.orderId}}'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.113",
+  "version": "0.2.115",
   "private": false,
   "description": "Public OpenAPI bundles (dist/) and the celigo-cli lint schema pack (schemas.json).",
   "keywords": [

package/schemas.json

@@ -1,7 +1,7 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "af39c6bc",
+		"iasCommit": "d2a71cdf",
 		"generatedAt": "2026-10-15"
 	},
 	"roots": {