docs(audit): apply cross-bundle review fixes before merge
Final cross-bundle reviewer identified 7 inconsistencies that the per-bundle reviewers couldn't see; all fixed in one logical commit. Critical: - HighLevelReqs AL-3: drop 'then upsert-on-newer-status' — AuditLog is strictly append-only (correct for SiteCalls/Notifications, wrong for the immutable AuditLog shadow). - Component-AuditLog Error rate KPI: align with HealthMonitoring's exclusion list (Success/Delivered/Enqueued) rather than just non-Success; otherwise every Delivered notification or Enqueued cached call would be counted as an error. Important: - Component-AuditLog line 154: ISiteAuditWriter -> IAuditWriter (canonical name per Commons and the rest of this doc). - Component-AuditLog Central direct-write paragraph: convert remaining slash notation (ApiInbound/Completed, Notification/Attempt, Notification/Terminal) to dot notation used everywhere else. - Component-ClusterInfrastructure: scope SiteCallAuditActor to reconciliation + KPIs + Retry/Discard relay; cached-telemetry ingest is AuditLogIngestActor's role per Combined Telemetry contract. - Component-CentralUI Audit Log page: state the OperationalAudit read permission and the read-vs-export split (matching CLI doc). - Component-NotificationOutbox: add never-fail-the-action invariant for dispatcher audit writes. Minor: - Component-InboundAPI: 'Non-blocking semantics' was ambiguous (could be read as async); reword to 'Fail-soft' — the write is still synchronous before flush, but failures are caught and don't change the response. - Component-CLI: realign audit-query/audit-export flags to actually match the Central UI Audit Log filter set (channel, kind, status, site, instance, target, actor, correlation-id, errors-only); drop --user and --entity-id which are IAuditService concepts, not Audit Log columns. - Component-AuditLog KPI tile names: 'Volume/Error rate/Backlog' -> 'Audit volume/Audit error rate/Audit backlog' (matches Central UI and Health Monitoring); drop the two orphan KPIs (Top inbound callers, Top outbound 5xx) that were never surfaced anywhere. - Component-AuditLog Interactions: re-attribute DbOutbound emissions to ESG (where Database.* lives) with a note that Site Runtime is the API surface for scripts. - HighLevelReqs AL-12: drop 'and reconciliation operations' (CLI has no reconcile command; reconciliation is an internal self-healing pull). Add note that verify-chain becomes operational once AL-11's hash chain ships.
This commit is contained in:
@@ -118,7 +118,7 @@ API method scripts are compiled at central startup — all method definitions ar
|
||||
|
||||
- **Every request — success or failure — emits one `ApiInbound.Completed` row** to `ICentralAuditWriter` from request middleware before the HTTP response is flushed. The row captures the API key **name** (never the key material), remote IP, user-agent, response status, duration, and truncated request/response bodies per the Audit Log capture policy (see Component-AuditLog.md, Payload Capture Policy). This supersedes the earlier failures-only stance: operational API traffic is now part of the centralized audit log, so configuration changes and call activity share a single retention/query surface.
|
||||
- Script execution errors (500 responses) remain captured on the same `ApiInbound.Completed` row (response status + error fields) rather than emitting a separate failure-only event.
|
||||
- **Non-blocking semantics.** Middleware audit-write failures are logged and metricked (see Health Monitoring #11 — `CentralAuditWriteFailures`) but **never affect the HTTP response**: a failed audit append does not turn a successful API call into an error returned to the caller.
|
||||
- **Fail-soft semantics.** The audit write is synchronous (inline before the response is flushed), but failures are caught: a write that throws is logged and increments `CentralAuditWriteFailures` (see Health Monitoring #11) and the request still returns its normal HTTP response. A failed audit append never turns a successful API call into an error returned to the caller.
|
||||
- No rate limiting — this is a private API in a controlled industrial environment with a known set of callers. Misbehaving callers are handled operationally (disable the API key).
|
||||
|
||||
## Request Flow
|
||||
|
||||
Reference in New Issue
Block a user