docs(requirements): add TrackedOperationId and cached-call contracts to Commons

This commit is contained in:
Joseph Doherty
2026-05-19 11:37:04 -04:00
parent e0026c6da7
commit 397498c120

View File

@@ -35,6 +35,8 @@ Commons must define shared primitive and utility types used across multiple comp
- **`AlarmLevel` enum**: None, Low, LowLow, High, HighHigh. Severity level for an active alarm; always `None` for binary trigger types, set by `HiLo` triggers.
- **`AlarmTriggerType` enum**: ValueMatch, RangeViolation, RateOfChange, HiLo.
- **`ConnectionHealth` enum**: Connected, Disconnected, Connecting, Error.
- **`TrackedOperationId`**: A GUID identifying a tracked store-and-forward operation (`ExternalSystem.CachedCall`, `Database.CachedWrite`, `Notify.Send`). Generated caller-side at the site at call time, returned to the script as a tracking handle, and reused as the idempotency key for telemetry sent to central. The notification domain's existing `NotificationId` is the notification-specific name for this same concept.
- **`TrackedOperationStatus` enum**: Pending, Retrying, Delivered, Parked, Failed, Discarded. The unified lifecycle state shared by all tracked store-and-forward operations.
Types defined here must be immutable and thread-safe.
@@ -119,6 +121,8 @@ Commons must define the shared DTOs and message contracts used for inter-compone
- **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` (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.
- **Cached Call Tracking DTOs**: `CachedCallTelemetry` (site→central lifecycle telemetry for a tracked cached call: `TrackedOperationId`, source site, `Kind` — an `ExternalCall` / `DatabaseWrite` enum — target summary, status, retry count, last error, key timestamps, and source instance / script provenance) and `CachedCallReconcileRequest` / `CachedCallReconcileResponse` (cursor-based per-site pull of tracking rows changed since a cursor, used so missed telemetry self-heals). All three live in the `Integration/` message folder and are subject to the additive-only evolution rules in REQ-COM-5a, since they cross the site→central version-skew boundary.
- **Parked Operation Command DTOs**: `RetryParkedOperation` and `DiscardParkedOperation` (central→site command/control messages keyed by `TrackedOperationId`, instructing the owning site to retry or discard a parked store-and-forward operation). These generalize the existing parked-message retry/discard commands to also cover parked cached calls; they live in the `RemoteQuery/` message folder alongside the other parked-message management messages.
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).
@@ -145,11 +149,13 @@ ScadaLink.Commons/
│ ├── StaleTagMonitor.cs # heartbeat staleness watchdog
│ ├── ValueFormatter.cs # culture-invariant value-to-string helper
│ ├── DynamicJsonElement.cs # dynamic JSON wrapper for scripts
│ ├── TrackedOperationId.cs # tracked store-and-forward operation ID (GUID)
│ ├── Enums/ # InstanceState, DeploymentStatus, AlarmState,
│ │ # AlarmLevel, AlarmTriggerType, ConnectionHealth,
│ │ # DataType, StoreAndForwardCategory,
│ │ # StoreAndForwardMessageStatus,
│ │ # NotificationType, NotificationStatus
│ │ # NotificationType, NotificationStatus,
│ │ # TrackedOperationStatus
│ ├── DataConnections/ # OPC UA endpoint config value objects + enums
│ ├── Flattening/ # FlattenedConfiguration, ConfigurationDiff,
│ │ # DeploymentPackage, ValidationResult
@@ -199,11 +205,13 @@ ScadaLink.Commons/
│ ├── Artifacts/
│ ├── DataConnection/ # data-connection subscribe/write/health messages
│ ├── Instance/ # attribute get/set request/command messages
│ ├── Integration/ # external-integration call request/response
│ ├── Integration/ # external-integration call request/response,
│ │ # cached-call tracking telemetry + reconcile
│ ├── Notification/ # NotificationSubmit + ack,
│ │ # NotificationStatusQuery/Response
│ ├── InboundApi/ # Route.To() request messages
│ ├── RemoteQuery/ # event-log and parked-message query messages
│ ├── RemoteQuery/ # event-log and parked-message query messages,
│ │ # parked-operation retry/discard commands
│ └── Management/ # HTTP/ClusterClient management commands + registry
├── Serialization/ # OpcUaEndpointConfigSerializer (typed↔legacy JSON)
└── Validators/ # OpcUaEndpointConfigValidator