@almadar/std 16.181.0 → 16.183.0

package/behaviors/lolo/infra/atoms/std-calendar-sync.lolo

@@ -0,0 +1,290 @@
+app std-calendar-sync "1.0.0"
+"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."
+type RemoteEvent = { id : string, summary : string, description : string, location : string, start : string, end : string, status : string, updated : string }
+type TargetRow = { id : string, externalEventId : string }
+orbital CalendarSyncOrbital {
+    type CAL_REMOTE_CHANGED = Event { channelId : string, resourceId : string, resourceState : string } "Google watch-channel push notification, delivered by the /api/hooks/google-calendar ingress."
+
+  entity CalendarSyncRun [persistent: calendarSyncState] {
+    id : string!
+    syncToken : string @description "Scratch: Google incremental-sync token from the last listEvents; in-memory per instance — a restart falls back to a full list." @synonyms "sync cursor, next token" = ""
+    lastSyncedAt : number @description "When the last full push+pull cycle completed; 0 = never." @synonyms "last sync time" = 0
+    headId : string @description "Scratch: id of the target row the push loop is currently exporting." @synonyms "cursor, current row" = ""
+    pending : [RemoteEvent] @description "Scratch: remote events remaining in the current pull-upsert loop." @synonyms "pull queue, remaining events" = []
+    lastError : string @description "Last sync failure detail; blank = none." @synonyms "sync error, failure" = ""
+  }
+
+  entity CalendarEvent [persistent: calendarEvents] {
+    id : string!
+    title : string @description "Event title/summary." @synonyms "summary, name, subject" = ""
+    startsAt : string @description "ISO start (dateTime, or YYYY-MM-DD for all-day)." @synonyms "start, begins, from" = ""
+    endsAt : string @description "ISO end (dateTime, or YYYY-MM-DD for all-day)." @synonyms "end, finishes, until" = ""
+    location : string @description "Event location." @synonyms "place, where, venue" = ""
+    description : string @description "Event description/notes." @synonyms "notes, details, body" = ""
+    status : string @description "Remote status (confirmed/tentative/cancelled)." @synonyms "state, confirmation" = ""
+    externalEventId : string @description "Google Calendar event id this row mirrors; the pull-upsert match key." @synonyms "remote id, google id, calendar event id" = ""
+    syncedAt : number @description "When this row last synced with the remote calendar; 0 = never." @synonyms "last sync, synced" = 0
+  }
+
+  trait CalendarSync -> CalendarSyncRun [lifecycle, instance] {
+    initial: idle
+
+    state idle {
+      INIT -> idle
+      SYNC_NOW -> idle when @config.enabled
+        (fetch @config.targetEntity {
+          emit: { failure: CAL_SYNC_FAILED, success: PUSH_ROWS_LOADED }
+          filter: ["=", (object/get @entity externalEventId), ""]
+        })
+      CAL_REMOTE_CHANGED -> idle when @config.enabled
+        (call-service "calendar" "listEvents" {
+          calendarId: @config.calendarId
+          syncToken: @entity.syncToken
+        } { emit: { failure: CAL_SYNC_FAILED, success: CAL_REMOTE_LISTED } })
+      PUSH_ROWS_LOADED -> pushing when (and @config.enabled [">", (array/len ?data), 0])
+        (set @entity.headId (object/get (array/first ?data) id))
+        (call-service "calendar" "createEvent" {
+          calendarId: @config.calendarId
+          summary: (object/get (array/first ?data) @config.titleField)
+          description: (if ["=", @config.descriptionField, ""] "" (object/get (array/first ?data) @config.descriptionField))
+          location: (if ["=", @config.locationField, ""] "" (object/get (array/first ?data) @config.locationField))
+          start: (object/get (array/first ?data) @config.startField)
+          end: (if ["=", @config.endField, ""] "" (object/get (array/first ?data) @config.endField))
+          durationMinutes: (if ["=", @config.durationField, ""] @config.durationMinutes (object/get (array/first ?data) @config.durationField))
+        } { emit: { failure: CAL_SYNC_FAILED, success: CAL_EVENT_CREATED } })
+      PUSH_ROWS_LOADED -> idle when ["=", (array/len ?data), 0]
+        (call-service "calendar" "listEvents" {
+          calendarId: @config.calendarId
+          syncToken: @entity.syncToken
+        } { emit: { failure: CAL_SYNC_FAILED, success: CAL_REMOTE_LISTED } })
+      CAL_REMOTE_LISTED -> pulling when [">", (array/len ?events), 0]
+        (set @entity.pending ?events)
+        (set @entity.syncToken (str/default ?nextSyncToken ""))
+        (fetch CalendarEvent {
+          emit: { failure: CAL_SYNC_FAILED, success: PULL_TARGET_LOADED }
+        })
+      CAL_REMOTE_LISTED -> idle when ["=", (array/len ?events), 0]
+        (set @entity.syncToken (str/default ?nextSyncToken ""))
+        (set @entity.lastSyncedAt @now)
+        (emit CAL_SYNCED { syncedAt: @entity.lastSyncedAt })
+      CAL_SYNC_FAILED -> idle
+        (set @entity.lastError ?error)
+    }
+
+    state pushing {
+      CAL_EVENT_CREATED -> pushing
+        (persist update @config.targetEntity { id: @entity.headId, externalEventId: ?id, syncedAt: @now } {
+          emit: { failure: CAL_SYNC_FAILED, success: PUSH_STEPPED }
+        })
+      PUSH_STEPPED -> pushing
+        (fetch @config.targetEntity {
+          emit: { failure: CAL_SYNC_FAILED, success: PUSH_ROWS_LOADED }
+          filter: ["=", (object/get @entity externalEventId), ""]
+        })
+      PUSH_ROWS_LOADED -> pushing when [">", (array/len ?data), 0]
+        (set @entity.headId (object/get (array/first ?data) id))
+        (call-service "calendar" "createEvent" {
+          calendarId: @config.calendarId
+          summary: (object/get (array/first ?data) @config.titleField)
+          description: (if ["=", @config.descriptionField, ""] "" (object/get (array/first ?data) @config.descriptionField))
+          location: (if ["=", @config.locationField, ""] "" (object/get (array/first ?data) @config.locationField))
+          start: (object/get (array/first ?data) @config.startField)
+          end: (if ["=", @config.endField, ""] "" (object/get (array/first ?data) @config.endField))
+          durationMinutes: (if ["=", @config.durationField, ""] @config.durationMinutes (object/get (array/first ?data) @config.durationField))
+        } { emit: { failure: CAL_SYNC_FAILED, success: CAL_EVENT_CREATED } })
+      PUSH_ROWS_LOADED -> idle when ["=", (array/len ?data), 0]
+        (call-service "calendar" "listEvents" {
+          calendarId: @config.calendarId
+          syncToken: @entity.syncToken
+        } { emit: { failure: CAL_SYNC_FAILED, success: CAL_REMOTE_LISTED } })
+      CAL_SYNC_FAILED -> idle
+        (set @entity.lastError ?error)
+    }
+
+    state pulling {
+      PULL_TARGET_LOADED -> pulling
+        (set @entity.headId (object/get (array/first @entity.pending) id))
+        (if ["=", (array/len (array/filter ?data (fn r ["=", (object/get @r externalEventId), @entity.headId]))), 0] (persist create CalendarEvent {
+          title: (object/get (array/first @entity.pending) summary)
+          startsAt: (object/get (array/first @entity.pending) start)
+          endsAt: (object/get (array/first @entity.pending) end)
+          location: (object/get (array/first @entity.pending) location)
+          description: (object/get (array/first @entity.pending) description)
+          status: (object/get (array/first @entity.pending) status)
+          externalEventId: @entity.headId
+          syncedAt: @now
+        } { emit: { failure: CAL_SYNC_FAILED, success: PULL_STEPPED } }) (persist update CalendarEvent {
+          id: (object/get (array/first (array/filter ?data (fn r ["=", (object/get @r externalEventId), @entity.headId]))) id)
+          title: (object/get (array/first @entity.pending) summary)
+          startsAt: (object/get (array/first @entity.pending) start)
+          endsAt: (object/get (array/first @entity.pending) end)
+          location: (object/get (array/first @entity.pending) location)
+          description: (object/get (array/first @entity.pending) description)
+          status: (object/get (array/first @entity.pending) status)
+          syncedAt: @now
+        } { emit: { failure: CAL_SYNC_FAILED, success: PULL_STEPPED } }))
+      PULL_STEPPED -> pulling
+        (set @entity.pending (array/drop @entity.pending 1))
+        (emit PULL_NEXT {
+          remaining: (array/len @entity.pending)
+        })
+      PULL_NEXT -> pulling when [">", ?remaining, 0]
+        (fetch CalendarEvent {
+          emit: { failure: CAL_SYNC_FAILED, success: PULL_TARGET_LOADED }
+        })
+      PULL_NEXT -> idle when ["=", ?remaining, 0]
+        (set @entity.lastSyncedAt @now)
+        (emit CAL_SYNCED { syncedAt: @entity.lastSyncedAt })
+      CAL_SYNC_FAILED -> idle
+        (set @entity.lastError ?error)
+    }
+
+    emits {
+      CAL_SYNCED -> external {
+        syncedAt : number
+      }
+        @description "A full push+pull cycle completed; wire to std-notify-on-event or a status surface."
+      CAL_SYNC_FAILED {
+        error : string!
+      }
+        @description "A calendar service call / fetch / persist failed — lastError carries the detail and the cycle stops until the next trigger."
+        @tier "secondary"
+      PUSH_ROWS_LOADED {
+        data : [TargetRow]
+      }
+        @description "Target rows with a blank externalEventId marker — the remaining local→remote export queue."
+        @tier "secondary"
+      CAL_EVENT_CREATED {
+        id : string!
+        status : string!
+        htmlLink : string!
+      }
+        @description "calendar.createEvent result, flattened onto the payload by the call-service effect executor."
+        @tier "secondary"
+      PUSH_STEPPED {
+        id : string!
+      }
+        @description "Target row stamped with its new externalEventId; drives the next push pass."
+        @tier "secondary"
+      CAL_REMOTE_LISTED {
+        events : [RemoteEvent]
+        nextSyncToken : string
+      }
+        @description "calendar.listEvents result — the remote change set for the pull-upsert loop."
+        @tier "secondary"
+      PULL_TARGET_LOADED {
+        data : [TargetRow]
+      }
+        @description "CalendarEvent rows loaded for externalEventId matching in the pull-upsert."
+        @tier "secondary"
+      PULL_STEPPED {
+        id : string!
+      }
+        @description "One remote event upserted into the CalendarEvent store; drives the next pull pass."
+        @tier "secondary"
+      PULL_NEXT {
+        remaining : number
+      }
+        @description "Pull loop control: how many remote events remain in the queue."
+        @tier "secondary"
+    }
+
+    listens {
+      SYNC_NOW {
+      }
+      CAL_REMOTE_CHANGED {
+        channelId : string
+        resourceId : string
+        resourceState : string
+      }
+      PUSH_ROWS_LOADED {
+        data : [TargetRow]
+      }
+      CAL_EVENT_CREATED {
+        id : string!
+        status : string!
+        htmlLink : string!
+      }
+      PUSH_STEPPED {
+        id : string!
+      }
+      CAL_REMOTE_LISTED {
+        events : [RemoteEvent]
+        nextSyncToken : string
+      }
+      PULL_TARGET_LOADED {
+        data : [TargetRow]
+      }
+      PULL_STEPPED {
+        id : string!
+      }
+      PULL_NEXT {
+        remaining : number
+      }
+    }
+
+    ticks {
+      syncCycle every "*/15 * * * *"
+        (fetch @config.targetEntity {
+          emit: { failure: CAL_SYNC_FAILED, success: PUSH_ROWS_LOADED }
+          filter: ["=", (object/get @entity externalEventId), ""]
+        })
+
+    }
+
+    config {
+      enabled : boolean = false
+        @label "Sync with Google Calendar"
+        @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)."
+        @synonyms "enable, calendar sync, google calendar, two-way sync, sync events, connect calendar"
+        @tier "infra"
+      targetEntity : entity = CalendarEvent
+        @label "Entity to push"
+        @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."
+        @synonyms "entity to sync, source entity, record type, appointments entity, sessions entity"
+        @tier "internal"
+      calendarId : string = ""
+        @label "Calendar id"
+        @description "Google calendar to sync with; blank = the service's default (GOOGLE_CALENDAR_ID env, else primary)."
+        @synonyms "google calendar id, target calendar"
+        @tier "infra"
+      titleField : string = title
+        @label "Title field"
+        @description "Target-entity field holding the event title."
+        @synonyms "summary field, name field"
+        @tier "internal"
+      startField : string = startsAt
+        @label "Start field"
+        @description "Target-entity field holding the ISO start (dateTime, or YYYY-MM-DD for all-day)."
+        @synonyms "start date field, begins field, scheduledAt field"
+        @tier "internal"
+      endField : string = endsAt
+        @label "End field"
+        @description "Target-entity field holding the ISO end. Blank = derive the end from `durationMinutes` instead (the corpus carries all four event shapes)."
+        @synonyms "end date field, finishes field"
+        @tier "internal"
+      durationMinutes : number = 60
+        @label "Duration (minutes)"
+        @description "Fixed event length used when both `endField` and `durationField` are blank; the calendar service computes the timezone-correct end."
+        @synonyms "length, event duration, minutes"
+        @tier "internal"
+      durationField : string = ""
+        @label "Duration field"
+        @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."
+        @synonyms "minutes field, length field, per-row duration"
+        @tier "internal"
+      locationField : string = ""
+        @label "Location field"
+        @description "Target-entity field holding the location; blank = none."
+        @synonyms "place field, venue field"
+        @tier "internal"
+      descriptionField : string = ""
+        @label "Description field"
+        @description "Target-entity field holding the description/notes; blank = none."
+        @synonyms "notes field, details field"
+        @tier "internal"
+    }
+  }
+
+  page "/calendar-sync" as CalendarSyncPage -> CalendarSync
+}

