@almadar/std 16.21.2 → 16.21.4

package/dist/registry/infra/atoms/std-notify-on-event.orb

@@ -1,6 +1,6 @@
 {
   "name": "std-notify-on-event",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "std-notify-on-event — cross-orbital wiring atom. Subscribes to events from another orbital (e.g. CheckoutOrbital emits OrderPlaced, OrderRecordOrbital reacts via this atom) and dispatches a notification. Use when one orbital needs to react to or be notified about events that happen in another orbital — the wiring goes through this atom's `EventOccurred` listener which the molecule renames via traitOverrides.events to the upstream event name. Resolves recipient from `recipients` (first entry; multi-recipient fan-out is a future extension) or falls back to `@user.id`. Skips dispatch when the recipient is in `suppressionList`. Emits in-app `notify` when `notifyChannel` is `\"in-app\"`, or persists a `NotificationRecord` row for out-of-band delivery when channel is `\"email\"` or `\"sms\"`.",
   "orbitals": [
     {
@@ -103,6 +103,10 @@
                   {
                     "name": "data",
                     "type": "object"
+                  },
+                  {
+                    "name": "status",
+                    "type": "string"
                   }
                 ]
               },
@@ -134,6 +138,19 @@
                 "from": "idle",
                 "to": "idle",
                 "event": "EventOccurred",
+                "guard": [
+                  "or",
+                  [
+                    "=",
+                    "@config.triggerStatus",
+                    ""
+                  ],
+                  [
+                    "=",
+                    "@payload.status",
+                    "@config.triggerStatus"
+                  ]
+                ],
                 "effects": [
                   [
                     "set",
@@ -222,12 +239,12 @@
                         "create",
                         "NotificationRecord",
                         {
-                          "dispatched": false,
                           "channel": "@config.notifyChannel",
-                          "recordedAt": 0.0,
                           "recipient": "@entity.recipient",
-                          "message": "@config.template",
-                          "severity": "@config.severity"
+                          "severity": "@config.severity",
+                          "recordedAt": 0.0,
+                          "dispatched": false,
+                          "message": "@config.template"
                         }
                       ]
                     ]
@@ -236,10 +253,10 @@
                     "emit",
                     "NotificationDispatched",
                     {
+                      "recipient": "@entity.recipient",
                       "channel": "@config.notifyChannel",
                       "severity": "@config.severity",
-                      "message": "@config.template",
-                      "recipient": "@entity.recipient"
+                      "message": "@config.template"
                     }
                   ]
                 ]
