From 2039b1ddca8d92b01d6745ef26f89dc037b80740 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Wed, 20 May 2026 08:06:12 -0400 Subject: [PATCH] docs(audit): emit AuditLog rows from External System Gateway call paths --- docs/requirements/Component-ExternalSystemGateway.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/requirements/Component-ExternalSystemGateway.md b/docs/requirements/Component-ExternalSystemGateway.md index e38560c..03cfa4d 100644 --- a/docs/requirements/Component-ExternalSystemGateway.md +++ b/docs/requirements/Component-ExternalSystemGateway.md @@ -57,6 +57,7 @@ Each database connection definition includes: - Script calls `Database.Connection("name")` and receives a raw ADO.NET `SqlConnection`. - Full control: queries, updates, transactions, stored procedures. - Failures are immediate — no buffering. +- **Audit emission**: script-initiated `Execute`/`ExecuteScalar` calls emit `DbOutbound.SyncWrite` rows; `ExecuteReader` emits `DbOutbound.SyncRead`. SQL parameter values are captured by default; per-connection redaction opt-in via the Audit Log configuration (see [Component-AuditLog.md](Component-AuditLog.md), Payload Capture Policy). Audit-write failure never aborts the script. ### Cached Write (Store-and-Forward) - Script calls `Database.CachedWrite("name", "sql", parameters)`. This is **deferred delivery**: the call returns a `TrackedOperationId` tracking handle immediately rather than the write result. @@ -64,6 +65,7 @@ Each database connection definition includes: - The write is attempted immediately. On immediate success it is recorded as a terminal `Delivered` tracking record. On **transient failure** (database unavailable) it is buffered (`Pending`/`Retrying`) and retried per the connection's retry settings by the Store-and-Forward Engine. - On **permanent failure** (e.g. a SQL syntax or constraint error — a request that will never succeed), the error is returned **synchronously** to the calling script and the write is **not** buffered. The call is also recorded as a terminal `Failed` tracking record capturing the error. - Cached-write status is observable to scripts via `Tracking.Status(id)` (answered site-locally and authoritatively) and centrally via the Site Call Audit component. +- **Audit emission**: each lifecycle transition (`CachedEnqueued`, `CachedAttempt`, `CachedTerminal`) emits an audit row via the combined cached-operation telemetry packet — one packet carries both the audit row and the SiteCalls upsert (see [Component-AuditLog.md](Component-AuditLog.md), Cached Operations — Combined Telemetry, and [Component-SiteCallAudit.md](Component-SiteCallAudit.md)). Audit-write failure never aborts the script. ## Invocation Protocol @@ -83,6 +85,7 @@ Scripts choose between two call modes per invocation, mirroring the dual-mode da - The HTTP request is executed immediately. The script blocks until the response is received or the timeout elapses. - **All failures** (transient and permanent) return an error to the calling script. No store-and-forward buffering. - Use for request/response interactions where the script needs the result (e.g., fetching a recipe, querying inventory). +- **Audit emission**: emits an `ApiOutbound.SyncCall` row to `IAuditWriter` at call completion (success or failure). Payload captured per the Audit Log policy (see [Component-AuditLog.md](Component-AuditLog.md), Payload Capture Policy). Audit-write failure never aborts the script. ### Cached (Store-and-Forward) - Script calls `ExternalSystem.CachedCall("systemName", "methodName", params)`. This is **deferred delivery**: the call returns a `TrackedOperationId` tracking handle immediately rather than the response body. @@ -90,6 +93,7 @@ Scripts choose between two call modes per invocation, mirroring the dual-mode da - On **transient failure** (connection refused, timeout, HTTP 5xx), the call is routed to the Store-and-Forward Engine for retry per the system's retry settings. The script does **not** block — the call is buffered (`Pending`/`Retrying`) and the script continues. - On **permanent failure** (HTTP 4xx), the error is returned **synchronously** to the calling script. No retry — the request itself is wrong. The call is also recorded as a terminal `Failed` tracking record capturing the error. - Cached-call status is observable to scripts via `Tracking.Status(id)` (answered site-locally and authoritatively) and centrally via the Site Call Audit component. +- **Audit emission**: each lifecycle transition (`CachedEnqueued`, `CachedAttempt`, `CachedTerminal`) emits an audit row via the combined cached-operation telemetry packet — one packet carries both the audit row and the SiteCalls upsert (see [Component-AuditLog.md](Component-AuditLog.md), Cached Operations — Combined Telemetry, and [Component-SiteCallAudit.md](Component-SiteCallAudit.md)). Audit-write failure never aborts the script. - Use for outbound data pushes where deferred delivery is acceptable (e.g., posting production data, sending quality reports). ## Call Timeout & Error Handling