@flowdular/sdk 0.2.4 → 0.3.1

package/modules/notifications/spec/module.yaml

@@ -0,0 +1,718 @@
+schemaVersion: 2
+id: notifications.core
+specVersion: 0.2.8
+status: approved
+name: Notifications Core
+description: Delivers what a person and a customer system need to hear about, as an in-app inbox per member and signed outbound webhooks per workspace with a delivery ledger, bounded retry and a dead letter an administrator can inspect and replay.
+profile: full
+capabilities:
+  - api
+  - database
+  - client
+  - translations
+  - cli
+dependencies:
+  - id: system.core
+    range: ^0.7.0
+  - id: auth.core
+    range: ^0.13.0
+tenancy: required
+locales:
+  - en
+  - pl
+invariants:
+  - Persistence runs on the shared asynchronous database contract with explicit PostgreSQL SQL; every tenant table enables and forces row-level security with USING and WITH CHECK policies bound to the transaction-local tenant id, and the runtime role holds neither SUPERUSER nor BYPASSRLS.
+  - An inbox item is owned by exactly one tenant and addressed to exactly one member account; a member reads, marks and archives only items addressed to their own account, and the tenant id and the recipient account id come from the authenticated principal, never from request input.
+  - Other modules create inbox items and webhook events only through the public capability notifications.publish.v1 registered by this module; a caller that finds the capability absent continues without notifying, and this module never reads another module's database.
+  - An outbound webhook subscription is created, changed, paused, resumed, rotated and deleted only by a principal holding notifications.webhooks.manage; every mutation checks CSRF first, and members holding only notifications.webhooks.read see subscriptions without secrets.
+  - The signing secret is generated by the server, stored encrypted with the module key held outside the database and rotatable through the platform keyring, and returned in full only at creation and at rotation; no read path ever returns it again.
+  - Every outbound request is signed the way inbound automations triggers are verified, HMAC-SHA256 over a versioned string of timestamp and body, sent in x-flowdular-signature with x-flowdular-timestamp, so a customer implements one scheme in both directions.
+  - A subscription URL must be https, must not resolve to a loopback, link-local, private or reserved address at save time and again at every delivery, is never followed through a redirect, receives a 10 second timeout and a 64 KB response cap, and when the platform allowlist setting is non-empty the host must be on it.
+  - A delivery opens its socket over node:https to one of the addresses the delivery-time check accepted, pinned to them for that one request on an agent created and destroyed with it, and the https scheme is refused again immediately before the socket; nothing between the check and the connection resolves the host name a second time, so a name answering publicly while the check runs and privately a moment later is unreachable.
+  - A member switches e-mail delivery on for their own account and for the whole workspace; it is off until they do, and it only decides whether an inbox item the member already receives is also sent to the address auth.core holds for them, so a kind they disabled is still not sent. The e-mail channel shares the queue, the claim, the retry budget, the backoff and the dead letter with webhooks; a dead-lettered message writes no inbox item, because that item would be mailed, fail and dead-letter again under a new source reference.
+  - An e-mail attempt stores the channel and the addressed member account and nothing else about the message; the address is read from auth.core and the title and body from the member's own inbox item at send time, so a changed address is honoured by the next attempt and no copy of either lives in the queue.
+  - Every message leaves through the platform mail port on the server context; this module never selects a transport, and a deployment that composed none records the attempt as refused instead of dropping it.
+  - A delivery attempt stores the outcome, the response status, the error class, the payload SHA-256 and the payload size; it never stores the payload, the signature or the secret, and the payload is regenerated from the delivery row for a replay.
+  - The webhook payload is a JSON object with version, event kind, tenant id, subscription id, source module, source reference, title and occurredAt; a customer fetches further details from the source module by that reference.
+  - The module signing key is rotated through the platform keyring with a module CLI command that re-seals stored secrets in bounded batches, idempotently, and never prints a secret.
+  - Delivery runs in a module-owned queue table drained by the platform job runner, which owns the pass, its bound, the isolation of one attempt from the next and the drain on stop and sends at most four attempts at a time, where the cross-tenant queue read runs on the read-only background role over the routing columns alone, and every attempt is read again, claimed and written under the tenant the row named before any request leaves; retention sweeps on a runner of its own rather than as a tail of every delivery pass.
+  - A failed delivery is retried with exponential backoff from one minute up to the tenant's maximum, at most the tenant's configured number of attempts, after which the delivery moves to dead letter and an inbox item of kind webhook-dead-letter is created for every member holding notifications.deliveries.read; a manual replay starts a fresh attempt sequence and never resets the ledger.
+  - Delivery attempts older than the tenant retention window are deleted by the poll loop in bounded batches; a member archives an inbox item and never deletes one, and an item leaves only when the workspace retention period of notifications.core.inbox passes.
+  - The module declares notifications.core.inbox (365 days by default) and notifications.core.deliveries (30 days by default, the retentionDays setting the poll loop already enforces) to the platform data class registry while it composes; both are exportable, both sweep in bounded batches inside this module's own tenant-scoped transaction, and preferences and webhook subscriptions are declared by neither because they are workspace configuration rather than history. The delivery sweep runs the same statement as the poll loop, so a queued or in-flight attempt is never removed by retention.
+  - A duplicate subscription name inside a tenant returns a stable conflict and changes nothing; input beyond the declared bounds returns 400 before any write.
+  - Notification events published for a source record are idempotent on the source reference, so publishing the same source reference and kind twice creates one inbox item per recipient and one webhook event per subscription.
+permissions:
+  - id: notifications.inbox.read
+    description: Read the inbox items addressed to the signed-in member in the active tenant.
+  - id: notifications.inbox.manage
+    description: Mark as read and archive the member's own inbox items in the active tenant.
+  - id: notifications.webhooks.read
+    description: Read outbound webhook subscriptions of the active tenant without their secrets.
+  - id: notifications.webhooks.manage
+    description: Create, change, pause, resume, rotate and delete outbound webhook subscriptions in the active tenant.
+  - id: notifications.deliveries.read
+    description: Read delivery attempts and the dead letter of the active tenant and replay a dead-lettered delivery.
+dataOwnership:
+  - notifications.core owns inbox items, member notification preferences, webhook subscriptions, the encrypted signing secrets, the delivery queue and the delivery attempt ledger.
+  - auth.core owns the e-mail address a message is sent to; this module reads it through the auth public surface while it sends and stores no copy.
+  - agents.core and workflows.core own the run records that produce notifications; they call notifications.publish.v1 with a source reference and never write inbox or delivery rows themselves.
+  - auth.core owns the member accounts a notification is addressed to; this module stores the account id and resolves display names through the auth public surface at read time.
+entities:
+  - id: inbox
+    name: Inbox item
+    description: One notification addressed to one member of the tenant.
+    fields:
+      - id: recipientAccountId
+        type: string
+        required: true
+        maxLength: 128
+        description: The member account the item is addressed to; taken from the recipient list of the published event, never from a request.
+      - id: kind
+        type: enum
+        required: true
+        values:
+          - agent-run-completed
+          - agent-run-failed
+          - workflow-run-completed
+          - workflow-run-failed
+          - webhook-dead-letter
+          - approval-requested
+          - approval-decided
+          - meter-threshold
+      - id: title
+        type: string
+        required: true
+        maxLength: 200
+      - id: body
+        type: text
+        required: false
+        maxLength: 4000
+      - id: sourceModule
+        type: string
+        required: true
+        maxLength: 64
+        description: The module id that published the event.
+      - id: sourceRef
+        type: string
+        required: true
+        maxLength: 200
+        description: The publisher's stable reference to the record, for example the run id; unique with kind and recipient inside a tenant.
+      - id: status
+        type: enum
+        required: true
+        values:
+          - unread
+          - read
+          - archived
+      - id: readAt
+        type: datetime
+        required: false
+    states:
+      field: status
+      values:
+        - unread
+        - read
+        - archived
+      transitions:
+        - from: unread
+          to: read
+          permission: notifications.inbox.manage
+        - from: read
+          to: unread
+          permission: notifications.inbox.manage
+        - from: unread
+          to: archived
+          permission: notifications.inbox.manage
+        - from: read
+          to: archived
+          permission: notifications.inbox.manage
+  - id: preference
+    name: Notification preference
+    description: Whether a member receives inbox items of one kind; absent means enabled.
+    fields:
+      - id: recipientAccountId
+        type: string
+        required: true
+        maxLength: 128
+      - id: kind
+        type: enum
+        required: true
+        values:
+          - agent-run-completed
+          - agent-run-failed
+          - workflow-run-completed
+          - workflow-run-failed
+          - webhook-dead-letter
+          - approval-requested
+          - approval-decided
+          - meter-threshold
+      - id: enabled
+        type: boolean
+        required: true
+  - id: member-preference
+    name: Member notification settings
+    description: The switches a member holds for the whole workspace rather than for one kind; absent means the defaults.
+    fields:
+      - id: recipientAccountId
+        type: string
+        required: true
+        maxLength: 128
+      - id: emailDelivery
+        type: boolean
+        required: true
+        description: Also send every inbox item this member receives to the address auth.core holds for them; off by default.
+  - id: webhook-subscription
+    name: Webhook subscription
+    description: A customer endpoint that receives signed events of the selected kinds.
+    fields:
+      - id: name
+        type: string
+        required: true
+        unique: tenant
+        maxLength: 120
+      - id: url
+        type: string
+        required: true
+        maxLength: 2048
+        description: https only; validated against the egress policy at save time and at every delivery.
+      - id: events
+        type: json
+        required: true
+        description: Array of event kinds the endpoint subscribes to, drawn from the inbox kinds.
+      - id: secretFingerprint
+        type: string
+        required: true
+        maxLength: 32
+        description: Truncated SHA-256 of the current signing secret, shown to administrators so a rotation is verifiable without revealing the secret.
+      - id: status
+        type: enum
+        required: true
+        values:
+          - active
+          - paused
+          - disabled
+      - id: lastDeliveryAt
+        type: datetime
+        required: false
+        description: Completion time of the most recent attempt, successful or not; the deliveries screen shows the outcome.
+      - id: description
+        type: text
+        required: false
+        maxLength: 1000
+    states:
+      field: status
+      values:
+        - active
+        - paused
+        - disabled
+      transitions:
+        - from: active
+          to: paused
+          permission: notifications.webhooks.manage
+        - from: paused
+          to: active
+          permission: notifications.webhooks.manage
+        - from: active
+          to: disabled
+          permission: notifications.webhooks.manage
+        - from: paused
+          to: disabled
+          permission: notifications.webhooks.manage
+        - from: disabled
+          to: active
+          permission: notifications.webhooks.manage
+  - id: delivery
+    name: Delivery attempt
+    description: One attempt to deliver one event to one subscription or one member, kept for the retention window.
+    fields:
+      - id: channel
+        type: enum
+        required: true
+        values:
+          - webhook
+          - email
+        description: Where the attempt is addressed; a webhook names a subscription and an e-mail names a member.
+      - id: subscription
+        type: reference
+        required: false
+        reference: webhook-subscription
+      - id: recipientAccountId
+        type: string
+        required: false
+        maxLength: 128
+        description: The member an e-mail attempt is addressed to; absent on a webhook attempt.
+      - id: kind
+        type: enum
+        required: true
+        values:
+          - agent-run-completed
+          - agent-run-failed
+          - workflow-run-completed
+          - workflow-run-failed
+          - webhook-dead-letter
+          - approval-requested
+          - approval-decided
+          - meter-threshold
+      - id: sourceModule
+        type: string
+        required: true
+        maxLength: 64
+      - id: sourceRef
+        type: string
+        required: true
+        maxLength: 200
+      - id: title
+        type: string
+        required: true
+        maxLength: 200
+        description: The published title, carried in the payload so a customer system can show it without a second call.
+      - id: occurredAt
+        type: datetime
+        required: true
+        description: When the event was published; stable across retries and replays so the payload digest stays comparable.
+      - id: sequence
+        type: integer
+        required: true
+        description: The attempt run, 1 for the original publication and one higher for every replay; with the attempt number it makes the ledger row unique.
+      - id: attemptNumber
+        type: integer
+        required: true
+      - id: status
+        type: enum
+        required: true
+        values:
+          - pending
+          - succeeded
+          - failed
+          - dead-letter
+      - id: scheduledFor
+        type: datetime
+        required: true
+      - id: completedAt
+        type: datetime
+        required: false
+      - id: responseStatus
+        type: integer
+        required: false
+      - id: errorClass
+        type: string
+        required: false
+        maxLength: 64
+        description: A stable class such as timeout, dns, egress-refused, response-5xx, response-4xx; never the response body.
+      - id: payloadDigest
+        type: string
+        required: true
+        maxLength: 64
+      - id: payloadBytes
+        type: integer
+        required: true
+    states:
+      field: status
+      values:
+        - pending
+        - succeeded
+        - failed
+        - dead-letter
+      transitions:
+        - from: pending
+          to: succeeded
+        - from: pending
+          to: failed
+        - from: failed
+          to: pending
+        - from: failed
+          to: dead-letter
+        - from: dead-letter
+          to: pending
+          permission: notifications.deliveries.read
+screens:
+  - id: inbox
+    kind: list
+    entity: inbox
+    title: Inbox
+    columns:
+      - status
+      - kind
+      - title
+      - sourceModule
+      - readAt
+    filters:
+      - status
+      - kind
+    navigationGroup: Workspace
+  - id: preferences
+    kind: form
+    entity: preference
+    title: Notification preferences
+    columns:
+      - kind
+      - enabled
+    navigationGroup: Workspace
+  - id: webhooks
+    kind: list
+    entity: webhook-subscription
+    title: Webhooks
+    columns:
+      - name
+      - url
+      - status
+      - lastDeliveryAt
+      - secretFingerprint
+    filters:
+      - status
+    navigationGroup: Administration
+  - id: webhook
+    kind: record
+    entity: webhook-subscription
+    title: Webhook
+    columns:
+      - name
+      - url
+      - events
+      - status
+      - secretFingerprint
+      - description
+    navigationGroup: Administration
+  - id: deliveries
+    kind: list
+    entity: delivery
+    title: Deliveries
+    columns:
+      - subscription
+      - kind
+      - sourceRef
+      - attemptNumber
+      - status
+      - scheduledFor
+      - completedAt
+      - responseStatus
+      - errorClass
+    filters:
+      - status
+      - subscription
+    navigationGroup: Administration
+actions:
+  - id: mark-read
+    entity: inbox
+    permission: notifications.inbox.manage
+    kind: update
+    risk: workspace-write
+    idempotent: true
+    description: Set the member's own item to read and stamp readAt; repeating it changes nothing.
+  - id: mark-unread
+    entity: inbox
+    permission: notifications.inbox.manage
+    kind: update
+    risk: workspace-write
+    idempotent: true
+    description: Return the member's own item to unread and clear readAt.
+  - id: archive-item
+    entity: inbox
+    permission: notifications.inbox.manage
+    kind: update
+    risk: workspace-write
+    idempotent: true
+    description: Archive the member's own item; archived items leave the default inbox list.
+  - id: transition-many
+    entity: inbox
+    permission: notifications.inbox.manage
+    kind: update
+    risk: workspace-write
+    idempotent: true
+    description: Mark read or archive the items the inbox screen selected, between 1 and 100 unique ids, each through the single transition path scoped to the member, answering one outcome per id (updated, not-found, or refused for an archived item) and never failing the whole call for an item that is missing or another member's.
+  - id: save-preference
+    entity: preference
+    permission: notifications.inbox.manage
+    kind: update
+    risk: workspace-write
+    idempotent: true
+    description: Enable or disable one kind for the member's own account; the row is created on first save.
+  - id: save-email-delivery
+    entity: member-preference
+    permission: notifications.inbox.manage
+    kind: update
+    risk: workspace-write
+    idempotent: true
+    description: Turn e-mail delivery on or off for the member's own account; the row is created on first save.
+  - id: create-subscription
+    entity: webhook-subscription
+    permission: notifications.webhooks.manage
+    kind: create
+    risk: workspace-write
+    idempotent: false
+    description: Create an active subscription, generate the secret server-side, validate the URL against the egress policy and return the secret once.
+  - id: update-subscription
+    entity: webhook-subscription
+    permission: notifications.webhooks.manage
+    kind: update
+    risk: workspace-write
+    idempotent: true
+    description: Change name, url, events or description; a changed URL is validated again.
+  - id: pause-subscription
+    entity: webhook-subscription
+    permission: notifications.webhooks.manage
+    kind: custom
+    risk: workspace-write
+    idempotent: true
+    description: Move the subscription to paused; pending deliveries wait and are not counted as attempts.
+  - id: resume-subscription
+    entity: webhook-subscription
+    permission: notifications.webhooks.manage
+    kind: custom
+    risk: workspace-write
+    idempotent: true
+    description: Move a paused or disabled subscription back to active.
+  - id: disable-subscription
+    entity: webhook-subscription
+    permission: notifications.webhooks.manage
+    kind: custom
+    risk: workspace-write
+    idempotent: true
+    description: Move an active or paused subscription to disabled; its pending deliveries are dropped and it can be deleted or re-enabled later.
+  - id: rotate-secret
+    entity: webhook-subscription
+    permission: notifications.webhooks.manage
+    kind: custom
+    risk: workspace-write
+    idempotent: false
+    description: Generate a new secret, update the fingerprint and return the new secret once; deliveries already signed with the old secret are not re-signed.
+  - id: delete-subscription
+    entity: webhook-subscription
+    permission: notifications.webhooks.manage
+    kind: delete
+    risk: destructive
+    idempotent: true
+    description: Delete a disabled subscription and its pending deliveries; the attempt ledger stays until retention removes it.
+  - id: replay-delivery
+    entity: delivery
+    permission: notifications.deliveries.read
+    kind: custom
+    risk: workspace-write
+    idempotent: false
+    description: Queue a fresh attempt for a dead-lettered delivery from its regenerated payload.
+widgets:
+  - id: unread-count
+    slot: topbar.actions
+    entity: inbox
+    description: The number of unread inbox items of the signed-in member with a link to the inbox; hidden at zero.
+settings:
+  - key: retentionDays
+    type: integer
+    scope: tenant
+    default: 30
+    description: Days a delivery attempt is kept before the poll loop deletes it; 1 to 365.
+  - key: retryMaxAttempts
+    type: integer
+    scope: tenant
+    default: 8
+    description: Attempts before a delivery moves to dead letter; 1 to 20.
+  - key: retryMaxBackoffMinutes
+    type: integer
+    scope: tenant
+    default: 360
+    description: Upper bound of the exponential backoff between attempts; 1 to 1440.
+  - key: egressAllowlist
+    type: string
+    scope: platform
+    default: ''
+    description: Comma-separated host names a subscription URL may use; empty means any public host that passes the private-range block.
+  - key: pollIntervalSeconds
+    type: integer
+    scope: platform
+    default: 15
+    description: How often the delivery loop looks for due attempts; 5 to 300.
+agentTools: []
+outOfScope:
+  - Per-kind e-mail preferences are not offered; e-mail delivery is one switch per member over the kinds they already receive.
+  - A digest is not offered; one inbox item is one message.
+  - Notification sources other than agent runs, workflow runs and dead letters are deferred; auth.core membership events arrive through a later edit of that module's specification.
+  - There is no event bus; publishers call notifications.publish.v1 synchronously inside their own request or worker and tolerate its absence.
+  - Full-text search of the inbox is not available; the inbox filters by status and kind only.
+  - Stored request payloads are not kept; an administrator inspects the digest and size and replays from the regenerated payload.
+  - Cron expressions and time zones do not apply; the delivery loop runs on a fixed platform interval.
+decisions:
+  - id: D-SCOPE-V1
+    question: What is in the first version of notifications.core?
+    answer: The in-app inbox with preferences and outbound webhooks with a signed delivery ledger, retry and dead letter, in one specification.
+    decidedBy: user
+  - id: D-WEBHOOK-PERMISSIONS
+    question: Who manages outbound webhook subscriptions?
+    answer: Owners hold notifications.webhooks.manage and notifications.deliveries.read; members hold notifications.webhooks.read; every member holds both inbox permissions.
+    decidedBy: user
+  - id: D-RETENTION
+    question: How long are delivery attempts kept and is the payload stored?
+    answer: 30 days by default as a tenant setting; only the payload SHA-256 and size are stored, never the body.
+    decidedBy: user
+  - id: D-RETRY
+    question: What is the retry and dead letter policy?
+    answer: Up to 8 attempts with exponential backoff from 1 minute to 6 hours, then dead letter with manual replay; both bounds are tenant settings.
+    decidedBy: user
+  - id: D-SOURCES
+    question: Which events produce notifications in v1?
+    answer: Agent run completed and failed, workflow run completed and failed, and webhook dead letter; other modules publish through notifications.publish.v1 later.
+    decidedBy: user
+  - id: D-KINDS-METERING
+    question: Which kind does metering.core publish?
+    answer: meter-threshold to the workspace owners at the warning and the exhausted threshold, added in 0.1.3.
+    decidedBy: default
+  - id: D-KINDS-APPROVALS
+    question: Which kinds does approvals.core publish?
+    answer: approval-requested to eligible deciders and approval-decided to the requester, added in 0.1.2 as the first extension of the kind list.
+    decidedBy: default
+  - id: D-EGRESS
+    question: What egress policy applies to outbound webhooks?
+    answer: https only, private, loopback and link-local ranges blocked at save and at delivery, no redirects, 10 second timeout, 64 KB response cap, optional platform host allowlist.
+    decidedBy: user
+  - id: D-EMAIL
+    question: Does this module deliver notifications by e-mail?
+    answer: Yes since 0.2.0, through the platform mail port on the server context, as one switch per member over the kinds they already receive; RFC 0004 H1 made the port platform-level and this module its second sender.
+    decidedBy: user
+  - id: D-EMAIL-DEAD-LETTER
+    question: What does a dead-lettered e-mail produce?
+    answer: A ledger row and nothing else; an inbox item for it would be mailed, fail and dead-letter again under a new source reference.
+    decidedBy: default
+  - id: D-ACTORS
+    question: Which roles hold which permissions by default?
+    answer: Owner manages webhooks and reads deliveries; member reads webhooks and manages only their own inbox.
+    decidedBy: default
+  - id: D-INBOX-OWNERSHIP
+    question: How is a member limited to their own inbox?
+    answer: Every inbox read and mutation filters by the principal's account id inside the tenant transaction; there is no endpoint that lists another member's items.
+    decidedBy: default
+  - id: D-UNIQUE-NAME
+    question: Which field is unique inside a tenant?
+    answer: The subscription name; a duplicate returns a stable conflict.
+    decidedBy: default
+  - id: D-STATES
+    question: Which lifecycles exist?
+    answer: Inbox items unread, read, archived; subscriptions active, paused, disabled; deliveries pending, succeeded, failed, dead-letter, with the transitions listed on each entity.
+    decidedBy: default
+  - id: D-SECRET-STORAGE
+    question: How is the signing secret stored?
+    answer: Encrypted with a module key held outside the database and rotatable through the platform keyring, exactly like automations.core trigger secrets; shown in full only at creation and rotation.
+    decidedBy: default
+  - id: D-SIGNING
+    question: How are outbound requests signed?
+    answer: The inbound automations scheme is reused, HMAC-SHA256 over a versioned timestamp and body string in x-flowdular-signature with x-flowdular-timestamp.
+    decidedBy: default
+  - id: D-QUEUE
+    question: How are deliveries executed?
+    answer: A module-owned queue table drained by one poll loop with the automations.core lease discipline; no platform job primitive yet.
+    decidedBy: default
+  - id: D-IDEMPOTENT-PUBLISH
+    question: What happens when the same event is published twice?
+    answer: The source reference and kind are unique per recipient and per subscription inside a tenant, so a repeat creates nothing.
+    decidedBy: default
+  - id: D-SCREENS
+    question: Which screens exist?
+    answer: Inbox list and preferences form under Workspace; webhooks list, webhook record and deliveries list under Administration.
+    decidedBy: default
+  - id: D-WIDGET
+    question: Is there a dashboard or topbar widget?
+    answer: One topbar.actions widget with the unread count, hidden at zero; no dashboard tile.
+    decidedBy: default
+  - id: D-SETTINGS
+    question: Which settings exist?
+    answer: Tenant retentionDays 30, retryMaxAttempts 8, retryMaxBackoffMinutes 360; platform egressAllowlist empty and pollIntervalSeconds 15.
+    decidedBy: default
+  - id: D-DISABLE
+    question: How does a subscription reach the disabled state the delete action requires?
+    answer: Through an explicit disable action behind the manage permission that drops pending deliveries; resume re-enables it.
+    decidedBy: default
+  - id: D-PAYLOAD
+    question: What does the webhook payload carry, given that bodies are not stored?
+    answer: Version, kind, tenant id, subscription id, source module, source reference, title and occurredAt, all regenerable from the delivery row; details come from the source module.
+    decidedBy: default
+  - id: D-SECRET-ROTATION-CLI
+    question: How is the module signing key rotated?
+    answer: A notifications secrets-rotate CLI command over the platform keyring, mirroring automations.core.
+    decidedBy: default
+  - id: D-TOOLS
+    question: Are there agent tools?
+    answer: None in v1; a later phase may add a read tool over the member's inbox.
+    decidedBy: default
+acceptanceScenarios:
+  - id: NOTIFICATIONS-PUBLISH
+    given: agents.core publishes an agent-run-failed event through notifications.publish.v1 with a source reference and the run's configuring member as recipient.
+    when: The capability is invoked.
+    then: One unread inbox item addressed to that member exists in the run's tenant, and one pending delivery exists for every active subscription of that tenant that lists the kind.
+  - id: NOTIFICATIONS-PUBLISH-REPEAT
+    given: An event with the same source reference and kind was already published in the tenant.
+    when: It is published again.
+    then: No second inbox item or delivery is created and the capability returns the original identifiers.
+  - id: NOTIFICATIONS-INBOX-OWN
+    given: Two members of one tenant each have inbox items.
+    when: A member lists, marks or archives inbox items.
+    then: Only items addressed to that member's account are returned or changed, and an item id of the other member answers as not found. The inbox screen lists at most 200 items per request (50 by default) sorted by createdAt in either direction, open items unless a status is chosen, and continues through an opaque cursor bound to the tenant, the member, the sort, the direction and the filters, which is refused when any of them differ.
+  - id: NOTIFICATIONS-INBOX-MANY
+    given: A member holding notifications.inbox.manage selects several of their own inbox items, and the request also names an id that does not exist, one addressed to another member of the same workspace, one that belongs to another tenant and one of their own items that is already archived.
+    when: The member marks them read or archives them in one call naming the selected ids.
+    then: A list of no ids, of more than 100, one repeating an id or an unknown transition is refused with INVALID_INPUT before any row is touched; otherwise each of the member's own open items changes through the single transition path, the missing, the other member's and the other tenant's id are answered not-found with those rows unchanged, the archived item is answered refused with INBOX_TRANSITION_INVALID for either change, the screen offers mark-read for unread rows and archive for open rows only, the response carries one outcome per id in the order sent, the unread count reflects the change, and a call without the permission or the CSRF proof is refused first.
+  - id: NOTIFICATIONS-INBOX-PREFERENCE
+    given: A member disabled the kind agent-run-completed.
+    when: An event of that kind is published with that member as recipient.
+    then: No inbox item is created for that member, while webhook deliveries are unaffected.
+  - id: NOTIFICATIONS-EMAIL-CHANNEL
+    given: A member turned e-mail delivery on and another member of the same workspace did not.
+    when: An event addressed to both is published and the delivery loop runs.
+    then: Exactly one message is sent, to the address auth.core holds for the member who asked, carrying the item's title and body with the HTML part escaped; the attempt is recorded as succeeded with a payload digest and size and no copy of the message or the address, the other member receives only the inbox item, and publishing the same event again sends nothing further.
+  - id: NOTIFICATIONS-EMAIL-REFUSED
+    given: A member asked for e-mail and the deployment composed no transport, the relay fails, or the port's gate rejects the message itself.
+    when: The delivery loop runs.
+    then: A missing transport and a relay failure are recorded with their class and retried with the same backoff a webhook gets until the attempts are exhausted; a message the gate rejects is recorded once and reaches the dead letter on that first attempt because a retry cannot change it; in every case the delivery ends in the dead letter and no inbox item is created for the failure.
+  - id: NOTIFICATIONS-WEBHOOK-CREATE
+    given: A principal holding notifications.webhooks.manage supplies a unique name, an https URL to a public host and a non-empty list of kinds.
+    when: The subscription is created.
+    then: An active subscription is persisted, the secret is returned once in the response, and only its fingerprint is readable afterwards.
+  - id: NOTIFICATIONS-WEBHOOK-DUPLICATE
+    given: A subscription already uses a name in the active tenant.
+    when: Another subscription is created with the same normalized name.
+    then: The server returns a stable conflict and leaves existing data unchanged.
+  - id: NOTIFICATIONS-EGRESS
+    given: A principal supplies a URL with an http scheme, a loopback, private or link-local address, a host that resolves to one, or a host outside a non-empty platform allowlist.
+    when: The subscription is created or updated.
+    then: The server refuses with a stable egress error before any write, and a host that starts resolving to a private address after creation makes every delivery fail with errorClass egress-refused.
+  - id: NOTIFICATIONS-DELIVERY-SIGNED
+    given: An active subscription lists the kind of a published event.
+    when: The poll loop delivers the attempt.
+    then: The request carries x-flowdular-timestamp and an x-flowdular-signature the customer verifies with the shared scheme, follows no redirect, aborts after 10 seconds, reads at most 64 KB, and the attempt records the response status, the payload digest and size and no payload.
+  - id: NOTIFICATIONS-RETRY-DEADLETTER
+    given: A subscription endpoint answers 503 on every attempt.
+    when: The configured maximum number of attempts is exhausted.
+    then: Each attempt was scheduled with growing backoff bounded by the tenant setting, the delivery is in dead-letter, and members holding notifications.deliveries.read receive a webhook-dead-letter inbox item.
+  - id: NOTIFICATIONS-REPLAY
+    given: A delivery is in dead-letter.
+    when: A principal holding notifications.deliveries.read replays it.
+    then: A new pending attempt is queued from the regenerated payload, the earlier attempts remain in the ledger, and a principal without the permission is refused.
+  - id: NOTIFICATIONS-PAUSE
+    given: A subscription is paused.
+    when: Events are published and the poll loop runs.
+    then: Deliveries stay pending without counting attempts until the subscription is resumed.
+  - id: NOTIFICATIONS-DISABLE-DELETE
+    given: An active subscription has pending deliveries.
+    when: A principal holding notifications.webhooks.manage disables it and then deletes it.
+    then: The pending deliveries are dropped, the subscription is deleted, and the attempt ledger remains until retention removes it; deleting an active or paused subscription is refused with a stable error.
+  - id: NOTIFICATIONS-ROTATE
+    given: A subscription has a secret.
+    when: A principal holding notifications.webhooks.manage rotates it.
+    then: A new secret is returned once, the fingerprint changes, and later deliveries are signed with the new secret.
+  - id: NOTIFICATIONS-RETENTION
+    given: Delivery attempts older than the tenant retention window exist.
+    when: The poll loop runs.
+    then: Those attempts are deleted in bounded batches and newer attempts and all inbox items remain.
+  - id: NOTIFICATIONS-LIST-PAGES
+    given: A workspace holds more subscriptions and delivery attempts than one page.
+    when: An administrator opens the webhooks or the deliveries screen and walks its pages.
+    then: The webhooks screen lists at most 200 subscriptions per request (50 by default) sorted by name in either direction with the status and search filters applied by the server, the deliveries screen lists at most 200 attempts per request (50 by default) sorted by scheduledFor in either direction with the status, subscription and search filters applied by the server, and each screen continues through an opaque cursor bound to the tenant, the sort, the direction and the filters, which is refused when any of them differ.
+  - id: NOTIFICATIONS-DENY
+    given: A principal is unauthenticated or lacks the required permission.
+    when: The principal reads or mutates inbox items, subscriptions or deliveries.
+    then: The server denies the operation before repository access, and a mutation without a CSRF proof is refused first.
+  - id: NOTIFICATIONS-DATA-CLASSES
+    given: Two tenants hold inbox items and delivery attempts of several ages, one attempt still queued.
+    when: The platform sweeps and exports the declared classes for one of them.
+    then: The sweep removes only that tenant's rows strictly older than the cutoff and at most the batch it was given, the queued attempt stays, and the export streams that tenant's rows alone through the sink in keyset pages with the oldest and newest record time, answering no rows and no range for a workspace that holds none.
+  - id: NOTIFICATIONS-TENANT-BOUNDARY
+    given: Two tenants own inbox items, subscriptions and deliveries.
+    when: A runtime transaction bound to one tenant reads or writes any of them, or the cross-tenant poll routes work.
+    then: Only that tenant's rows are visible or mutable, the poll sees routing columns alone on the read-only role, and a row carrying another tenant identifier is rejected by the forced policy.