@@ -247,36 +264,65 @@
             ]
           },
           "config": {
-            "suppressionList": {
+            "triggerStatus": {
+              "type": "string",
+              "default": "",
+              "label": "Trigger status",
+              "description": "When set, dispatch only when the upstream event's `status` field equals this value (e.g. fire only when a record becomes 'approved'). Empty = fire on every subscribed event.",
+              "synonyms": "on status, when status, status filter, only when, fire on, react on status",
+              "tier": "policy"
+            },
+            "quietHours": {
+              "type": "QuietHoursSpec",
+              "default": {
+                "start": "",
+                "end": ""
+              },
+              "label": "Quiet hours",
+              "description": "Local-time window during which dispatch is suppressed. Both start and end required to activate. WIRING DEFERRED: needs @now-aware time comparison primitive (gap — docs/Almadar_Std_Factories.md).",
+              "tier": "policy",
+              "properties": {
+                "start": {
+                  "name": "start",
+                  "type": "string",
+                  "required": false
+                },
+                "end": {
+                  "name": "end",
+                  "type": "string",
+                  "required": false
+                }
+              }
+            },
+            "frequencyCapPerWeek": {
+              "type": "number",
+              "default": 0.0,
+              "label": "Frequency cap (per week)",
+              "description": "Max sends per (channel, recipient) per rolling 7-day window. 0 = uncapped. WIRING DEFERRED: needs stateful history query (gap — docs/Almadar_Std_Factories.md).",
+              "tier": "policy"
+            },
+            "recipients": {
               "type": "[string]",
               "default": [],
-              "label": "Suppression list",
-              "description": "Recipient ids/addresses to skip (e.g. unsubscribed users). Suppression check runs before dispatch.",
-              "synonyms": "block list, unsubscribed, opt-out list",
+              "label": "Recipients",
+              "description": "Recipient ids/addresses. v1.1 uses the first entry; multi-recipient fan-out lands in v1.2 (gap). When empty, falls back to the authenticated user.",
+              "synonyms": "targets, addressees, notify to",
               "tier": "policy",
               "items": {
                 "type": "string"
               }
             },
-            "listensFor": {
+            "suppressionList": {
               "type": "[string]",
               "default": [],
-              "label": "Trigger events",
-              "description": "Event names that should fire a notification. Set this to the upstream event name (e.g. OrderPlaced, CheckoutCompleted) so this atom listens for events from the orbital that emits them. The orbital owning this trait reacts whenever the named event fires anywhere in the schema.",
-              "synonyms": "subscribe to event, listen for event, react to event, watch for, wire upstream event, observe event from another orbital, cross-orbital subscription, on-event trigger",
-              "tier": "internal",
+              "label": "Suppression list",
+              "description": "Recipient ids/addresses to skip (e.g. unsubscribed users). Suppression check runs before dispatch.",
+              "synonyms": "block list, unsubscribed, opt-out list",
+              "tier": "policy",
               "items": {
                 "type": "string"
               }
             },
-            "template": {
-              "type": "string",
-              "default": "",
-              "label": "Message template",
-              "description": "Text shown to the recipient; supports payload interpolation",
-              "synonyms": "notification text, message body, alert text",
-              "tier": "presentation"
-            },
             "notifyChannel": {
               "type": "string",
               "default": "in-app",
@@ -285,46 +331,25 @@
               "synonyms": "delivery method, notification channel, send via, dispatch through",
               "tier": "policy"
             },
-            "frequencyCapPerWeek": {
-              "type": "number",
-              "default": 0.0,
-              "label": "Frequency cap (per week)",
-              "description": "Max sends per (channel, recipient) per rolling 7-day window. 0 = uncapped. WIRING DEFERRED: needs stateful history query (gap — docs/Almadar_Std_Factories.md).",
-              "tier": "policy"
+            "template": {
+              "type": "string",
+              "default": "",
+              "label": "Message template",
+              "description": "Text shown to the recipient; supports payload interpolation",
+              "synonyms": "notification text, message body, alert text",
+              "tier": "presentation"
             },
-            "recipients": {
+            "listensFor": {
               "type": "[string]",
               "default": [],
-              "label": "Recipients",
-              "description": "Recipient ids/addresses. v1.1 uses the first entry; multi-recipient fan-out lands in v1.2 (gap). When empty, falls back to the authenticated user.",
-              "synonyms": "targets, addressees, notify to",
-              "tier": "policy",
+              "label": "Trigger events",
+              "description": "Event names that should fire a notification. Set this to the upstream event name (e.g. OrderPlaced, CheckoutCompleted) so this atom listens for events from the orbital that emits them. The orbital owning this trait reacts whenever the named event fires anywhere in the schema.",
+              "synonyms": "subscribe to event, listen for event, react to event, watch for, wire upstream event, observe event from another orbital, cross-orbital subscription, on-event trigger",
+              "tier": "internal",
               "items": {
                 "type": "string"
               }
             },
-            "quietHours": {
-              "type": "QuietHoursSpec",
-              "default": {
-                "start": "",
-                "end": ""
-              },
-              "label": "Quiet hours",
-              "description": "Local-time window during which dispatch is suppressed. Both start and end required to activate. WIRING DEFERRED: needs @now-aware time comparison primitive (gap — docs/Almadar_Std_Factories.md).",
-              "tier": "policy",
-              "properties": {
-                "start": {
-                  "name": "start",
-                  "type": "string",
-                  "required": false
-                },
-                "end": {
-                  "name": "end",
-                  "type": "string",
-                  "required": false
-                }
-              }
-            },
             "severity": {
               "type": "string",
               "default": "info",

package/dist/registry/infra/atoms/std-status-lifecycle.orb

@@ -0,0 +1,306 @@
+{
+  "name": "std-status-lifecycle",
+  "version": "0.1.0",
+  "description": "Infra substrate: data-driven entity status lifecycle. The statuses and the allowed transitions are config data over a fixed single-state topology, so a host organism can expand or collapse its lifecycle without forking. Compose onto an entity, rename the ChangeStatusRequested listen to the host's status-change action, and supply `states` + `transitions`. A requested move is validated against the `transitions` table (illegal moves are rejected), then the new value is written to `statusField` on the target entity and StatusChanged is emitted. Surfaces nothing — the host renders the badge and buttons.",
+  "orbitals": [
+    {
+      "name": "StatusLifecycleOrbital",
+      "entity": {
+        "name": "StatusRecord",
+        "collection": "status_records",
+        "persistence": "persistent",
+        "fields": [
+          {
+            "name": "id",
+            "type": "string",
+            "required": true
+          },
+          {
+            "name": "status",
+            "type": "string",
+            "default": "",
+            "description": "Current lifecycle status of the record.",
+            "synonyms": "state, stage, phase"
+          }
+        ]
+      },
+      "traits": [
+        {
+          "name": "StatusMachine",
+          "entityRebindable": true,
+          "entityContract": {
+            "requires": [],
+            "provides": []
+          },
+          "category": "lifecycle",
+          "linkedEntity": "StatusRecord",
+          "emits": [
+            {
+              "event": "StatusChanged",
+              "scope": "external",
+              "payloadSchema": [
+                {
+                  "name": "entityId",
+                  "type": "string"
+                },
+                {
+                  "name": "status",
+                  "type": "string"
+                }
+              ]
+            },
+            {
+              "event": "StatusChangeFailed",
+              "payloadSchema": [
+                {
+                  "name": "error",
+                  "type": "string"
+                },
+                {
+                  "name": "code",
+                  "type": "string"
+                }
+              ]
+            }
+          ],
+          "stateMachine": {
+            "states": [
+              {
+                "name": "idle",
+                "isInitial": true
+              }
+            ],
+            "events": [
+              {
+                "key": "ChangeStatusRequested",
+                "name": "Change status requested",
+                "payloadSchema": [
+                  {
+                    "name": "id",
+                    "type": "string"
+                  },
+                  {
+                    "name": "from",
+                    "type": "string"
+                  },
+                  {
+                    "name": "to",
+                    "type": "string"
+                  }
+                ]
+              },
+              {
+                "key": "StatusChangeFailed",
+                "name": "Status change failed",
+                "payloadSchema": [
+                  {
+                    "name": "error",
+                    "type": "string"
+                  },
+                  {
+                    "name": "code",
+                    "type": "string"
+                  }
+                ]
+              },
+              {
+                "key": "StatusChanged",
+                "name": "Status changed",
+                "payloadSchema": [
+                  {
+                    "name": "entityId",
+                    "type": "string"
+                  },
+                  {
+                    "name": "status",
+                    "type": "string"
+                  }
+                ]
+              }
+            ],
+            "transitions": [
+              {
+                "from": "idle",
+                "to": "idle",
+                "event": "ChangeStatusRequested",
+                "guard": [
+                  "and",
+                  "@config.enabled",
+                  [
+                    "array/some",
+                    "@config.transitions",
+                    [
+                      "fn",
+                      "t",
+                      [
+                        "and",
+                        [
+                          "=",
+                          [
+                            "object/get",
+                            "@t",
+                            "from"
+                          ],
+                          "@payload.from"
+                        ],
+                        [
+                          "=",
+                          [
+                            "object/get",
+                            "@t",
+                            "to"
+                          ],
+                          "@payload.to"
+                        ]
+                      ]
+                    ]
+                  ]
+                ],
+                "effects": [
+                  [
+                    "persist",
+                    "update",
+                    "@config.targetEntity",
+                    [
+                      "object/set",
+                      {
+                        "id": "@payload.id"
+                      },
+                      "@config.statusField",
+                      "@payload.to"
+                    ],
+                    {
+                      "emit": {
+                        "failure": "StatusChangeFailed",
+                        "success": "StatusChanged"
+                      }
+                    }
+                  ],
+                  [
+                    "emit",
+                    "StatusChanged",
+                    {
+                      "status": "@payload.to",
+                      "entityId": "@payload.id"
+                    }
+                  ]
+                ]
+              },
+              {
+                "from": "idle",
+                "to": "idle",
+                "event": "StatusChangeFailed"
+              }
+            ]
+          },
+          "config": {
+            "enabled": {
+              "type": "boolean",
+              "default": false,
+              "label": "Enforce status lifecycle",
+              "description": "Validate and apply status transitions against the configured table. Off by default.",
+              "synonyms": "lifecycle, statuses, states, stages, workflow, status transitions, enforce, enable, apply",
+              "tier": "infra"
+            },
+            "statusField": {
+              "type": "string",
+              "default": "status",
+              "label": "Status field",
+              "description": "Which entity field this lifecycle drives. Defaults to 'status'; set it to bind any field (e.g. 'state', 'stage', 'phase').",
+              "synonyms": "state field, stage field, status column, lifecycle field",
+              "tier": "domain"
+            },
+            "transitions": {
+              "type": "[TransitionSpec]",
+              "default": [
+                {
+                  "to": "active",
+                  "from": "draft",
+                  "event": "ACTIVATE",
+                  "label": "Activate"
+                },
+                {
+                  "from": "active",
+                  "label": "Archive",
+                  "event": "ARCHIVE",
+                  "to": "archived"
+                }
+              ],
+              "label": "Allowed transitions",
+              "description": "The legal moves: each row is { from, to, event, label }. A requested move is applied only if it matches a row.",
+              "synonyms": "edges, allowed moves, status flow, workflow transitions",
+              "tier": "domain",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "event": {
+                    "name": "event",
+                    "type": "string",
+                    "required": false
+                  },
+                  "label": {
+                    "name": "label",
+                    "type": "string",
+                    "required": false
+                  },
+                  "to": {
+                    "name": "to",
+                    "type": "string",
+                    "required": true
+                  },
+                  "from": {
+                    "name": "from",
+                    "type": "string",
+                    "required": true
+                  }
+                }
+              }
+            },
+            "states": {
+              "type": "[string]",
+              "default": [
+                "draft",
+                "active",
+                "archived"
+              ],
+              "label": "Statuses",
+              "description": "The closed set of statuses a record can hold.",
+              "synonyms": "states, stages, phases, statuses, lifecycle, workflow steps",
+              "tier": "domain",
+              "items": {
+                "type": "string"
+              }
+            },
+            "targetEntity": {
+              "type": "string",
+              "default": "StatusRecord",
+              "label": "Target entity",
+              "description": "Entity name whose status field this lifecycle drives (e.g. 'Contract'). Defaults to the atom's own record so the standalone validates; rebind per composition.",
+              "tier": "internal"
+            },
+            "initialStatus": {
+              "type": "string",
+              "default": "draft",
+              "label": "Initial status",
+              "description": "The status a new record starts in.",
+              "synonyms": "starting state, default status, first stage",
+              "tier": "domain"
+            }
+          },
+          "scope": "instance"
+        }
+      ],
+      "pages": [
+        {
+          "name": "StatusLifecyclePage",
+          "path": "/status-lifecycle",
+          "traits": [
+            {
+              "ref": "StatusMachine"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/std",
-  "version": "16.21.2",
+  "version": "16.21.4",
   "description": "Standard library operators for Almadar (math, string, array, etc.)",
   "type": "module",
   "main": "./dist/index.js",