@almadar/std 16.145.0 → 16.147.0

package/behaviors/registry/infra/atoms/std-migration-job.orb

@@ -0,0 +1,1310 @@
+{
+  "description": "std-migration-job — one import run of external data into the host system, modeled as a persistent MigrationJob row with a lifecycle state machine: idle → fetching → mapping → reviewing → committing → done | failed. All source access goes through the migration service (call-service \"migration\" listDocuments / fetchDocument / commit) — the atom never talks to a source directly, and the host-injected service handler resolves credentials from the connectionRef knob (a reference, never the secret). Staging/mapping is host work (deterministic pipeline or agent): the atom fetches, the host stages and emits MIGRATION_STAGED, the user approves (MIGRATION_APPROVED) and only then does commit run. Terminal runs persist the job row for provenance. Rebind the entity to a host-owned job entity via linkedEntity; target and connectionRef are config knobs.",
+  "ledger": {
+    "entries": {
+      "ent_01KYEH1JHZB917648MRS0X5P3H": {
+        "bakedName": "MigrationJob",
+        "curName": "MigrationJob",
+        "id": "ent_01KYEH1JHZB917648MRS0X5P3H",
+        "kind": "entity",
+        "owner": "workspace",
+        "renames": []
+      },
+      "evt_01KYEH1JHZ108ZC0A25A791JJG": {
+        "bakedName": "MIGRATION_FETCHED",
+        "curName": "MIGRATION_FETCHED",
+        "id": "evt_01KYEH1JHZ108ZC0A25A791JJG",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYEH1JHZFRWA4GSJPS78WGXK",
+        "renames": []
+      },
+      "evt_01KYEH1JHZ46HRGQWBVH62VTWB": {
+        "bakedName": "MIGRATION_CALL_FAILED",
+        "curName": "MIGRATION_CALL_FAILED",
+        "id": "evt_01KYEH1JHZ46HRGQWBVH62VTWB",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYEH1JHZFRWA4GSJPS78WGXK",
+        "renames": []
+      },
+      "evt_01KYEH1JHZ4P70WNXP5KD40DQD": {
+        "bakedName": "MIGRATION_RETRY",
+        "curName": "MIGRATION_RETRY",
+        "id": "evt_01KYEH1JHZ4P70WNXP5KD40DQD",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYEH1JHZFRWA4GSJPS78WGXK",
+        "renames": []
+      },
+      "evt_01KYEH1JHZ67GY1VYWWG8FJN5M": {
+        "bakedName": "MIGRATION_REJECTED",
+        "curName": "MIGRATION_REJECTED",
+        "id": "evt_01KYEH1JHZ67GY1VYWWG8FJN5M",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYEH1JHZFRWA4GSJPS78WGXK",
+        "renames": []
+      },
+      "evt_01KYEH1JHZ6TVR2PR9DCX7M0JW": {
+        "bakedName": "RESET",
+        "curName": "RESET",
+        "id": "evt_01KYEH1JHZ6TVR2PR9DCX7M0JW",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYEH1JHZFRWA4GSJPS78WGXK",
+        "renames": []
+      },
+      "evt_01KYEH1JHZANEQQJWVAQWKE7T8": {
+        "bakedName": "MIGRATION_APPROVED",
+        "curName": "MIGRATION_APPROVED",
+        "id": "evt_01KYEH1JHZANEQQJWVAQWKE7T8",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYEH1JHZFRWA4GSJPS78WGXK",
+        "renames": []
+      },
+      "evt_01KYEH1JHZCM65W3K5JPH22W1Y": {
+        "bakedName": "FETCH_DOCUMENT",
+        "curName": "FETCH_DOCUMENT",
+        "id": "evt_01KYEH1JHZCM65W3K5JPH22W1Y",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYEH1JHZFRWA4GSJPS78WGXK",
+        "renames": []
+      },
+      "evt_01KYEH1JHZE908KJFCWPSJ231V": {
+        "bakedName": "DOCUMENTS_LISTED",
+        "curName": "DOCUMENTS_LISTED",
+        "id": "evt_01KYEH1JHZE908KJFCWPSJ231V",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYEH1JHZFRWA4GSJPS78WGXK",
+        "renames": []
+      },
+      "evt_01KYEH1JHZFMZPRSAAAW5SNS5H": {
+        "bakedName": "MIGRATION_FAILED",
+        "curName": "MIGRATION_FAILED",
+        "id": "evt_01KYEH1JHZFMZPRSAAAW5SNS5H",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYEH1JHZFRWA4GSJPS78WGXK",
+        "renames": []
+      },
+      "evt_01KYEH1JHZKCD8JKV9CAHZG2JC": {
+        "bakedName": "MIGRATION_COMPLETED",
+        "curName": "MIGRATION_COMPLETED",
+        "id": "evt_01KYEH1JHZKCD8JKV9CAHZG2JC",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYEH1JHZFRWA4GSJPS78WGXK",
+        "renames": []
+      },
+      "evt_01KYEH1JHZMFZQV6JQ7BF49TGJ": {
+        "bakedName": "COMMITTED",
+        "curName": "COMMITTED",
+        "id": "evt_01KYEH1JHZMFZQV6JQ7BF49TGJ",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYEH1JHZFRWA4GSJPS78WGXK",
+        "renames": []
+      },
+      "evt_01KYEH1JHZQQGPZ8285ZJA0W2Z": {
+        "bakedName": "MIGRATION_REVIEW_READY",
+        "curName": "MIGRATION_REVIEW_READY",
+        "id": "evt_01KYEH1JHZQQGPZ8285ZJA0W2Z",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYEH1JHZFRWA4GSJPS78WGXK",
+        "renames": []
+      },
+      "evt_01KYEH1JHZS686HZ1PSX9E41SN": {
+        "bakedName": "INIT",
+        "curName": "INIT",
+        "id": "evt_01KYEH1JHZS686HZ1PSX9E41SN",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYEH1JHZFRWA4GSJPS78WGXK",
+        "renames": []
+      },
+      "evt_01KYEH1JHZTCZZE53EY6264JTY": {
+        "bakedName": "MIGRATION_STAGED",
+        "curName": "MIGRATION_STAGED",
+        "id": "evt_01KYEH1JHZTCZZE53EY6264JTY",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYEH1JHZFRWA4GSJPS78WGXK",
+        "renames": []
+      },
+      "evt_01KYEH1JHZVA84NGHKV4DNKKZ8": {
+        "bakedName": "MIGRATION_START",
+        "curName": "MIGRATION_START",
+        "id": "evt_01KYEH1JHZVA84NGHKV4DNKKZ8",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYEH1JHZFRWA4GSJPS78WGXK",
+        "renames": []
+      },
+      "evt_01KYEH1JHZXK69X09ZRB3JFTX8": {
+        "bakedName": "MIGRATION_DISCARDED",
+        "curName": "MIGRATION_DISCARDED",
+        "id": "evt_01KYEH1JHZXK69X09ZRB3JFTX8",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYEH1JHZFRWA4GSJPS78WGXK",
+        "renames": []
+      },
+      "evt_01KYEH1JHZYBNE7SNEH4YSB3AJ": {
+        "bakedName": "MIGRATION_DOCUMENT",
+        "curName": "MIGRATION_DOCUMENT",
+        "id": "evt_01KYEH1JHZYBNE7SNEH4YSB3AJ",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYEH1JHZFRWA4GSJPS78WGXK",
+        "renames": []
+      },
+      "evt_01KYEH1JHZYH9ESEMWYAGG5V20": {
+        "bakedName": "DOCUMENT_FETCHED",
+        "curName": "DOCUMENT_FETCHED",
+        "id": "evt_01KYEH1JHZYH9ESEMWYAGG5V20",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYEH1JHZFRWA4GSJPS78WGXK",
+        "renames": []
+      },
+      "orb_01KYEH1JHZPWD4MVJ22QXP4X62": {
+        "bakedName": "MigrationJobOrbital",
+        "curName": "MigrationJobOrbital",
+        "id": "orb_01KYEH1JHZPWD4MVJ22QXP4X62",
+        "kind": "orbital",
+        "owner": "workspace",
+        "renames": []
+      },
+      "pag_01KYEH1JJ0N7EVAQGKJJQBT08X": {
+        "bakedName": "MigrationJobPage",
+        "curName": "MigrationJobPage",
+        "id": "pag_01KYEH1JJ0N7EVAQGKJJQBT08X",
+        "kind": "page",
+        "owner": "workspace",
+        "renames": []
+      },
+      "trt_01KYEH1JHZFRWA4GSJPS78WGXK": {
+        "bakedName": "MigrationJobLifecycle",
+        "curName": "MigrationJobLifecycle",
+        "id": "trt_01KYEH1JHZFRWA4GSJPS78WGXK",
+        "kind": "trait",
+        "owner": "workspace",
+        "renames": []
+      }
+    },
+    "schemaVersion": 1
+  },
+  "name": "std-migration-job",
+  "orbitals": [
+    {
+      "entity": {
+        "collection": "migration_jobs",
+        "fields": [
+          {
+            "name": "id",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "default": {},
+            "description": "ImportSource descriptor of the run (kind + options), supplied by the host.",
+            "name": "source",
+            "type": "object"
+          },
+          {
+            "default": [],
+            "description": "Client-side file metadata for upload sources (name/size/type/lastModified).",
+            "items": {
+              "type": "object"
+            },
+            "name": "files",
+            "type": "array"
+          },
+          {
+            "default": "",
+            "description": "Name of the host entity this import writes into.",
+            "name": "target",
+            "type": "string"
+          },
+          {
+            "default": "idle",
+            "description": "Lifecycle position of the run.",
+            "name": "status",
+            "type": "string",
+            "values": [
+              "idle",
+              "fetching",
+              "mapping",
+              "reviewing",
+              "committing",
+              "done",
+              "failed"
+            ]
+          },
+          {
+            "default": [],
+            "description": "Document metadata listed from the source.",
+            "items": {
+              "type": "object"
+            },
+            "name": "documents",
+            "type": "array"
+          },
+          {
+            "default": {},
+            "description": "Most recently fetched document content.",
+            "name": "document",
+            "type": "object"
+          },
+          {
+            "default": {},
+            "description": "Staged/committed/failed/skipped counts.",
+            "name": "stats",
+            "type": "object"
+          },
+          {
+            "default": "",
+            "description": "Failure detail when status is failed.",
+            "name": "error",
+            "type": "string"
+          },
+          {
+            "default": 0.0,
+            "description": "Run start timestamp.",
+            "name": "createdAt",
+            "type": "number"
+          }
+        ],
+        "id": "ent_01KYEH1JHZB917648MRS0X5P3H",
+        "name": "MigrationJob",
+        "persistence": "persistent"
+      },
+      "id": "orb_01KYEH1JHZPWD4MVJ22QXP4X62",
+      "name": "MigrationJobOrbital",
+      "pages": [
+        {
+          "id": "pag_01KYEH1JJ0N7EVAQGKJJQBT08X",
+          "name": "MigrationJobPage",
+          "path": "/migration-job",
+          "traits": [
+            {
+              "ref": "MigrationJobLifecycle",
+              "refId": "trt_01KYEH1JHZFRWA4GSJPS78WGXK"
+            }
+          ]
+        }
+      ],
+      "traits": [
+        {
+          "category": "lifecycle",
+          "config": {
+            "connectionRef": {
+              "default": "",
+              "description": "Secret-store / environment KEY holding the source credentials. The reference is stored; the secret itself never enters config, traces, or snapshots — the migration service resolves it at run time. (Typed `string` until the `secret` config-field type lands in the lolo language — tracked gap.)",
+              "label": "Connection reference",
+              "synonyms": "credential key, connection string reference, secret name",
+              "tier": "internal",
+              "type": "string"
+            },
+            "target": {
+              "default": "",
+              "description": "Name of the host entity this import writes into (e.g. the organism's own entity). The migration service derives the full target descriptor from the running app's schema.",
+              "label": "Target entity",
+              "synonyms": "destination, import into, target type",
+              "tier": "domain",
+              "type": "string"
+            }
+          },
+          "emits": [
+            {
+              "description": "migration.listDocuments service result, flattened onto the payload by the call-service effect executor",
+              "event": "DOCUMENTS_LISTED",
+              "eventId": "evt_01KYEH1JHZE908KJFCWPSJ231V",
+              "payloadSchema": [
+                {
+                  "name": "documents",
+                  "required": true,
+                  "type": "[object]"
+                }
+              ],
+              "tier": "secondary"
+            },
+            {
+              "description": "migration.fetchDocument service result, flattened onto the payload by the call-service effect executor",
+              "event": "DOCUMENT_FETCHED",
+              "eventId": "evt_01KYEH1JHZYH9ESEMWYAGG5V20",
+              "payloadSchema": [
+                {
+                  "name": "document",
+                  "required": true,
+                  "type": "object"
+                }
+              ],
+              "tier": "secondary"
+            },
+            {
+              "description": "migration.commit service result — committed count plus per-unit failures",
+              "event": "COMMITTED",
+              "eventId": "evt_01KYEH1JHZMFZQV6JQ7BF49TGJ",
+              "payloadSchema": [
+                {
+                  "name": "committed",
+                  "required": true,
+                  "type": "number"
+                },
+                {
+                  "name": "failed",
+                  "required": true,
+                  "type": "[object]"
+                }
+              ],
+              "tier": "secondary"
+            },
+            {
+              "description": "migration service call failure signal — lands the run in failed, never a silent swallow",
+              "event": "MIGRATION_CALL_FAILED",
+              "eventId": "evt_01KYEH1JHZ46HRGQWBVH62VTWB",
+              "payloadSchema": [
+                {
+                  "name": "error",
+                  "required": true,
+                  "type": "string"
+                }
+              ],
+              "tier": "secondary"
+            },
+            {
+              "description": "Source documents are listed and the run is ready for staging (deterministic pipeline or agent)",
+              "event": "MIGRATION_FETCHED",
+              "eventId": "evt_01KYEH1JHZ108ZC0A25A791JJG",
+              "payloadSchema": [
+                {
+                  "name": "documents",
+                  "required": true,
+                  "type": "[object]"
+                }
+              ],
+              "scope": "external",
+              "synonyms": "import fetched, source listed, documents ready",
+              "tier": "domain"
+            },
+            {
+              "description": "A single fetched document's content, for the host staging layer to map into target units",
+              "event": "MIGRATION_DOCUMENT",
+              "eventId": "evt_01KYEH1JHZYBNE7SNEH4YSB3AJ",
+              "payloadSchema": [
+                {
+                  "name": "document",
+                  "required": true,
+                  "type": "object"
+                }
+              ],
+              "scope": "external",
+              "synonyms": "document loaded, content fetched",
+              "tier": "domain"
+            },
+            {
+              "description": "Staging is complete; the preview is ready for the approval gate",
+              "event": "MIGRATION_REVIEW_READY",
+              "eventId": "evt_01KYEH1JHZQQGPZ8285ZJA0W2Z",
+              "payloadSchema": [
+                {
+                  "name": "stats",
+                  "required": true,
+                  "type": "object"
+                }
+              ],
+              "scope": "external",
+              "synonyms": "preview ready, staging complete, review import",
+              "tier": "domain"
+            },
+            {
+              "description": "The commit drained through the host sink; stats carry committed and per-unit failed counts",
+              "event": "MIGRATION_COMPLETED",
+              "eventId": "evt_01KYEH1JHZKCD8JKV9CAHZG2JC",
+              "payloadSchema": [
+                {
+                  "name": "stats",
+                  "required": true,
+                  "type": "object"
+                }
+              ],
+              "scope": "external",
+              "synonyms": "import done, migration complete, data imported",
+              "tier": "domain"
+            },
+            {
+              "description": "The run failed; error carries the service-reported detail and the terminal job row was persisted",
+              "event": "MIGRATION_FAILED",
+              "eventId": "evt_01KYEH1JHZFMZPRSAAAW5SNS5H",
+              "payloadSchema": [
+                {
+                  "name": "error",
+                  "required": true,
+                  "type": "string"
+                }
+              ],
+              "scope": "external",
+              "synonyms": "import failed, migration error",
+              "tier": "domain"
+            }
+          ],
+          "entityContract": {
+            "provides": [
+              "document",
+              "documents",
+              "error",
+              "files",
+              "source",
+              "stats",
+              "status",
+              "target"
+            ],
+            "requires": []
+          },
+          "entityRebindable": true,
+          "entityRefIds": {
+            "MigrationJob": "ent_01KYEH1JHZB917648MRS0X5P3H"
+          },
+          "id": "trt_01KYEH1JHZFRWA4GSJPS78WGXK",
+          "linkedEntity": "MigrationJob",
+          "linkedEntityId": "ent_01KYEH1JHZB917648MRS0X5P3H",
+          "name": "MigrationJobLifecycle",
+          "scope": "instance",
+          "stateMachine": {
+            "events": [
+              {
+                "id": "evt_01KYEH1JHZS686HZ1PSX9E41SN",
+                "key": "INIT",
+                "name": "Initialize"
+              },
+              {
+                "description": "Starts an import run. source is the ImportSource descriptor; files carries client file metadata for upload sources. Also reached via a sibling std-import's IMPORT_REQUESTED.",
+                "id": "evt_01KYEH1JHZVA84NGHKV4DNKKZ8",
+                "key": "MIGRATION_START",
+                "name": "Migration Start",
+                "payloadSchema": [
+                  {
+                    "name": "source",
+                    "required": true,
+                    "type": "object"
+                  },
+                  {
+                    "name": "files",
+                    "type": "[object]"
+                  }
+                ],
+                "synonyms": "start import, run migration, import data",
+                "tier": "domain"
+              },
+              {
+                "description": "migration.listDocuments service result, flattened onto the payload by the call-service effect executor",
+                "id": "evt_01KYEH1JHZE908KJFCWPSJ231V",
+                "key": "DOCUMENTS_LISTED",
+                "name": "Documents Listed",
+                "payloadSchema": [
+                  {
+                    "name": "documents",
+                    "required": true,
+                    "type": "[object]"
+                  }
+                ],
+                "tier": "secondary"
+              },
+              {
+                "description": "Source documents are listed and the run is ready for staging (deterministic pipeline or agent)",
+                "id": "evt_01KYEH1JHZ108ZC0A25A791JJG",
+                "key": "MIGRATION_FETCHED",
+                "name": "Migration Fetched",
+                "payloadSchema": [
+                  {
+                    "name": "documents",
+                    "required": true,
+                    "type": "[object]"
+                  }
+                ],
+                "synonyms": "import fetched, source listed, documents ready",
+                "tier": "domain"
+              },
+              {
+                "description": "A single fetched document's content, for the host staging layer to map into target units",
+                "id": "evt_01KYEH1JHZYBNE7SNEH4YSB3AJ",
+                "key": "MIGRATION_DOCUMENT",
+                "name": "Migration Document",
+                "payloadSchema": [
+                  {
+                    "name": "document",
+                    "required": true,
+                    "type": "object"
+                  }
+                ],
+                "synonyms": "document loaded, content fetched",
+                "tier": "domain"
+              },
+              {
+                "description": "migration service call failure signal — lands the run in failed, never a silent swallow",
+                "id": "evt_01KYEH1JHZ46HRGQWBVH62VTWB",
+                "key": "MIGRATION_CALL_FAILED",
+                "name": "Migration Call Failed",
+                "payloadSchema": [
+                  {
+                    "name": "error",
+                    "required": true,
+                    "type": "string"
+                  }
+                ],
+                "tier": "secondary"
+              },
+              {
+                "description": "Fetch one document's full content from the source during staging",
+                "id": "evt_01KYEH1JHZCM65W3K5JPH22W1Y",
+                "key": "FETCH_DOCUMENT",
+                "name": "Fetch Document",
+                "payloadSchema": [
+                  {
+                    "name": "documentId",
+                    "required": true,
+                    "type": "string"
+                  }
+                ],
+                "tier": "internal"
+              },
+              {
+                "description": "migration.fetchDocument service result, flattened onto the payload by the call-service effect executor",
+                "id": "evt_01KYEH1JHZYH9ESEMWYAGG5V20",
+                "key": "DOCUMENT_FETCHED",
+                "name": "Document Fetched",
+                "payloadSchema": [
+                  {
+                    "name": "document",
+                    "required": true,
+                    "type": "object"
+                  }
+                ],
+                "tier": "secondary"
+              },
+              {
+                "description": "Host staging finished — units are staged and validated; stats summarize staged/skipped counts for the preview",
+                "id": "evt_01KYEH1JHZTCZZE53EY6264JTY",
+                "key": "MIGRATION_STAGED",
+                "name": "Migration Staged",
+                "payloadSchema": [
+                  {
+                    "name": "stats",
+                    "required": true,
+                    "type": "object"
+                  }
+                ],
+                "tier": "internal"
+              },
+              {
+                "description": "The run was discarded before commit",
+                "id": "evt_01KYEH1JHZXK69X09ZRB3JFTX8",
+                "key": "MIGRATION_DISCARDED",
+                "name": "Migration Discarded",
+                "tier": "internal"
+              },
+              {
+                "description": "The user approved the preview; units are the staged ImportUnits to commit through the host sink",
+                "id": "evt_01KYEH1JHZANEQQJWVAQWKE7T8",
+                "key": "MIGRATION_APPROVED",
+                "name": "Migration Approved",
+                "payloadSchema": [
+                  {
+                    "name": "units",
+                    "required": true,
+                    "type": "[object]"
+                  }
+                ],
+                "synonyms": "approve import, confirm migration",
+                "tier": "domain"
+              },
+              {
+                "description": "The user sent the preview back for more staging",
+                "id": "evt_01KYEH1JHZ67GY1VYWWG8FJN5M",
+                "key": "MIGRATION_REJECTED",
+                "name": "Migration Rejected",
+                "tier": "internal"
+              },
+              {
+                "description": "Staging is complete; the preview is ready for the approval gate",
+                "id": "evt_01KYEH1JHZQQGPZ8285ZJA0W2Z",
+                "key": "MIGRATION_REVIEW_READY",
+                "name": "Migration Review Ready",
+                "payloadSchema": [
+                  {
+                    "name": "stats",
+                    "required": true,
+                    "type": "object"
+                  }
+                ],
+                "synonyms": "preview ready, staging complete, review import",
+                "tier": "domain"
+              },
+              {
+                "description": "migration.commit service result — committed count plus per-unit failures",
+                "id": "evt_01KYEH1JHZMFZQV6JQ7BF49TGJ",
+                "key": "COMMITTED",
+                "name": "Committed",
+                "payloadSchema": [
+                  {
+                    "name": "committed",
+                    "required": true,
+                    "type": "number"
+                  },
+                  {
+                    "name": "failed",
+                    "required": true,
+                    "type": "[object]"
+                  }
+                ],
+                "tier": "secondary"
+              },
+              {
+                "description": "Returns the job to idle from a terminal state",
+                "id": "evt_01KYEH1JHZ6TVR2PR9DCX7M0JW",
+                "key": "RESET",
+                "name": "Reset",
+                "tier": "internal"
+              },
+              {
+                "description": "The commit drained through the host sink; stats carry committed and per-unit failed counts",
+                "id": "evt_01KYEH1JHZKCD8JKV9CAHZG2JC",
+                "key": "MIGRATION_COMPLETED",
+                "name": "Migration Completed",
+                "payloadSchema": [
+                  {
+                    "name": "stats",
+                    "required": true,
+                    "type": "object"
+                  }
+                ],
+                "synonyms": "import done, migration complete, data imported",
+                "tier": "domain"
+              },
+              {
+                "description": "Re-runs the fetch after a failure, with the same source",
+                "id": "evt_01KYEH1JHZ4P70WNXP5KD40DQD",
+                "key": "MIGRATION_RETRY",
+                "name": "Migration Retry",
+                "tier": "internal"
+              },
+              {
+                "description": "The run failed; error carries the service-reported detail and the terminal job row was persisted",
+                "id": "evt_01KYEH1JHZFMZPRSAAAW5SNS5H",
+                "key": "MIGRATION_FAILED",
+                "name": "Migration Failed",
+                "payloadSchema": [
+                  {
+                    "name": "error",
+                    "required": true,
+                    "type": "string"
+                  }
+                ],
+                "synonyms": "import failed, migration error",
+                "tier": "domain"
+              }
+            ],
+            "states": [
+              {
+                "isInitial": true,
+                "name": "idle"
+              },
+              {
+                "name": "fetching"
+              },
+              {
+                "name": "mapping"
+              },
+              {
+                "name": "reviewing"
+              },
+              {
+                "name": "committing"
+              },
+              {
+                "name": "done"
+              },
+              {
+                "name": "failed"
+              }
+            ],
+            "transitions": [
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.status",
+                    "idle"
+                  ],
+                  [
+                    "set",
+                    "@entity.error",
+                    ""
+                  ],
+                  [
+                    "set",
+                    "@entity.documents",
+                    []
+                  ],
+                  [
+                    "set",
+                    "@entity.document",
+                    {}
+                  ],
+                  [
+                    "set",
+                    "@entity.stats",
+                    {}
+                  ]
+                ],
+                "event": "INIT",
+                "eventId": "evt_01KYEH1JHZS686HZ1PSX9E41SN",
+                "from": "idle",
+                "to": "idle"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.source",
+                    "@payload.source"
+                  ],
+                  [
+                    "set",
+                    "@entity.files",
+                    "@payload.files"
+                  ],
+                  [
+                    "set",
+                    "@entity.target",
+                    "@config.target"
+                  ],
+                  [
+                    "set",
+                    "@entity.status",
+                    "fetching"
+                  ],
+                  [
+                    "set",
+                    "@entity.createdAt",
+                    [
+                      "time/now"
+                    ]
+                  ],
+                  [
+                    "call-service",
+                    "migration",
+                    "listDocuments",
+                    {
+                      "connectionRef": "@config.connectionRef",
+                      "files": "@entity.files",
+                      "source": "@entity.source"
+                    },
+                    {
+                      "emit": {
+                        "failure": "MIGRATION_CALL_FAILED",
+                        "success": "DOCUMENTS_LISTED"
+                      }
+                    }
+                  ]
+                ],
+                "event": "MIGRATION_START",
+                "eventId": "evt_01KYEH1JHZVA84NGHKV4DNKKZ8",
+                "from": "idle",
+                "to": "fetching"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.documents",
+                    "@payload.documents"
+                  ],
+                  [
+                    "set",
+                    "@entity.status",
+                    "mapping"
+                  ],
+                  [
+                    "emit",
+                    "MIGRATION_FETCHED",
+                    {
+                      "documents": "@entity.documents"
+                    }
+                  ]
+                ],
+                "event": "DOCUMENTS_LISTED",
+                "eventId": "evt_01KYEH1JHZE908KJFCWPSJ231V",
+                "from": "fetching",
+                "to": "mapping"
+              },
+              {
+                "event": "MIGRATION_FETCHED",
+                "eventId": "evt_01KYEH1JHZ108ZC0A25A791JJG",
+                "from": "fetching",
+                "to": "mapping"
+              },
+              {
+                "event": "MIGRATION_DOCUMENT",
+                "eventId": "evt_01KYEH1JHZYBNE7SNEH4YSB3AJ",
+                "from": "fetching",
+                "to": "mapping"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.error",
+                    "@payload.error"
+                  ],
+                  [
+                    "set",
+                    "@entity.status",
+                    "failed"
+                  ],
+                  [
+                    "persist",
+                    "create",
+                    "MigrationJob",
+                    {
+                      "createdAt": "@entity.createdAt",
+                      "error": "@entity.error",
+                      "source": "@entity.source",
+                      "stats": "@entity.stats",
+                      "status": "@entity.status",
+                      "target": "@entity.target"
+                    }
+                  ],
+                  [
+                    "emit",
+                    "MIGRATION_FAILED",
+                    {
+                      "error": "@entity.error"
+                    }
+                  ]
+                ],
+                "event": "MIGRATION_CALL_FAILED",
+                "eventId": "evt_01KYEH1JHZ46HRGQWBVH62VTWB",
+                "from": "fetching",
+                "to": "failed"
+              },
+              {
+                "effects": [
+                  [
+                    "call-service",
+                    "migration",
+                    "fetchDocument",
+                    {
+                      "connectionRef": "@config.connectionRef",
+                      "documentId": "@payload.documentId",
+                      "source": "@entity.source"
+                    },
+                    {
+                      "emit": {
+                        "failure": "MIGRATION_CALL_FAILED",
+                        "success": "DOCUMENT_FETCHED"
+                      }
+                    }
+                  ]
+                ],
+                "event": "FETCH_DOCUMENT",
+                "eventId": "evt_01KYEH1JHZCM65W3K5JPH22W1Y",
+                "from": "mapping",
+                "to": "mapping"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.document",
+                    "@payload.document"
+                  ],
+                  [
+                    "emit",
+                    "MIGRATION_DOCUMENT",
+                    {
+                      "document": "@entity.document"
+                    }
+                  ]
+                ],
+                "event": "DOCUMENT_FETCHED",
+                "eventId": "evt_01KYEH1JHZYH9ESEMWYAGG5V20",
+                "from": "mapping",
+                "to": "mapping"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.stats",
+                    "@payload.stats"
+                  ],
+                  [
+                    "set",
+                    "@entity.status",
+                    "reviewing"
+                  ],
+                  [
+                    "emit",
+                    "MIGRATION_REVIEW_READY",
+                    {
+                      "stats": "@entity.stats"
+                    }
+                  ]
+                ],
+                "event": "MIGRATION_STAGED",
+                "eventId": "evt_01KYEH1JHZTCZZE53EY6264JTY",
+                "from": "mapping",
+                "to": "reviewing"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.status",
+                    "idle"
+                  ],
+                  [
+                    "set",
+                    "@entity.documents",
+                    []
+                  ],
+                  [
+                    "set",
+                    "@entity.document",
+                    {}
+                  ],
+                  [
+                    "set",
+                    "@entity.stats",
+                    {}
+                  ]
+                ],
+                "event": "MIGRATION_DISCARDED",
+                "eventId": "evt_01KYEH1JHZXK69X09ZRB3JFTX8",
+                "from": "mapping",
+                "to": "idle"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.error",
+                    "@payload.error"
+                  ],
+                  [
+                    "set",
+                    "@entity.status",
+                    "failed"
+                  ],
+                  [
+                    "persist",
+                    "create",
+                    "MigrationJob",
+                    {
+                      "createdAt": "@entity.createdAt",
+                      "error": "@entity.error",
+                      "source": "@entity.source",
+                      "stats": "@entity.stats",
+                      "status": "@entity.status",
+                      "target": "@entity.target"
+                    }
+                  ],
+                  [
+                    "emit",
+                    "MIGRATION_FAILED",
+                    {
+                      "error": "@entity.error"
+                    }
+                  ]
+                ],
+                "event": "MIGRATION_CALL_FAILED",
+                "eventId": "evt_01KYEH1JHZ46HRGQWBVH62VTWB",
+                "from": "mapping",
+                "to": "failed"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.status",
+                    "committing"
+                  ],
+                  [
+                    "call-service",
+                    "migration",
+                    "commit",
+                    {
+                      "jobId": "@entity.id",
+                      "units": "@payload.units"
+                    },
+                    {
+                      "emit": {
+                        "failure": "MIGRATION_CALL_FAILED",
+                        "success": "COMMITTED"
+                      }
+                    }
+                  ]
+                ],
+                "event": "MIGRATION_APPROVED",
+                "eventId": "evt_01KYEH1JHZANEQQJWVAQWKE7T8",
+                "from": "reviewing",
+                "to": "committing"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.status",
+                    "mapping"
+                  ]
+                ],
+                "event": "MIGRATION_REJECTED",
+                "eventId": "evt_01KYEH1JHZ67GY1VYWWG8FJN5M",
+                "from": "reviewing",
+                "to": "mapping"
+              },
+              {
+                "event": "MIGRATION_REVIEW_READY",
+                "eventId": "evt_01KYEH1JHZQQGPZ8285ZJA0W2Z",
+                "from": "reviewing",
+                "to": "reviewing"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.status",
+                    "idle"
+                  ],
+                  [
+                    "set",
+                    "@entity.documents",
+                    []
+                  ],
+                  [
+                    "set",
+                    "@entity.document",
+                    {}
+                  ],
+                  [
+                    "set",
+                    "@entity.stats",
+                    {}
+                  ]
+                ],
+                "event": "MIGRATION_DISCARDED",
+                "eventId": "evt_01KYEH1JHZXK69X09ZRB3JFTX8",
+                "from": "reviewing",
+                "to": "idle"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.stats",
+                    [
+                      "object/merge",
+                      "@entity.stats",
+                      {
+                        "committed": "@payload.committed",
+                        "failed": "@payload.failed"
+                      }
+                    ]
+                  ],
+                  [
+                    "set",
+                    "@entity.status",
+                    "done"
+                  ],
+                  [
+                    "persist",
+                    "create",
+                    "MigrationJob",
+                    {
+                      "createdAt": "@entity.createdAt",
+                      "error": "",
+                      "source": "@entity.source",
+                      "stats": "@entity.stats",
+                      "status": "@entity.status",
+                      "target": "@entity.target"
+                    }
+                  ],
+                  [
+                    "emit",
+                    "MIGRATION_COMPLETED",
+                    {
+                      "stats": "@entity.stats"
+                    }
+                  ]
+                ],
+                "event": "COMMITTED",
+                "eventId": "evt_01KYEH1JHZMFZQV6JQ7BF49TGJ",
+                "from": "committing",
+                "to": "done"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.error",
+                    "@payload.error"
+                  ],
+                  [
+                    "set",
+                    "@entity.status",
+                    "failed"
+                  ],
+                  [
+                    "persist",
+                    "create",
+                    "MigrationJob",
+                    {
+                      "createdAt": "@entity.createdAt",
+                      "error": "@entity.error",
+                      "source": "@entity.source",
+                      "stats": "@entity.stats",
+                      "status": "@entity.status",
+                      "target": "@entity.target"
+                    }
+                  ],
+                  [
+                    "emit",
+                    "MIGRATION_FAILED",
+                    {
+                      "error": "@entity.error"
+                    }
+                  ]
+                ],
+                "event": "MIGRATION_CALL_FAILED",
+                "eventId": "evt_01KYEH1JHZ46HRGQWBVH62VTWB",
+                "from": "committing",
+                "to": "failed"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.status",
+                    "idle"
+                  ],
+                  [
+                    "set",
+                    "@entity.error",
+                    ""
+                  ],
+                  [
+                    "set",
+                    "@entity.documents",
+                    []
+                  ],
+                  [
+                    "set",
+                    "@entity.document",
+                    {}
+                  ],
+                  [
+                    "set",
+                    "@entity.stats",
+                    {}
+                  ]
+                ],
+                "event": "RESET",
+                "eventId": "evt_01KYEH1JHZ6TVR2PR9DCX7M0JW",
+                "from": "done",
+                "to": "idle"
+              },
+              {
+                "event": "MIGRATION_COMPLETED",
+                "eventId": "evt_01KYEH1JHZKCD8JKV9CAHZG2JC",
+                "from": "done",
+                "to": "done"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.status",
+                    "fetching"
+                  ],
+                  [
+                    "set",
+                    "@entity.error",
+                    ""
+                  ],
+                  [
+                    "call-service",
+                    "migration",
+                    "listDocuments",
+                    {
+                      "connectionRef": "@config.connectionRef",
+                      "files": "@entity.files",
+                      "source": "@entity.source"
+                    },
+                    {
+                      "emit": {
+                        "failure": "MIGRATION_CALL_FAILED",
+                        "success": "DOCUMENTS_LISTED"
+                      }
+                    }
+                  ]
+                ],
+                "event": "MIGRATION_RETRY",
+                "eventId": "evt_01KYEH1JHZ4P70WNXP5KD40DQD",
+                "from": "failed",
+                "to": "fetching"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.status",
+                    "idle"
+                  ],
+                  [
+                    "set",
+                    "@entity.error",
+                    ""
+                  ],
+                  [
+                    "set",
+                    "@entity.documents",
+                    []
+                  ],
+                  [
+                    "set",
+                    "@entity.document",
+                    {}
+                  ],
+                  [
+                    "set",
+                    "@entity.stats",
+                    {}
+                  ]
+                ],
+                "event": "RESET",
+                "eventId": "evt_01KYEH1JHZ6TVR2PR9DCX7M0JW",
+                "from": "failed",
+                "to": "idle"
+              },
+              {
+                "event": "MIGRATION_FAILED",
+                "eventId": "evt_01KYEH1JHZFMZPRSAAAW5SNS5H",
+                "from": "failed",
+                "to": "failed"
+              }
+            ]
+          }
+        }
+      ]
+    }
+  ],
+  "schemaVersion": 1,
+  "version": "1.0.0"
+}