@almadar/std 16.181.0 → 16.182.0

package/behaviors/registry/infra/atoms/std-calendar-sync.orb

@@ -0,0 +1,1643 @@
+{
+  "description": "std-calendar-sync — two-way Google Calendar synchronization engine. PUSH: a 15-minute cron scan (and the user-addressable SYNC_NOW) walks `targetEntity` rows whose `externalEventId` marker is blank and creates a remote event per row through calendar.createEvent, reading the summary/start/end via the configured field mapping (`titleField`/`startField`/`endField`/`durationMinutes` fallback/`locationField`/`descriptionField`) — so ANY event-shaped host entity pushes, provided it declares the two marker columns `externalEventId : string` and `syncedAt : number` (the remindedAt precedent). PULL: `CAL_REMOTE_CHANGED` (delivered by the shared /api/hooks/google-calendar ingress from a calendar.watch channel) or the same cycle after a clean push lists remote events (incremental via the in-memory sync token; a restart falls back to a full window list) and upserts each into the atom's own canonical `CalendarEvent` store, matched by `externalEventId` — pulls land in the canonical store, NOT the arbitrary target, because persist keys are static in the language; bind calendar UI to `CalendarEvent` to surface remote events. Conflict detection (local-newer-than-remote) needs a local-modified marker convention and is a recorded gap, not a decorative state. Composes with std-notify-on-event via CAL_SYNCED / CAL_SYNC_FAILED.",
+  "ledger": {
+    "entries": {
+      "ent_01M0M9E89Q1H8VNNH0J06PH7RH": {
+        "bakedName": "CalendarEvent",
+        "curName": "CalendarEvent",
+        "id": "ent_01M0M9E89Q1H8VNNH0J06PH7RH",
+        "kind": "entity",
+        "owner": "workspace",
+        "renames": []
+      },
+      "ent_01M0MAF1B71AH9M3J5ZYKAXFM3": {
+        "bakedName": "CalendarSyncRun",
+        "curName": "CalendarSyncRun",
+        "id": "ent_01M0MAF1B71AH9M3J5ZYKAXFM3",
+        "kind": "entity",
+        "owner": "workspace",
+        "renames": []
+      },
+      "evt_01M0M9E89Q006H33RM6WGB8QRJ": {
+        "bakedName": "CAL_REMOTE_LISTED",
+        "curName": "CAL_REMOTE_LISTED",
+        "id": "evt_01M0M9E89Q006H33RM6WGB8QRJ",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01M0M9E89QMEF62295H7XTZDND",
+        "renames": []
+      },
+      "evt_01M0M9E89Q7GVB4RTA9MQZKB90": {
+        "bakedName": "CAL_SYNCED",
+        "curName": "CAL_SYNCED",
+        "id": "evt_01M0M9E89Q7GVB4RTA9MQZKB90",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01M0M9E89QMEF62295H7XTZDND",
+        "renames": []
+      },
+      "evt_01M0M9E89Q7PTP9ZRG3M5VD1SY": {
+        "bakedName": "SYNC_NOW",
+        "curName": "SYNC_NOW",
+        "id": "evt_01M0M9E89Q7PTP9ZRG3M5VD1SY",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01M0M9E89QMEF62295H7XTZDND",
+        "renames": []
+      },
+      "evt_01M0M9E89Q9N7X13XMTK58JYY9": {
+        "bakedName": "CAL_EVENT_CREATED",
+        "curName": "CAL_EVENT_CREATED",
+        "id": "evt_01M0M9E89Q9N7X13XMTK58JYY9",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01M0M9E89QMEF62295H7XTZDND",
+        "renames": []
+      },
+      "evt_01M0M9E89QBVVRWENZKAMT0H2B": {
+        "bakedName": "CAL_REMOTE_CHANGED",
+        "curName": "CAL_REMOTE_CHANGED",
+        "id": "evt_01M0M9E89QBVVRWENZKAMT0H2B",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01M0M9E89QMEF62295H7XTZDND",
+        "renames": []
+      },
+      "evt_01M0M9E89QMRE2B1QZPM8HPXS5": {
+        "bakedName": "CAL_SYNC_FAILED",
+        "curName": "CAL_SYNC_FAILED",
+        "id": "evt_01M0M9E89QMRE2B1QZPM8HPXS5",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01M0M9E89QMEF62295H7XTZDND",
+        "renames": []
+      },
+      "evt_01M0M9E89QR7NR9G2343SA8BPM": {
+        "bakedName": "PULL_STEPPED",
+        "curName": "PULL_STEPPED",
+        "id": "evt_01M0M9E89QR7NR9G2343SA8BPM",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01M0M9E89QMEF62295H7XTZDND",
+        "renames": []
+      },
+      "evt_01M0M9E89QRFQJNXPGD4C8XFP0": {
+        "bakedName": "PUSH_STEPPED",
+        "curName": "PUSH_STEPPED",
+        "id": "evt_01M0M9E89QRFQJNXPGD4C8XFP0",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01M0M9E89QMEF62295H7XTZDND",
+        "renames": []
+      },
+      "evt_01M0M9E89QV7Q7Z4KV2FHA4QZC": {
+        "bakedName": "PULL_NEXT",
+        "curName": "PULL_NEXT",
+        "id": "evt_01M0M9E89QV7Q7Z4KV2FHA4QZC",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01M0M9E89QMEF62295H7XTZDND",
+        "renames": []
+      },
+      "evt_01M0M9E89QVRM9F7VRMWJ8NT71": {
+        "bakedName": "PUSH_ROWS_LOADED",
+        "curName": "PUSH_ROWS_LOADED",
+        "id": "evt_01M0M9E89QVRM9F7VRMWJ8NT71",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01M0M9E89QMEF62295H7XTZDND",
+        "renames": []
+      },
+      "evt_01M0M9E89QYTZJDGBZVC1BVZDY": {
+        "bakedName": "INIT",
+        "curName": "INIT",
+        "id": "evt_01M0M9E89QYTZJDGBZVC1BVZDY",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01M0M9E89QMEF62295H7XTZDND",
+        "renames": []
+      },
+      "evt_01M0M9E89QZS3J82D8V4N7GNTX": {
+        "bakedName": "PULL_TARGET_LOADED",
+        "curName": "PULL_TARGET_LOADED",
+        "id": "evt_01M0M9E89QZS3J82D8V4N7GNTX",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01M0M9E89QMEF62295H7XTZDND",
+        "renames": []
+      },
+      "orb_01M0M9E89QS0N7F1YWY99SQVH1": {
+        "bakedName": "CalendarSyncOrbital",
+        "curName": "CalendarSyncOrbital",
+        "id": "orb_01M0M9E89QS0N7F1YWY99SQVH1",
+        "kind": "orbital",
+        "owner": "workspace",
+        "renames": []
+      },
+      "pag_01M0M9E89Q5PSV0NJ8P9N6X0JZ": {
+        "bakedName": "CalendarSyncPage",
+        "curName": "CalendarSyncPage",
+        "id": "pag_01M0M9E89Q5PSV0NJ8P9N6X0JZ",
+        "kind": "page",
+        "owner": "workspace",
+        "renames": []
+      },
+      "trt_01M0M9E89QMEF62295H7XTZDND": {
+        "bakedName": "CalendarSync",
+        "curName": "CalendarSync",
+        "id": "trt_01M0M9E89QMEF62295H7XTZDND",
+        "kind": "trait",
+        "owner": "workspace",
+        "renames": []
+      }
+    },
+    "schemaVersion": 1
+  },
+  "name": "std-calendar-sync",
+  "orbitals": [
+    {
+      "auxiliaryEntities": [
+        {
+          "collection": "calendarEvents",
+          "fields": [
+            {
+              "name": "id",
+              "required": true,
+              "type": "string"
+            },
+            {
+              "default": "",
+              "description": "Event title/summary.",
+              "name": "title",
+              "synonyms": "summary, name, subject",
+              "type": "string"
+            },
+            {
+              "default": "",
+              "description": "ISO start (dateTime, or YYYY-MM-DD for all-day).",
+              "name": "startsAt",
+              "synonyms": "start, begins, from",
+              "type": "string"
+            },
+            {
+              "default": "",
+              "description": "ISO end (dateTime, or YYYY-MM-DD for all-day).",
+              "name": "endsAt",
+              "synonyms": "end, finishes, until",
+              "type": "string"
+            },
+            {
+              "default": "",
+              "description": "Event location.",
+              "name": "location",
+              "synonyms": "place, where, venue",
+              "type": "string"
+            },
+            {
+              "default": "",
+              "description": "Event description/notes.",
+              "name": "description",
+              "synonyms": "notes, details, body",
+              "type": "string"
+            },
+            {
+              "default": "",
+              "description": "Remote status (confirmed/tentative/cancelled).",
+              "name": "status",
+              "synonyms": "state, confirmation",
+              "type": "string"
+            },
+            {
+              "default": "",
+              "description": "Google Calendar event id this row mirrors; the pull-upsert match key.",
+              "name": "externalEventId",
+              "synonyms": "remote id, google id, calendar event id",
+              "type": "string"
+            },
+            {
+              "default": 0.0,
+              "description": "When this row last synced with the remote calendar; 0 = never.",
+              "name": "syncedAt",
+              "synonyms": "last sync, synced",
+              "type": "number"
+            }
+          ],
+          "id": "ent_01M0M9E89Q1H8VNNH0J06PH7RH",
+          "name": "CalendarEvent",
+          "persistence": "persistent"
+        }
+      ],
+      "entity": {
+        "collection": "calendarSyncState",
+        "fields": [
+          {
+            "name": "id",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "default": "",
+            "description": "Scratch: Google incremental-sync token from the last listEvents; in-memory per instance — a restart falls back to a full list.",
+            "name": "syncToken",
+            "synonyms": "sync cursor, next token",
+            "type": "string"
+          },
+          {
+            "default": 0.0,
+            "description": "When the last full push+pull cycle completed; 0 = never.",
+            "name": "lastSyncedAt",
+            "synonyms": "last sync time",
+            "type": "number"
+          },
+          {
+            "default": "",
+            "description": "Scratch: id of the target row the push loop is currently exporting.",
+            "name": "headId",
+            "synonyms": "cursor, current row",
+            "type": "string"
+          },
+          {
+            "default": [],
+            "description": "Scratch: remote events remaining in the current pull-upsert loop.",
+            "items": {
+              "properties": {
+                "description": {
+                  "name": "description",
+                  "required": false,
+                  "type": "string"
+                },
+                "end": {
+                  "name": "end",
+                  "required": false,
+                  "type": "string"
+                },
+                "id": {
+                  "name": "id",
+                  "required": false,
+                  "type": "string"
+                },
+                "location": {
+                  "name": "location",
+                  "required": false,
+                  "type": "string"
+                },
+                "start": {
+                  "name": "start",
+                  "required": false,
+                  "type": "string"
+                },
+                "status": {
+                  "name": "status",
+                  "required": false,
+                  "type": "string"
+                },
+                "summary": {
+                  "name": "summary",
+                  "required": false,
+                  "type": "string"
+                },
+                "updated": {
+                  "name": "updated",
+                  "required": false,
+                  "type": "string"
+                }
+              },
+              "type": "object"
+            },
+            "name": "pending",
+            "synonyms": "pull queue, remaining events",
+            "type": "array"
+          },
+          {
+            "default": "",
+            "description": "Last sync failure detail; blank = none.",
+            "name": "lastError",
+            "synonyms": "sync error, failure",
+            "type": "string"
+          }
+        ],
+        "id": "ent_01M0MAF1B71AH9M3J5ZYKAXFM3",
+        "name": "CalendarSyncRun",
+        "persistence": "persistent"
+      },
+      "id": "orb_01M0M9E89QS0N7F1YWY99SQVH1",
+      "name": "CalendarSyncOrbital",
+      "pages": [
+        {
+          "id": "pag_01M0M9E89Q5PSV0NJ8P9N6X0JZ",
+          "name": "CalendarSyncPage",
+          "path": "/calendar-sync",
+          "traits": [
+            {
+              "ref": "CalendarSync",
+              "refId": "trt_01M0M9E89QMEF62295H7XTZDND"
+            }
+          ]
+        }
+      ],
+      "traits": [
+        {
+          "category": "lifecycle",
+          "config": {
+            "calendarId": {
+              "default": "",
+              "description": "Google calendar to sync with; blank = the service's default (GOOGLE_CALENDAR_ID env, else primary).",
+              "label": "Calendar id",
+              "synonyms": "google calendar id, target calendar",
+              "tier": "infra",
+              "type": "string"
+            },
+            "descriptionField": {
+              "default": "",
+              "description": "Target-entity field holding the description/notes; blank = none.",
+              "label": "Description field",
+              "synonyms": "notes field, details field",
+              "tier": "internal",
+              "type": "string"
+            },
+            "durationField": {
+              "default": "",
+              "description": "Target-entity field holding the per-row duration in minutes (e.g. ClassSession.durationMinutes). Takes precedence over the fixed `durationMinutes` when set; ignored when `endField` is set. Field precedence: endField > durationField > durationMinutes — the corpus carries all these event shapes.",
+              "label": "Duration field",
+              "synonyms": "minutes field, length field, per-row duration",
+              "tier": "internal",
+              "type": "string"
+            },
+            "durationMinutes": {
+              "default": 60.0,
+              "description": "Fixed event length used when both `endField` and `durationField` are blank; the calendar service computes the timezone-correct end.",
+              "label": "Duration (minutes)",
+              "synonyms": "length, event duration, minutes",
+              "tier": "internal",
+              "type": "number"
+            },
+            "enabled": {
+              "default": false,
+              "description": "Push local records to Google Calendar and pull remote events into the CalendarEvent store. Off by default; needs the calendar service credentials (GOOGLE_CALENDAR_SA_KEY).",
+              "label": "Sync with Google Calendar",
+              "synonyms": "enable, calendar sync, google calendar, two-way sync, sync events, connect calendar",
+              "tier": "infra",
+              "type": "boolean"
+            },
+            "endField": {
+              "default": "endsAt",
+              "description": "Target-entity field holding the ISO end. Blank = derive the end from `durationMinutes` instead (the corpus carries all four event shapes).",
+              "label": "End field",
+              "synonyms": "end date field, finishes field",
+              "tier": "internal",
+              "type": "string"
+            },
+            "locationField": {
+              "default": "",
+              "description": "Target-entity field holding the location; blank = none.",
+              "label": "Location field",
+              "synonyms": "place field, venue field",
+              "tier": "internal",
+              "type": "string"
+            },
+            "startField": {
+              "default": "startsAt",
+              "description": "Target-entity field holding the ISO start (dateTime, or YYYY-MM-DD for all-day).",
+              "label": "Start field",
+              "synonyms": "start date field, begins field, scheduledAt field",
+              "tier": "internal",
+              "type": "string"
+            },
+            "targetEntity": {
+              "default": "CalendarEvent",
+              "description": "Event-shaped entity whose rows export to Google Calendar. MUST declare the marker columns `externalEventId : string = \"\"` and `syncedAt : number = 0` (stamped by the push loop). Defaults to the atom's own CalendarEvent store so the standalone validates; rebind per composition.",
+              "label": "Entity to push",
+              "refId": "ent_01M0M9E89Q1H8VNNH0J06PH7RH",
+              "synonyms": "entity to sync, source entity, record type, appointments entity, sessions entity",
+              "tier": "internal",
+              "type": "entity"
+            },
+            "titleField": {
+              "default": "title",
+              "description": "Target-entity field holding the event title.",
+              "label": "Title field",
+              "synonyms": "summary field, name field",
+              "tier": "internal",
+              "type": "string"
+            }
+          },
+          "emits": [
+            {
+              "description": "A full push+pull cycle completed; wire to std-notify-on-event or a status surface.",
+              "event": "CAL_SYNCED",
+              "eventId": "evt_01M0M9E89Q7GVB4RTA9MQZKB90",
+              "payloadSchema": [
+                {
+                  "name": "syncedAt",
+                  "type": "number"
+                }
+              ],
+              "scope": "external"
+            },
+            {
+              "description": "A calendar service call / fetch / persist failed — lastError carries the detail and the cycle stops until the next trigger.",
+              "event": "CAL_SYNC_FAILED",
+              "eventId": "evt_01M0M9E89QMRE2B1QZPM8HPXS5",
+              "payloadSchema": [
+                {
+                  "name": "error",
+                  "required": true,
+                  "type": "string"
+                }
+              ],
+              "tier": "secondary"
+            },
+            {
+              "description": "Target rows with a blank externalEventId marker — the remaining local→remote export queue.",
+              "event": "PUSH_ROWS_LOADED",
+              "eventId": "evt_01M0M9E89QVRM9F7VRMWJ8NT71",
+              "payloadSchema": [
+                {
+                  "name": "data",
+                  "type": "[TargetRow]"
+                }
+              ],
+              "tier": "secondary"
+            },
+            {
+              "description": "calendar.createEvent result, flattened onto the payload by the call-service effect executor.",
+              "event": "CAL_EVENT_CREATED",
+              "eventId": "evt_01M0M9E89Q9N7X13XMTK58JYY9",
+              "payloadSchema": [
+                {
+                  "name": "id",
+                  "required": true,
+                  "type": "string"
+                },
+                {
+                  "name": "status",
+                  "required": true,
+                  "type": "string"
+                },
+                {
+                  "name": "htmlLink",
+                  "required": true,
+                  "type": "string"
+                }
+              ],
+              "tier": "secondary"
+            },
+            {
+              "description": "Target row stamped with its new externalEventId; drives the next push pass.",
+              "event": "PUSH_STEPPED",
+              "eventId": "evt_01M0M9E89QRFQJNXPGD4C8XFP0",
+              "payloadSchema": [
+                {
+                  "name": "id",
+                  "required": true,
+                  "type": "string"
+                }
+              ],
+              "tier": "secondary"
+            },
+            {
+              "description": "calendar.listEvents result — the remote change set for the pull-upsert loop.",
+              "event": "CAL_REMOTE_LISTED",
+              "eventId": "evt_01M0M9E89Q006H33RM6WGB8QRJ",
+              "payloadSchema": [
+                {
+                  "name": "events",
+                  "type": "[RemoteEvent]"
+                },
+                {
+                  "name": "nextSyncToken",
+                  "type": "string"
+                }
+              ],
+              "tier": "secondary"
+            },
+            {
+              "description": "CalendarEvent rows loaded for externalEventId matching in the pull-upsert.",
+              "event": "PULL_TARGET_LOADED",
+              "eventId": "evt_01M0M9E89QZS3J82D8V4N7GNTX",
+              "payloadSchema": [
+                {
+                  "name": "data",
+                  "type": "[TargetRow]"
+                }
+              ],
+              "tier": "secondary"
+            },
+            {
+              "description": "One remote event upserted into the CalendarEvent store; drives the next pull pass.",
+              "event": "PULL_STEPPED",
+              "eventId": "evt_01M0M9E89QR7NR9G2343SA8BPM",
+              "payloadSchema": [
+                {
+                  "name": "id",
+                  "required": true,
+                  "type": "string"
+                }
+              ],
+              "tier": "secondary"
+            },
+            {
+              "description": "Pull loop control: how many remote events remain in the queue.",
+              "event": "PULL_NEXT",
+              "eventId": "evt_01M0M9E89QV7Q7Z4KV2FHA4QZC",
+              "payloadSchema": [
+                {
+                  "name": "remaining",
+                  "type": "number"
+                }
+              ],
+              "tier": "secondary"
+            }
+          ],
+          "entityRefIds": {
+            "CalendarEvent": "ent_01M0M9E89Q1H8VNNH0J06PH7RH",
+            "CalendarSyncRun": "ent_01M0MAF1B71AH9M3J5ZYKAXFM3"
+          },
+          "id": "trt_01M0M9E89QMEF62295H7XTZDND",
+          "linkedEntity": "CalendarSyncRun",
+          "linkedEntityId": "ent_01M0MAF1B71AH9M3J5ZYKAXFM3",
+          "name": "CalendarSync",
+          "scope": "instance",
+          "stateMachine": {
+            "events": [
+              {
+                "id": "evt_01M0M9E89QYTZJDGBZVC1BVZDY",
+                "key": "INIT",
+                "name": "Initialize"
+              },
+              {
+                "id": "evt_01M0M9E89Q7PTP9ZRG3M5VD1SY",
+                "key": "SYNC_NOW",
+                "name": "Sync Now"
+              },
+              {
+                "id": "evt_01M0M9E89QBVVRWENZKAMT0H2B",
+                "key": "CAL_REMOTE_CHANGED",
+                "name": "Cal Remote Changed",
+                "payloadSchema": [
+                  {
+                    "name": "channelId",
+                    "type": "string"
+                  },
+                  {
+                    "name": "resourceId",
+                    "type": "string"
+                  },
+                  {
+                    "name": "resourceState",
+                    "type": "string"
+                  }
+                ]
+              },
+              {
+                "description": "Target rows with a blank externalEventId marker — the remaining local→remote export queue.",
+                "id": "evt_01M0M9E89QVRM9F7VRMWJ8NT71",
+                "key": "PUSH_ROWS_LOADED",
+                "name": "Push Rows Loaded",
+                "payloadSchema": [
+                  {
+                    "name": "data",
+                    "properties": [
+                      {
+                        "name": "id",
+                        "type": "string"
+                      },
+                      {
+                        "name": "externalEventId",
+                        "type": "string"
+                      }
+                    ],
+                    "type": "[object]"
+                  }
+                ],
+                "tier": "secondary"
+              },
+              {
+                "description": "calendar.listEvents result — the remote change set for the pull-upsert loop.",
+                "id": "evt_01M0M9E89Q006H33RM6WGB8QRJ",
+                "key": "CAL_REMOTE_LISTED",
+                "name": "Cal Remote Listed",
+                "payloadSchema": [
+                  {
+                    "name": "events",
+                    "properties": [
+                      {
+                        "name": "id",
+                        "type": "string"
+                      },
+                      {
+                        "name": "summary",
+                        "type": "string"
+                      },
+                      {
+                        "name": "description",
+                        "type": "string"
+                      },
+                      {
+                        "name": "location",
+                        "type": "string"
+                      },
+                      {
+                        "name": "start",
+                        "type": "string"
+                      },
+                      {
+                        "name": "end",
+                        "type": "string"
+                      },
+                      {
+                        "name": "status",
+                        "type": "string"
+                      },
+                      {
+                        "name": "updated",
+                        "type": "string"
+                      }
+                    ],
+                    "type": "[object]"
+                  },
+                  {
+                    "name": "nextSyncToken",
+                    "type": "string"
+                  }
+                ],
+                "tier": "secondary"
+              },
+              {
+                "description": "A calendar service call / fetch / persist failed — lastError carries the detail and the cycle stops until the next trigger.",
+                "id": "evt_01M0M9E89QMRE2B1QZPM8HPXS5",
+                "key": "CAL_SYNC_FAILED",
+                "name": "Cal Sync Failed",
+                "payloadSchema": [
+                  {
+                    "name": "error",
+                    "required": true,
+                    "type": "string"
+                  }
+                ],
+                "tier": "secondary"
+              },
+              {
+                "description": "calendar.createEvent result, flattened onto the payload by the call-service effect executor.",
+                "id": "evt_01M0M9E89Q9N7X13XMTK58JYY9",
+                "key": "CAL_EVENT_CREATED",
+                "name": "Cal Event Created",
+                "payloadSchema": [
+                  {
+                    "name": "id",
+                    "required": true,
+                    "type": "string"
+                  },
+                  {
+                    "name": "status",
+                    "required": true,
+                    "type": "string"
+                  },
+                  {
+                    "name": "htmlLink",
+                    "required": true,
+                    "type": "string"
+                  }
+                ],
+                "tier": "secondary"
+              },
+              {
+                "description": "Target row stamped with its new externalEventId; drives the next push pass.",
+                "id": "evt_01M0M9E89QRFQJNXPGD4C8XFP0",
+                "key": "PUSH_STEPPED",
+                "name": "Push Stepped",
+                "payloadSchema": [
+                  {
+                    "name": "id",
+                    "required": true,
+                    "type": "string"
+                  }
+                ],
+                "tier": "secondary"
+              },
+              {
+                "description": "CalendarEvent rows loaded for externalEventId matching in the pull-upsert.",
+                "id": "evt_01M0M9E89QZS3J82D8V4N7GNTX",
+                "key": "PULL_TARGET_LOADED",
+                "name": "Pull Target Loaded",
+                "payloadSchema": [
+                  {
+                    "name": "data",
+                    "properties": [
+                      {
+                        "name": "id",
+                        "type": "string"
+                      },
+                      {
+                        "name": "externalEventId",
+                        "type": "string"
+                      }
+                    ],
+                    "type": "[object]"
+                  }
+                ],
+                "tier": "secondary"
+              },
+              {
+                "description": "One remote event upserted into the CalendarEvent store; drives the next pull pass.",
+                "id": "evt_01M0M9E89QR7NR9G2343SA8BPM",
+                "key": "PULL_STEPPED",
+                "name": "Pull Stepped",
+                "payloadSchema": [
+                  {
+                    "name": "id",
+                    "required": true,
+                    "type": "string"
+                  }
+                ],
+                "tier": "secondary"
+              },
+              {
+                "description": "Pull loop control: how many remote events remain in the queue.",
+                "id": "evt_01M0M9E89QV7Q7Z4KV2FHA4QZC",
+                "key": "PULL_NEXT",
+                "name": "Pull Next",
+                "payloadSchema": [
+                  {
+                    "name": "remaining",
+                    "type": "number"
+                  }
+                ],
+                "tier": "secondary"
+              },
+              {
+                "description": "A full push+pull cycle completed; wire to std-notify-on-event or a status surface.",
+                "id": "evt_01M0M9E89Q7GVB4RTA9MQZKB90",
+                "key": "CAL_SYNCED",
+                "name": "Cal Synced",
+                "payloadSchema": [
+                  {
+                    "name": "syncedAt",
+                    "type": "number"
+                  }
+                ]
+              }
+            ],
+            "states": [
+              {
+                "isInitial": true,
+                "name": "idle"
+              },
+              {
+                "name": "pushing"
+              },
+              {
+                "name": "pulling"
+              }
+            ],
+            "transitions": [
+              {
+                "event": "INIT",
+                "eventId": "evt_01M0M9E89QYTZJDGBZVC1BVZDY",
+                "from": "idle",
+                "to": "idle"
+              },
+              {
+                "effects": [
+                  [
+                    "fetch",
+                    "@config.targetEntity",
+                    {
+                      "emit": {
+                        "failure": "CAL_SYNC_FAILED",
+                        "success": "PUSH_ROWS_LOADED"
+                      },
+                      "filter": [
+                        "=",
+                        [
+                          "object/get",
+                          "@entity",
+                          "externalEventId"
+                        ],
+                        ""
+                      ]
+                    }
+                  ]
+                ],
+                "event": "SYNC_NOW",
+                "eventId": "evt_01M0M9E89Q7PTP9ZRG3M5VD1SY",
+                "from": "idle",
+                "guard": "@config.enabled",
+                "to": "idle"
+              },
+              {
+                "effects": [
+                  [
+                    "call-service",
+                    "calendar",
+                    "listEvents",
+                    {
+                      "calendarId": "@config.calendarId",
+                      "syncToken": "@entity.syncToken"
+                    },
+                    {
+                      "emit": {
+                        "failure": "CAL_SYNC_FAILED",
+                        "success": "CAL_REMOTE_LISTED"
+                      }
+                    }
+                  ]
+                ],
+                "event": "CAL_REMOTE_CHANGED",
+                "eventId": "evt_01M0M9E89QBVVRWENZKAMT0H2B",
+                "from": "idle",
+                "guard": "@config.enabled",
+                "to": "idle"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.headId",
+                    [
+                      "object/get",
+                      [
+                        "array/first",
+                        "@payload.data"
+                      ],
+                      "id"
+                    ]
+                  ],
+                  [
+                    "call-service",
+                    "calendar",
+                    "createEvent",
+                    {
+                      "calendarId": "@config.calendarId",
+                      "description": [
+                        "if",
+                        [
+                          "=",
+                          "@config.descriptionField",
+                          ""
+                        ],
+                        "",
+                        [
+                          "object/get",
+                          [
+                            "array/first",
+                            "@payload.data"
+                          ],
+                          "@config.descriptionField"
+                        ]
+                      ],
+                      "durationMinutes": [
+                        "if",
+                        [
+                          "=",
+                          "@config.durationField",
+                          ""
+                        ],
+                        "@config.durationMinutes",
+                        [
+                          "object/get",
+                          [
+                            "array/first",
+                            "@payload.data"
+                          ],
+                          "@config.durationField"
+                        ]
+                      ],
+                      "end": [
+                        "if",
+                        [
+                          "=",
+                          "@config.endField",
+                          ""
+                        ],
+                        "",
+                        [
+                          "object/get",
+                          [
+                            "array/first",
+                            "@payload.data"
+                          ],
+                          "@config.endField"
+                        ]
+                      ],
+                      "location": [
+                        "if",
+                        [
+                          "=",
+                          "@config.locationField",
+                          ""
+                        ],
+                        "",
+                        [
+                          "object/get",
+                          [
+                            "array/first",
+                            "@payload.data"
+                          ],
+                          "@config.locationField"
+                        ]
+                      ],
+                      "start": [
+                        "object/get",
+                        [
+                          "array/first",
+                          "@payload.data"
+                        ],
+                        "@config.startField"
+                      ],
+                      "summary": [
+                        "object/get",
+                        [
+                          "array/first",
+                          "@payload.data"
+                        ],
+                        "@config.titleField"
+                      ]
+                    },
+                    {
+                      "emit": {
+                        "failure": "CAL_SYNC_FAILED",
+                        "success": "CAL_EVENT_CREATED"
+                      }
+                    }
+                  ]
+                ],
+                "event": "PUSH_ROWS_LOADED",
+                "eventId": "evt_01M0M9E89QVRM9F7VRMWJ8NT71",
+                "from": "idle",
+                "guard": [
+                  "and",
+                  "@config.enabled",
+                  [
+                    ">",
+                    [
+                      "array/len",
+                      "@payload.data"
+                    ],
+                    0.0
+                  ]
+                ],
+                "to": "pushing"
+              },
+              {
+                "effects": [
+                  [
+                    "call-service",
+                    "calendar",
+                    "listEvents",
+                    {
+                      "calendarId": "@config.calendarId",
+                      "syncToken": "@entity.syncToken"
+                    },
+                    {
+                      "emit": {
+                        "failure": "CAL_SYNC_FAILED",
+                        "success": "CAL_REMOTE_LISTED"
+                      }
+                    }
+                  ]
+                ],
+                "event": "PUSH_ROWS_LOADED",
+                "eventId": "evt_01M0M9E89QVRM9F7VRMWJ8NT71",
+                "from": "idle",
+                "guard": [
+                  "=",
+                  [
+                    "array/len",
+                    "@payload.data"
+                  ],
+                  0.0
+                ],
+                "to": "idle"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.pending",
+                    "@payload.events"
+                  ],
+                  [
+                    "set",
+                    "@entity.syncToken",
+                    [
+                      "str/default",
+                      "@payload.nextSyncToken",
+                      ""
+                    ]
+                  ],
+                  [
+                    "fetch",
+                    "CalendarEvent",
+                    {
+                      "emit": {
+                        "failure": "CAL_SYNC_FAILED",
+                        "success": "PULL_TARGET_LOADED"
+                      }
+                    }
+                  ]
+                ],
+                "event": "CAL_REMOTE_LISTED",
+                "eventId": "evt_01M0M9E89Q006H33RM6WGB8QRJ",
+                "from": "idle",
+                "guard": [
+                  ">",
+                  [
+                    "array/len",
+                    "@payload.events"
+                  ],
+                  0.0
+                ],
+                "to": "pulling"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.syncToken",
+                    [
+                      "str/default",
+                      "@payload.nextSyncToken",
+                      ""
+                    ]
+                  ],
+                  [
+                    "set",
+                    "@entity.lastSyncedAt",
+                    "@now"
+                  ],
+                  [
+                    "emit",
+                    "CAL_SYNCED",
+                    {
+                      "syncedAt": "@entity.lastSyncedAt"
+                    }
+                  ]
+                ],
+                "event": "CAL_REMOTE_LISTED",
+                "eventId": "evt_01M0M9E89Q006H33RM6WGB8QRJ",
+                "from": "idle",
+                "guard": [
+                  "=",
+                  [
+                    "array/len",
+                    "@payload.events"
+                  ],
+                  0.0
+                ],
+                "to": "idle"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.lastError",
+                    "@payload.error"
+                  ]
+                ],
+                "event": "CAL_SYNC_FAILED",
+                "eventId": "evt_01M0M9E89QMRE2B1QZPM8HPXS5",
+                "from": "idle",
+                "to": "idle"
+              },
+              {
+                "effects": [
+                  [
+                    "persist",
+                    "update",
+                    "@config.targetEntity",
+                    {
+                      "externalEventId": "@payload.id",
+                      "id": "@entity.headId",
+                      "syncedAt": "@now"
+                    },
+                    {
+                      "emit": {
+                        "failure": "CAL_SYNC_FAILED",
+                        "success": "PUSH_STEPPED"
+                      }
+                    }
+                  ]
+                ],
+                "event": "CAL_EVENT_CREATED",
+                "eventId": "evt_01M0M9E89Q9N7X13XMTK58JYY9",
+                "from": "pushing",
+                "to": "pushing"
+              },
+              {
+                "effects": [
+                  [
+                    "fetch",
+                    "@config.targetEntity",
+                    {
+                      "emit": {
+                        "failure": "CAL_SYNC_FAILED",
+                        "success": "PUSH_ROWS_LOADED"
+                      },
+                      "filter": [
+                        "=",
+                        [
+                          "object/get",
+                          "@entity",
+                          "externalEventId"
+                        ],
+                        ""
+                      ]
+                    }
+                  ]
+                ],
+                "event": "PUSH_STEPPED",
+                "eventId": "evt_01M0M9E89QRFQJNXPGD4C8XFP0",
+                "from": "pushing",
+                "to": "pushing"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.headId",
+                    [
+                      "object/get",
+                      [
+                        "array/first",
+                        "@payload.data"
+                      ],
+                      "id"
+                    ]
+                  ],
+                  [
+                    "call-service",
+                    "calendar",
+                    "createEvent",
+                    {
+                      "calendarId": "@config.calendarId",
+                      "description": [
+                        "if",
+                        [
+                          "=",
+                          "@config.descriptionField",
+                          ""
+                        ],
+                        "",
+                        [
+                          "object/get",
+                          [
+                            "array/first",
+                            "@payload.data"
+                          ],
+                          "@config.descriptionField"
+                        ]
+                      ],
+                      "durationMinutes": [
+                        "if",
+                        [
+                          "=",
+                          "@config.durationField",
+                          ""
+                        ],
+                        "@config.durationMinutes",
+                        [
+                          "object/get",
+                          [
+                            "array/first",
+                            "@payload.data"
+                          ],
+                          "@config.durationField"
+                        ]
+                      ],
+                      "end": [
+                        "if",
+                        [
+                          "=",
+                          "@config.endField",
+                          ""
+                        ],
+                        "",
+                        [
+                          "object/get",
+                          [
+                            "array/first",
+                            "@payload.data"
+                          ],
+                          "@config.endField"
+                        ]
+                      ],
+                      "location": [
+                        "if",
+                        [
+                          "=",
+                          "@config.locationField",
+                          ""
+                        ],
+                        "",
+                        [
+                          "object/get",
+                          [
+                            "array/first",
+                            "@payload.data"
+                          ],
+                          "@config.locationField"
+                        ]
+                      ],
+                      "start": [
+                        "object/get",
+                        [
+                          "array/first",
+                          "@payload.data"
+                        ],
+                        "@config.startField"
+                      ],
+                      "summary": [
+                        "object/get",
+                        [
+                          "array/first",
+                          "@payload.data"
+                        ],
+                        "@config.titleField"
+                      ]
+                    },
+                    {
+                      "emit": {
+                        "failure": "CAL_SYNC_FAILED",
+                        "success": "CAL_EVENT_CREATED"
+                      }
+                    }
+                  ]
+                ],
+                "event": "PUSH_ROWS_LOADED",
+                "eventId": "evt_01M0M9E89QVRM9F7VRMWJ8NT71",
+                "from": "pushing",
+                "guard": [
+                  ">",
+                  [
+                    "array/len",
+                    "@payload.data"
+                  ],
+                  0.0
+                ],
+                "to": "pushing"
+              },
+              {
+                "effects": [
+                  [
+                    "call-service",
+                    "calendar",
+                    "listEvents",
+                    {
+                      "calendarId": "@config.calendarId",
+                      "syncToken": "@entity.syncToken"
+                    },
+                    {
+                      "emit": {
+                        "failure": "CAL_SYNC_FAILED",
+                        "success": "CAL_REMOTE_LISTED"
+                      }
+                    }
+                  ]
+                ],
+                "event": "PUSH_ROWS_LOADED",
+                "eventId": "evt_01M0M9E89QVRM9F7VRMWJ8NT71",
+                "from": "pushing",
+                "guard": [
+                  "=",
+                  [
+                    "array/len",
+                    "@payload.data"
+                  ],
+                  0.0
+                ],
+                "to": "idle"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.lastError",
+                    "@payload.error"
+                  ]
+                ],
+                "event": "CAL_SYNC_FAILED",
+                "eventId": "evt_01M0M9E89QMRE2B1QZPM8HPXS5",
+                "from": "pushing",
+                "to": "idle"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.headId",
+                    [
+                      "object/get",
+                      [
+                        "array/first",
+                        "@entity.pending"
+                      ],
+                      "id"
+                    ]
+                  ],
+                  [
+                    "if",
+                    [
+                      "=",
+                      [
+                        "array/len",
+                        [
+                          "array/filter",
+                          "@payload.data",
+                          [
+                            "fn",
+                            "r",
+                            [
+                              "=",
+                              [
+                                "object/get",
+                                "@r",
+                                "externalEventId"
+                              ],
+                              "@entity.headId"
+                            ]
+                          ]
+                        ]
+                      ],
+                      0.0
+                    ],
+                    [
+                      "persist",
+                      "create",
+                      "CalendarEvent",
+                      {
+                        "description": [
+                          "object/get",
+                          [
+                            "array/first",
+                            "@entity.pending"
+                          ],
+                          "description"
+                        ],
+                        "endsAt": [
+                          "object/get",
+                          [
+                            "array/first",
+                            "@entity.pending"
+                          ],
+                          "end"
+                        ],
+                        "externalEventId": "@entity.headId",
+                        "location": [
+                          "object/get",
+                          [
+                            "array/first",
+                            "@entity.pending"
+                          ],
+                          "location"
+                        ],
+                        "startsAt": [
+                          "object/get",
+                          [
+                            "array/first",
+                            "@entity.pending"
+                          ],
+                          "start"
+                        ],
+                        "status": [
+                          "object/get",
+                          [
+                            "array/first",
+                            "@entity.pending"
+                          ],
+                          "status"
+                        ],
+                        "syncedAt": "@now",
+                        "title": [
+                          "object/get",
+                          [
+                            "array/first",
+                            "@entity.pending"
+                          ],
+                          "summary"
+                        ]
+                      },
+                      {
+                        "emit": {
+                          "failure": "CAL_SYNC_FAILED",
+                          "success": "PULL_STEPPED"
+                        }
+                      }
+                    ],
+                    [
+                      "persist",
+                      "update",
+                      "CalendarEvent",
+                      {
+                        "description": [
+                          "object/get",
+                          [
+                            "array/first",
+                            "@entity.pending"
+                          ],
+                          "description"
+                        ],
+                        "endsAt": [
+                          "object/get",
+                          [
+                            "array/first",
+                            "@entity.pending"
+                          ],
+                          "end"
+                        ],
+                        "id": [
+                          "object/get",
+                          [
+                            "array/first",
+                            [
+                              "array/filter",
+                              "@payload.data",
+                              [
+                                "fn",
+                                "r",
+                                [
+                                  "=",
+                                  [
+                                    "object/get",
+                                    "@r",
+                                    "externalEventId"
+                                  ],
+                                  "@entity.headId"
+                                ]
+                              ]
+                            ]
+                          ],
+                          "id"
+                        ],
+                        "location": [
+                          "object/get",
+                          [
+                            "array/first",
+                            "@entity.pending"
+                          ],
+                          "location"
+                        ],
+                        "startsAt": [
+                          "object/get",
+                          [
+                            "array/first",
+                            "@entity.pending"
+                          ],
+                          "start"
+                        ],
+                        "status": [
+                          "object/get",
+                          [
+                            "array/first",
+                            "@entity.pending"
+                          ],
+                          "status"
+                        ],
+                        "syncedAt": "@now",
+                        "title": [
+                          "object/get",
+                          [
+                            "array/first",
+                            "@entity.pending"
+                          ],
+                          "summary"
+                        ]
+                      },
+                      {
+                        "emit": {
+                          "failure": "CAL_SYNC_FAILED",
+                          "success": "PULL_STEPPED"
+                        }
+                      }
+                    ]
+                  ]
+                ],
+                "event": "PULL_TARGET_LOADED",
+                "eventId": "evt_01M0M9E89QZS3J82D8V4N7GNTX",
+                "from": "pulling",
+                "to": "pulling"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.pending",
+                    [
+                      "array/drop",
+                      "@entity.pending",
+                      1.0
+                    ]
+                  ],
+                  [
+                    "emit",
+                    "PULL_NEXT",
+                    {
+                      "remaining": [
+                        "array/len",
+                        "@entity.pending"
+                      ]
+                    }
+                  ]
+                ],
+                "event": "PULL_STEPPED",
+                "eventId": "evt_01M0M9E89QR7NR9G2343SA8BPM",
+                "from": "pulling",
+                "to": "pulling"
+              },
+              {
+                "effects": [
+                  [
+                    "fetch",
+                    "CalendarEvent",
+                    {
+                      "emit": {
+                        "failure": "CAL_SYNC_FAILED",
+                        "success": "PULL_TARGET_LOADED"
+                      }
+                    }
+                  ]
+                ],
+                "event": "PULL_NEXT",
+                "eventId": "evt_01M0M9E89QV7Q7Z4KV2FHA4QZC",
+                "from": "pulling",
+                "guard": [
+                  ">",
+                  "@payload.remaining",
+                  0.0
+                ],
+                "to": "pulling"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.lastSyncedAt",
+                    "@now"
+                  ],
+                  [
+                    "emit",
+                    "CAL_SYNCED",
+                    {
+                      "syncedAt": "@entity.lastSyncedAt"
+                    }
+                  ]
+                ],
+                "event": "PULL_NEXT",
+                "eventId": "evt_01M0M9E89QV7Q7Z4KV2FHA4QZC",
+                "from": "pulling",
+                "guard": [
+                  "=",
+                  "@payload.remaining",
+                  0.0
+                ],
+                "to": "idle"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.lastError",
+                    "@payload.error"
+                  ]
+                ],
+                "event": "CAL_SYNC_FAILED",
+                "eventId": "evt_01M0M9E89QMRE2B1QZPM8HPXS5",
+                "from": "pulling",
+                "to": "idle"
+              }
+            ]
+          },
+          "ticks": [
+            {
+              "effects": [
+                [
+                  "fetch",
+                  "@config.targetEntity",
+                  {
+                    "emit": {
+                      "failure": "CAL_SYNC_FAILED",
+                      "success": "PUSH_ROWS_LOADED"
+                    },
+                    "filter": [
+                      "=",
+                      [
+                        "object/get",
+                        "@entity",
+                        "externalEventId"
+                      ],
+                      ""
+                    ]
+                  }
+                ]
+              ],
+              "interval": "*/15 * * * *",
+              "name": "syncCycle"
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "schemaVersion": 1,
+  "version": "1.0.0"
+}