From e0026c6da7f64095b517b3770cefe0d347f1113e Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Tue, 19 May 2026 11:34:44 -0400 Subject: [PATCH] docs(requirements): clarify Site Call Audit lifecycle states and actionability --- docs/requirements/Component-SiteCallAudit.md | 27 +++++++++++++++----- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/docs/requirements/Component-SiteCallAudit.md b/docs/requirements/Component-SiteCallAudit.md index 33b5d8b..efd7397 100644 --- a/docs/requirements/Component-SiteCallAudit.md +++ b/docs/requirements/Component-SiteCallAudit.md @@ -37,7 +37,9 @@ Lives in the central MS SQL configuration database — a sibling of the - **TrackedOperationId** — GUID, primary key. Generated site-side at call time. - **SourceSite** — site that issued the call. - **Kind** — `ExternalCall` or `DatabaseWrite`. -- **TargetSummary** — external system + method name, or database connection name. +- **TargetSummary** — external system + method name for an `ExternalCall`; for a + `DatabaseWrite`, just the database connection name — intentionally not the SQL + statement or table, a deliberate scoping choice. - **Status** — `Pending`, `Retrying`, `Delivered`, `Parked`, `Failed`, `Discarded`. - **RetryCount** — attempts so far. - **LastError** — most recent error detail, if any. @@ -48,12 +50,18 @@ Lives in the central MS SQL configuration database — a sibling of the `Pending → Retrying → Delivered / Parked / Failed / Discarded` -- **Delivered** — succeeded. A cached call that succeeds on its first immediate - attempt is recorded directly as `Delivered`. -- **Parked** — transient retries exhausted; awaiting manual action. -- **Failed** — permanent failure (e.g. HTTP 4xx). The error was also returned - synchronously to the calling script; the record captures it. -- **Discarded** — an operator discarded a parked operation. +- **Pending** — non-terminal: buffered after a transient failure, awaiting its + first retry. +- **Retrying** — non-terminal: undergoing retry attempts. +- **Delivered** — terminal, success. A cached call that succeeds on its first + immediate attempt is recorded directly as `Delivered`. +- **Parked** — non-terminal: transient retries exhausted; awaiting manual action. +- **Failed** — terminal: permanent failure (e.g. HTTP 4xx). The error was also + returned synchronously to the calling script; the record captures it. `Failed` + rows are **not operator-actionable** — see Retry / Discard Relay. +- **Discarded** — terminal, reached **only by operator action** on a `Parked` + row. The row is kept (not deleted) so the table remains a complete audit + record. The site is the source of truth. The `SiteCalls` row is an eventually-consistent mirror — never queried by scripts (`Tracking.Status()` is answered site-locally). @@ -81,6 +89,11 @@ applies the change and emits telemetry reflecting the new state; central never mutates the `SiteCalls` row directly. If the site is offline the command fails fast and the UI surfaces a "site unreachable" message. +Only `Parked` rows are operator-actionable. `Failed` rows offer no Retry or +Discard: a permanent failure (e.g. HTTP 4xx) would simply fail again, and the +error was already returned synchronously to the calling script — there is +nothing for an operator to recover. + ## KPIs Point-in-time, computed from the `SiteCalls` table, global and per-source-site,