package/behaviors/lolo/infra/atoms/std-migration-job.lolo

@@ -297,9 +297,9 @@ orbital MigrationJobOrbital {
         @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."
         @synonyms "destination, import into, target type"
         @tier "domain"
-      connectionRef : string = ""
+      connectionRef : secret = ""
         @label "Connection reference"
-        @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.)"
+        @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 `secret` — the config-field type that marks a credential reference; UI password-renders it and traces mask it.)"
         @synonyms "credential key, connection string reference, secret name"
         @tier "internal"
       reviewSlot : slot = modal

package/behaviors/lolo/infra/atoms/std-notification-center.lolo

@@ -0,0 +1,290 @@
+app std-notification-center "1.0.0"
+"std-notification-center — per-user notification preferences, web-push subscriptions, and the digest drain for suppressed notifications. Owns the two owner-scoped stores std-notify-on-event consults at dispatch time: NotificationPreference rows (per event key: mode instant/digest/off, channel override, per-user quiet hours) and PushSubscription rows (captured via the browser/push-subscribe flow — the shared service worker + PushManager subscription, persisted as flat endpoint/p256dh/auth credentials). The DigestDrain trait is the delivery half of every suppression std-notify-on-event records: an hourly cron tick scans NotificationRecord audit rows left undispatched for digest/quiet-hours reasons and at least `minAgeHours` old, delivers each by email (the digest channel), and marks it dispatched — the reminder-scheduler self-driving scan loop verbatim. Compose alongside std-notify-on-event: the listener suppresses and records, this atom captures subscriptions, edits preferences, and drains."
+type NotifRow = { id : string, recipient : string, channel : string, message : string, severity : string, dispatched : boolean, error : string, recordedAt : number }
+type PushCreds = { endpoint : string, p256dh : string, auth : string }
+orbital NotificationCenterOrbital {
+    type PUSH_SUBSCRIBED = Event { result : PushCreds } "browser/push-subscribe resolved — the flat subscription credentials arrive in `result`."
+
+  entity NotificationPreference [persistent: notificationPreferences] {
+    id : string!
+    userId : string @description "Owner of this preference row — rows are meant to be private to their owner. Access predicates need an [identity] roster, so the binding organism (which declares one) owns the @read/@update scoping; the generic atom cannot." @synonyms "user, owner, account" = ""
+    eventType : string @description "Event key this preference applies to (matches a listener's eventKey); blank = all events." @synonyms "event, trigger, subscription, topic" = ""
+    mode : "instant" | "digest" | "off" @description "Delivery mode: instant (default), digest (deferred to the drain cycle), or off (muted)." @synonyms "delivery mode, frequency, cadence, mute, defer" = instant
+    channel : string @description "Channel override for this user (in-app/email/sms/push/webhook); blank = the listener's configured channel." @synonyms "preferred channel, delivery method" = ""
+    quietStartHour : number @description "Per-user quiet-hours start (hour 0-23); equal to quietEndHour = disabled." @synonyms "quiet start, do not disturb from" = 0
+    quietEndHour : number @description "Per-user quiet-hours end (hour 0-23); equal to quietStartHour = disabled." @synonyms "quiet end, do not disturb until" = 0
+  }
+
+  entity PushSubscription [persistent: pushSubscriptions] {
+    id : string!
+    userId : string @description "Owner of this browser push subscription. Owner-scoped access predicates belong to the binding organism's [identity] roster, as with NotificationPreference." @synonyms "user, owner, account" = ""
+    endpoint : string @description "Push service endpoint URL for this subscription." @synonyms "push url, subscription endpoint" = ""
+    p256dh : string @description "Client public key (p256dh) of the subscription." @synonyms "public key" = ""
+    auth : string @description "Auth secret of the subscription." @synonyms "auth secret" = ""
+    createdAt : number @description "When this subscription was captured." @synonyms "subscribed at, created" = 0
+    lastError : string @description "Scratch: last subscribe-flow failure shown to the user; blank = none." @synonyms "subscribe error, failure reason" = ""
+  }
+
+  entity NotificationRecord [persistent: notifications] {
+    id : string!
+    recipient : string @description "The identifier of the entity receiving the notification." @synonyms "user, target, receiver, destination" = ""
+    channel : string @description "The delivery method for the notification (e.g., email, SMS, in-app)." @synonyms "delivery, medium, type" = in-app
+    message : string @description "The content of the notification message." @synonyms "text, content, body" = ""
+    severity : string @description "Indicates the importance or urgency level of the notification." @synonyms "priority, level, importance" = info
+    dispatched : boolean @description "Indicates whether the notification has been successfully sent." @synonyms "sent, delivered, status" = false
+    error : string @description "Suppression reason or delivery failure detail when dispatched is false." @synonyms "error message, failure reason, dispatch error" = ""
+    recordedAt : number @description "Timestamp indicating when the notification record was created." @synonyms "creation time, timestamp, date, when" = 0
+  }
+
+  entity DigestRunView [runtime] {
+    id : string!
+    headId : string @description "Scratch: id of the audit row the drain loop is currently delivering." @synonyms "current id, cursor" = ""
+    headRecipient : string @description "Scratch: recipient of the row being delivered." @synonyms "current recipient" = ""
+    headMessage : string @description "Scratch: message of the row being delivered." @synonyms "current message" = ""
+    drainedCount : number @description "Number of rows delivered in the current drain cycle." @synonyms "delivered count, processed" = 0
+    lastError : string @description "Last drain failure; blank = none." @synonyms "drain error, failure" = ""
+  }
+
+  trait PushSubscriber -> PushSubscription [lifecycle, instance] {
+    initial: idle
+
+    state idle {
+      SUBSCRIBE_PUSH -> idle
+        (browser/push-subscribe { emit: { failure: PUSH_SUBSCRIBE_FAILED, success: PUSH_SUBSCRIBED } })
+      PUSH_SUBSCRIBED -> idle
+        (set @entity.lastError "")
+        (persist create PushSubscription {
+          auth: ?result.auth
+          createdAt: @now
+          endpoint: ?result.endpoint
+          p256dh: ?result.p256dh
+          userId: @user.id
+        } { emit: { failure: PUSH_SAVE_FAILED, success: PUSH_SAVED } })
+      PUSH_SAVED -> idle
+        (notify success "Push notifications enabled on this browser")
+      PUSH_SUBSCRIBE_FAILED -> idle
+        (set @entity.lastError ?error)
+        (notify warning "Could not enable push notifications")
+      PUSH_SAVE_FAILED -> idle
+        (set @entity.lastError ?error)
+        (notify warning "Could not save the push subscription")
+    }
+
+    emits {
+      PUSH_SUBSCRIBED {
+        result : PushCreds
+      }
+        @description "browser/push-subscribe resolved with the flat subscription credentials in `result`"
+        @tier "secondary"
+      PUSH_SUBSCRIBE_FAILED {
+        error : string!
+      }
+        @description "Push API unavailable, permission denied, or the host has no VAPID key"
+        @tier "secondary"
+      PUSH_SAVED {
+        id : string!
+      }
+        @description "Subscription row persisted for the current user"
+        @tier "secondary"
+      PUSH_SAVE_FAILED {
+        error : string!
+      }
+        @description "Persisting the subscription row failed"
+        @tier "secondary"
+    }
+
+    listens {
+      SUBSCRIBE_PUSH {
+      }
+    }
+  }
+
+  trait PreferenceEditor -> NotificationPreference [lifecycle, instance] {
+    initial: idle
+
+    state idle {
+      SAVE_PREFERENCE -> idle
+        (persist create NotificationPreference {
+          channel: ?channel
+          eventType: ?eventType
+          mode: ?mode
+          quietEndHour: ?quietEndHour
+          quietStartHour: ?quietStartHour
+          userId: @user.id
+        } { emit: { failure: PREFERENCE_SAVE_FAILED, success: PREFERENCE_SAVED } })
+      UPDATE_PREFERENCE -> idle
+        (persist update NotificationPreference {
+          id: ?id
+          channel: ?channel
+          eventType: ?eventType
+          mode: ?mode
+          quietEndHour: ?quietEndHour
+          quietStartHour: ?quietStartHour
+        } { emit: { failure: PREFERENCE_SAVE_FAILED, success: PREFERENCE_SAVED } })
+      DELETE_PREFERENCE -> idle
+        (persist delete NotificationPreference ?id { emit: { failure: PREFERENCE_SAVE_FAILED, success: PREFERENCE_DELETED } })
+      PREFERENCE_SAVED -> idle
+        (notify success "Notification preference saved")
+      PREFERENCE_DELETED -> idle
+        (notify info "Notification preference removed")
+      PREFERENCE_SAVE_FAILED -> idle
+        (notify warning "Could not save the notification preference")
+    }
+
+    emits {
+      PREFERENCE_SAVED {
+        id : string!
+      }
+        @description "Preference row persisted"
+        @tier "secondary"
+      PREFERENCE_DELETED {
+        id : string!
+      }
+        @description "Preference row removed"
+        @tier "secondary"
+      PREFERENCE_SAVE_FAILED {
+        error : string!
+      }
+        @description "Preference persist failed"
+        @tier "secondary"
+    }
+
+    listens {
+      SAVE_PREFERENCE {
+        eventType : string
+        mode : string
+        channel : string
+        quietStartHour : number
+        quietEndHour : number
+      }
+      UPDATE_PREFERENCE {
+        id : string
+        eventType : string
+        mode : string
+        channel : string
+        quietStartHour : number
+        quietEndHour : number
+      }
+      DELETE_PREFERENCE {
+        id : string
+      }
+    }
+  }
+
+  trait DigestDrain -> DigestRunView [lifecycle, instance] {
+    initial: idle
+
+    state idle {
+      DIGEST_ROWS_LOADED -> draining when (and @config.digestEnabled [">", (array/len ?data), 0])
+        (set @entity.headId (object/get (array/first ?data) id))
+        (set @entity.headRecipient (object/get (array/first ?data) recipient))
+        (set @entity.headMessage (object/get (array/first ?data) message))
+        (call-service "email" "send" {
+          body: @entity.headMessage
+          from: ""
+          subject: @config.digestSubject
+          to: @entity.headRecipient
+        } { emit: { failure: DIGEST_FAILED, success: DIGEST_ITEM_SENT } })
+      DIGEST_ROWS_LOADED -> idle when ["=", (array/len ?data), 0]
+      DIGEST_FAILED -> idle
+        (set @entity.lastError ?error)
+    }
+
+    state draining {
+      DIGEST_ITEM_SENT -> draining
+        (set @entity.drainedCount ["+", @entity.drainedCount, 1])
+        (persist update NotificationRecord { id: @entity.headId, dispatched: true } {
+          emit: { failure: DIGEST_FAILED, success: DIGEST_STEPPED }
+        })
+      DIGEST_STEPPED -> draining
+        (fetch NotificationRecord {
+          emit: { failure: DIGEST_FAILED, success: DIGEST_ROWS_LOADED }
+          filter: (and ["=", (object/get @entity dispatched), false] (or ["=", (object/get @entity error), "digest-deferred"] ["=", (object/get @entity error), "quiet-hours"]) ["<", (object/get @entity recordedAt), ["-", @now, ["*", @config.minAgeHours, 3600000]]])
+        })
+      DIGEST_ROWS_LOADED -> draining when [">", (array/len ?data), 0]
+        (set @entity.headId (object/get (array/first ?data) id))
+        (set @entity.headRecipient (object/get (array/first ?data) recipient))
+        (set @entity.headMessage (object/get (array/first ?data) message))
+        (call-service "email" "send" {
+          body: @entity.headMessage
+          from: ""
+          subject: @config.digestSubject
+          to: @entity.headRecipient
+        } { emit: { failure: DIGEST_FAILED, success: DIGEST_ITEM_SENT } })
+      DIGEST_ROWS_LOADED -> idle when ["=", (array/len ?data), 0]
+      DIGEST_FAILED -> idle
+        (set @entity.lastError ?error)
+    }
+
+    emits {
+      DIGEST_ROWS_LOADED {
+        data : [NotifRow]
+      }
+        @description "Undispatched digest/quiet-hours audit rows past minAgeHours, oldest batch first"
+        @tier "secondary"
+      DIGEST_ITEM_SENT {
+        id : string!
+        status : string!
+      }
+        @description "email.send result for the current digest row"
+        @tier "secondary"
+      DIGEST_STEPPED {
+        id : string!
+      }
+        @description "Current row marked dispatched; drives the next loop pass"
+        @tier "secondary"
+      DIGEST_FAILED {
+        error : string!
+      }
+        @description "Digest scan / delivery / persist failed — the cycle stops until the next tick"
+        @tier "secondary"
+    }
+
+    listens {
+      DIGEST_ROWS_LOADED {
+        data : [NotifRow]
+      }
+      DIGEST_ITEM_SENT {
+        id : string!
+        status : string!
+      }
+      DIGEST_STEPPED {
+        id : string!
+      }
+      DIGEST_FAILED {
+        error : string!
+      }
+    }
+
+    ticks {
+      digestCycle every "0 * * * *"
+        (fetch NotificationRecord {
+          emit: { failure: DIGEST_FAILED, success: DIGEST_ROWS_LOADED }
+          filter: (and ["=", (object/get @entity dispatched), false] (or ["=", (object/get @entity error), "digest-deferred"] ["=", (object/get @entity error), "quiet-hours"]) ["<", (object/get @entity recordedAt), ["-", @now, ["*", @config.minAgeHours, 3600000]]])
+        })
+
+    }
+
+    config {
+      digestEnabled : boolean = false
+        @label "Deliver digests"
+        @description "Drain suppressed notifications (digest-deferred and quiet-hours audit rows) on the hourly cycle. Off by default."
+        @synonyms "enable digest, digest mode, batch notifications, daily summary, drain suppressed"
+        @tier "infra"
+      digestSubject : string = "Notification digest"
+        @label "Digest email subject"
+        @description "Subject line for drained digest deliveries."
+        @synonyms "digest title, summary subject, email subject"
+        @tier "presentation"
+      minAgeHours : number = 1
+        @label "Minimum age (hours)"
+        @description "Only drain audit rows at least this many hours old, so quiet-hours suppressions are not redelivered inside their window."
+        @synonyms "delay, drain delay, hold for, batch window"
+        @tier "infra"
+    }
+  }
+
+  page "/notifications/preferences" as NotificationPreferencesPage -> PreferenceEditor
+  page "/notifications/subscribe" as PushSubscribePage -> PushSubscriber
+  page "/notifications/digest" as NotificationDigestPage -> DigestDrain
+}