docs(notification-outbox): polish Task 8 docs — purge basis, message-contract naming, density

This commit is contained in:
Joseph Doherty
2026-05-18 23:34:40 -04:00
parent ef4614d710
commit 097bb3361e
2 changed files with 5 additions and 4 deletions

View File

@@ -118,7 +118,7 @@ Commons must define the shared DTOs and message contracts used for inter-compone
- **Debug View DTOs**: Subscribe/unsubscribe requests, one-shot snapshot request (`DebugSnapshotRequest`), initial snapshot, stream filter criteria.
- **Script Execution DTOs**: Script call requests (with recursion depth), return values, error results.
- **System-Wide Artifact DTOs**: Shared script packages, external system definitions, database connection definitions, notification list definitions.
- **Notification DTOs**: `NotificationSubmit` — the site→central notification submission carrying `NotificationId` (GUID), `ListName`, `Subject`, `Body`, provenance (`SourceSiteId`, `SourceInstanceId`, `SourceScript`), and `SiteEnqueuedAt` and `NotificationSubmitAck`, the central acknowledgement returned after the `Notifications` row is persisted (ack-after-persist), which the site Store-and-Forward Engine waits on before clearing the buffered message. Recipient resolution is *not* part of the contract — the site forwards only `(listName, subject, body)` and central resolves the list at delivery time. `Notify.Status` also round-trips a small status-query request and a status-record response (status, retry count, last error, key timestamps) once a notification has been forwarded. These contracts are `record` types subject to the additive-only evolution rules in REQ-COM-5a — relevant because a notification submission can cross the site→central version skew boundary; future per-type fields are carried by adding optional fields (or via the `Notifications` table's `TypeData` JSON hook) rather than by changing existing ones.
- **Notification DTOs**: `NotificationSubmit` (site→central submission: `NotificationId`, `ListName`, `Subject`, `Body`, provenance, `SiteEnqueuedAt`) and `NotificationSubmitAck` (central acknowledgement returned only after the `Notifications` row is persisted ack-after-persist which the site Store-and-Forward Engine waits on before clearing the buffered message). `NotificationStatusQuery` / `NotificationStatusResponse` back the `Notify.Status` script API, round-tripping a status record (status, retry count, last error, key timestamps) once a notification has been forwarded. Recipient resolution is *not* part of any contract — the site forwards only `(listName, subject, body)` and central resolves the list at delivery time. Subject to the additive-only evolution rules in REQ-COM-5a, since a submission can cross the site→central version-skew boundary.
All message types must be `record` types or immutable classes suitable for use as Akka.NET messages (though Commons itself must not depend on Akka.NET).
@@ -200,7 +200,8 @@ ScadaLink.Commons/
│ ├── DataConnection/ # data-connection subscribe/write/health messages
│ ├── Instance/ # attribute get/set request/command messages
│ ├── Integration/ # external-integration call request/response
│ ├── Notification/ # NotificationSubmit + ack, Notify.Status query/response
│ ├── Notification/ # NotificationSubmit + ack,
│ │ # NotificationStatusQuery/Response
│ ├── InboundApi/ # Route.To() request messages
│ ├── RemoteQuery/ # event-log and parked-message query messages
│ └── Management/ # HTTP/ClusterClient management commands + registry