docs(requirements): cached calls return TrackedOperationId in ESG

docs/requirements/Component-ExternalSystemGateway.md

@@ -59,10 +59,10 @@ Each database connection definition includes:
 - Failures are immediate — no buffering.
 
 ### Cached Write (Store-and-Forward)
-- Script calls `Database.CachedWrite("name", "sql", parameters)`.
-- The write is submitted to the Store-and-Forward Engine.
+- Script calls `Database.CachedWrite("name", "sql", parameters)`. This is **deferred delivery**: the call returns a `TrackedOperationId` tracking handle immediately rather than the write result.
 - Payload includes: connection name, SQL statement, serialized parameter values.
-- If the database is unavailable, the write is buffered and retried per the connection's retry settings.
+- 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.
+- Cached-write status is observable to scripts via `Tracking.Status(id)` (answered site-locally) and centrally via the Site Call Audit component.
 
 ## Invocation Protocol
 
@@ -84,10 +84,11 @@ Scripts choose between two call modes per invocation, mirroring the dual-mode da
 - Use for request/response interactions where the script needs the result (e.g., fetching a recipe, querying inventory).
 
 ### Cached (Store-and-Forward)
-- Script calls `ExternalSystem.CachedCall("systemName", "methodName", params)`.
-- The call is attempted immediately. If it succeeds, the response is discarded (fire-and-forget).
-- 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 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.
+- Script calls `ExternalSystem.CachedCall("systemName", "methodName", params)`. This is **deferred delivery**: the call returns a `TrackedOperationId` tracking handle immediately rather than the response body.
+- The call is attempted immediately. If it succeeds, the response is discarded and the call is recorded as a terminal `Delivered` tracking record.
+- 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.
 - Use for outbound data pushes where deferred delivery is acceptable (e.g., posting production data, sending quality reports).
 
 ## Call Timeout & Error Handling
@@ -95,7 +96,7 @@ Scripts choose between two call modes per invocation, mirroring the dual-mode da
 - Each external system definition specifies a **timeout** that applies to all method calls on that system.
 - Error classification by HTTP response:
   - **Transient failures** (connection refused, timeout, HTTP 408, 429, 5xx): Behavior depends on call mode — `CachedCall` buffers for retry; `Call` returns error to script.
-  - **Permanent failures** (HTTP 4xx except 408/429): Always returned to the calling script regardless of call mode. Logged to Site Event Logging.
+  - **Permanent failures** (HTTP 4xx except 408/429): Always returned to the calling script regardless of call mode. Logged to Site Event Logging. For `CachedCall`, the failure is additionally recorded as a terminal `Failed` tracking record — so even a never-buffered cached call has an authoritative status record.
 - This classification ensures the S&F buffer is not polluted with requests that will never succeed.
 - **Idempotency note**: `CachedCall` retries may result in duplicate delivery if the external system received the original request but the response was lost. Callers should use `CachedCall` only for operations that are idempotent or where duplicate delivery is acceptable.
 
@@ -114,7 +115,8 @@ Scripts choose between two call modes per invocation, mirroring the dual-mode da
 
 - **Configuration Database (MS SQL)**: Stores external system and database connection definitions (central only).
 - **Local SQLite**: At sites, external system and database connection definitions are read from local SQLite (populated by artifact deployment). Sites do not access the central config DB.
-- **Store-and-Forward Engine**: Handles buffering for failed external system calls and cached database writes.
+- **Store-and-Forward Engine**: Handles buffering for failed external system calls and cached database writes, and owns the site-local operation tracking table read by `Tracking.Status(id)`.
+- **Site Call Audit**: Central audit mirror for cached calls — receives cached-call lifecycle telemetry so `CachedCall`/`CachedWrite` status is observable centrally.
 - **Communication Layer**: Routes inbound external system requests from central to sites.
 - **Security & Auth**: Design role manages definitions.
 - **Configuration Database (via IAuditService)**: Definition changes are audit logged.
@@ -122,5 +124,6 @@ Scripts choose between two call modes per invocation, mirroring the dual-mode da
 ## Interactions
 
 - **Site Runtime (Script/Alarm Execution Actors)**: Scripts invoke external system methods and database operations through this component.
-- **Store-and-Forward Engine**: Failed calls and cached writes are routed here for reliable delivery.
+- **Store-and-Forward Engine**: Failed calls and cached writes are routed here for reliable delivery; it also assigns each cached call a `TrackedOperationId` tracking row.
+- **Site Call Audit**: The central observability sibling for cached calls — cached-call status reported here is queried via the Central UI Site Calls page.
 - **Deployment Manager**: Receives updated definitions as part of system-wide artifact deployment (triggered explicitly by Deployment role).