From f839f6ce4530986c4d3d6625cc47afac6651d7cf Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Tue, 19 May 2026 11:47:30 -0400 Subject: [PATCH] docs(requirements): make cached-write and cached-call docs symmetric --- docs/requirements/Component-ExternalSystemGateway.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/requirements/Component-ExternalSystemGateway.md b/docs/requirements/Component-ExternalSystemGateway.md index 9678f55..e38560c 100644 --- a/docs/requirements/Component-ExternalSystemGateway.md +++ b/docs/requirements/Component-ExternalSystemGateway.md @@ -62,7 +62,8 @@ Each database connection definition includes: - 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. - 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. +- 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. ## Invocation Protocol