From 117fa39d35aaa058ed205eae0361cf3645eb82d0 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Wed, 20 May 2026 08:05:31 -0400 Subject: [PATCH] docs(audit): note IAuditWriter hook and site SQLite in Site Runtime --- docs/requirements/Component-SiteRuntime.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/requirements/Component-SiteRuntime.md b/docs/requirements/Component-SiteRuntime.md index 38a99a4..46ced24 100644 --- a/docs/requirements/Component-SiteRuntime.md +++ b/docs/requirements/Component-SiteRuntime.md @@ -294,6 +294,10 @@ Scripts execute **in-process** with constrained access. The following restrictio These constraints are enforced by restricting the set of assemblies and namespaces available to the script compilation context. +### Script Trust Boundary Auditing + +Every script-trust-boundary call (External System Gateway, Database layer, Notify) emits an `AuditEvent` to `IAuditWriter` (site-local SQLite append). Hot path; never fails the calling action; failures logged via the `SiteAuditWriteFailures` health metric (see [Component-HealthMonitoring.md](Component-HealthMonitoring.md)). The central audit mirror and event schema live in [Component-AuditLog.md](Component-AuditLog.md). + ## Script Scoping Rules - Scripts can only read/write attributes on **their own instance** (via the parent Instance Actor). @@ -363,7 +367,7 @@ Per Akka.NET best practices, internal actor communication uses **Tell** (fire-an - **Communication Layer**: Receives deployments and lifecycle commands from central. Handles debug view requests. Reports deployment results. - **Site Event Logging**: Records script executions, alarm events, deployment events, instance lifecycle events. - **Health Monitoring**: Reports script error rates and alarm evaluation error rates. -- **Local SQLite**: Persists deployed configurations, system-wide artifacts (external system definitions, database connection definitions, data connection definitions). +- **Local SQLite**: Persists deployed configurations, system-wide artifacts (external system definitions, database connection definitions, data connection definitions). Sites also maintain peer SQLite stores for the Store-and-Forward buffer, the site event log, the operation tracking table, and the site-local `AuditLog` (see [Component-AuditLog.md](Component-AuditLog.md)). The `AuditLog` file is purged on the same daily cadence as the others but respects the hard `ForwardState` invariant — rows still `Pending` forward are never purged, regardless of age. ## Interactions