Operational services
Log, audit and user notification.
Applies the SDLC framework's logging, audit and notification standard (core/LOGGING_AUDIT_NOTIFICATIONS.md). Values are design; nothing is implemented.
Capabilities and reuse
| Capability | Verified contract and implementation (Observed 2026-10-28) | Decision | Owner | Verification |
|---|---|---|---|---|
| Log Service | Two layers. (a) Legacy IDMLogger (BeepDM/DataManagementModelsStandard/Logger/IDMLogger.cs), implemented by DataManagementEngineStandard/Logger/DMLogger.cs (also Microsoft.Extensions.Logging.ILogger; rolling file log.txt, 7 files; lock-guarded config) and by Services/Logging/Bridges/DMLoggerToBeepLogBridge.cs. (b) Unified IBeepLog (DataManagementModelsStandard/Services/Logging/IBeepLog.cs: Log(...), Trace/Debug/Info/Warn/Error(msg, ex, properties), Critical, FlushAsync) with BeepLog.*.cs, NullBeepLog, options in BeepLoggingOptions.cs, registered by BeepServiceExtensions.Logging.cs. IDMEEditor.Logger is IDMLogger |
Reuse IBeepLog (structured properties, exception parameter, async flush) resolved from DI when present; fall back to IDMEEditor.Logger.LogStructured when absent. ReportLog adapter adds event IDs/correlation ID. Do not create a third logger |
ARC | P00.E.4 tests |
| Audit Service | Two layers. (a) Forms-oriented IAuditStore/IAuditManager/AuditEntry (Editor/Forms/Interfaces/ISecurityAndAudit.cs, Editor/Forms/Models/AuditModels.cs: FormName, BlockName, RecordKey, AuditOperation, UserName, Timestamp, before/after images; FileAuditStore = whole-file JSON rewrite under a lock, InMemoryAuditStore) — not suitable (no tenant/outcome/correlation, not append-only). (b) Unified IBeepAudit (DataManagementModelsStandard/Services/Audit/IBeepAudit.cs: RecordAsync(AuditEvent), QueryAsync, PurgeByUser/Entity, VerifyIntegrityAsync, FlushAsync; "lossless by policy, never sampled or dropped") with AuditEvent (EventId, TimestampUtc, Source, EntityName, RecordKey, UserId, UserName, Tenant, CorrelationId, TraceId, Properties, Category (DataAccess/Auth/Config/…), Operation, Outcome (Success/Failure/Denied/Pending), Reason, hash-chain fields), engine Services/Audit/* (queue with BackpressureMode.Block, retention, NDJSON export, hash-chain integrity, GDPR purge). Disabled by default (BeepAuditOptions.Enabled=false → NullBeepAudit); enabled through AddBeepAudit (Services/BeepServiceExtensions.Audit.cs) |
Reuse IBeepAudit — fits actor/tenant/action/target/outcome/correlation exactly. IReportAuditSink becomes a thin mapper ReportAuditRecord → AuditEvent. Because the default is NullBeepAudit, Beep.Reports must detect the null implementation and refuse audited actions (BR8001) unless the host explicitly accepts "audit disabled" via config. Resolves D-10; upstream request U-04 is not needed |
ARC | P00.E.4 + P07 tests |
| Notification Service | INotificationService (DataManagementModelsStandard/Studio/Notifications/INotificationService.cs: SendAsync(NotificationMessage, channels), inbox, subscriptions) implemented by Services/Studio/Notifications/InboxNotificationService.cs (file-backed JSON under {dataRoot}/notifications, process-wide lock, atomic temp+move; NotificationChannel Inbox/Email/…/SignalR; pluggable INotificationChannel, adapters must not throw). Email/SignalR channel adapters are not in BeepDM (only the interface) |
Reuse for inbox; Beep.Reports supplies its own INotificationChannel adapters (SMTP, file) in P07.C.4; retry/dead-letter is ours (channel contract says "log and return") |
DEV | P07 tests |
| UI Notification Service | No shared cross-host service. Found: WinForms BeepNotificationManager (Beep.Winform/TheTechIdea.Beep.Winform.Controls/Notifications/BeepNotificationManager.cs: Show/ShowSuccess/ShowError/ShowWarning/ShowInfo/ShowWithActions/Dismiss*); Web FailureNotifier over MudBlazor ISnackbar (Beep.Web/TheTechIdeaWeb.Diagnostics/Notifications/FailureNotifier.cs); legacy designer uses ISnackbar. None in Beep.Skia hosts, WPF or Avalonia |
New IUiNotificationService contract (Designer.Core/Viewer.Core) with adapters: WinForms → BeepNotificationManager, Blazor → ISnackbar (or host-neutral fallback banner), WPF/Avalonia → own minimal toast/status bar. Resolves D-11 |
DEV | P10/P11 UI tests |
Related findings (P00.C.1)
- Reports in ConfigEditor:
IConfigEditor.Reportslist(List<ReportsList>),SaveReportsValues()/LoadReportsValues(),ReportWritersClasses,SaveReportDefinitionsValues()/LoadReportsDefinitionValues()(List<AppTemplate>) (ConfigUtil/IConfigEditor.cs; implementationConfigUtil/ConfigEditor.cs; persistedReportslist.jsonbyManagers/ComponentConfigManager.cs).ReportsListcarriesReportName,ReportDefinition(string),ReportEngine, …IReportDMWriter(Reports/IReportDMWriter.cs: Html/Text/Csv/PDF/Excel flags,RunReport) is the legacy writer contract. →ConfigEditorReportStore(P01.E.3) can store.beeprptJSON inReportsList.ReportDefinitionwithReportEngine = "Beep.Reports"; legacy writer classes remain for P14.B adapters. - Datasource thread safety:
IDMEEditor.GetDataSource(name)→GetDataSourceById→EditorDataSourceRegistry.Find(Helpers/EditorDataSourceRegistry.cs) returns the shared registered instance per editor; the registry guards only its own lookup/creation (state.Gate), not use of the instance. No documented thread-safety forIDataSourcemembers. → P02.A.4 must use a per-run dedicated instance viaCreateNewDataSourceConnection(connection, name)where the driver allows, otherwise serialize runs per connection (SemaphoreSlimkeyed by connection). Upstream request U-03 stays open (documentation/guarantee), but the implementation does not depend on it. - Model-side
AuditEntryname collision:Pipelines/Models/Observability/AuditEntry.csand Beep.SkiaCollaboration.AuditEntryalso exist — always useAuditEventfromServices/Audit/Modelsand namespace-qualify.
Event coverage and destinations
| Boundary / event (ID prefix) | Actor/target/outcome | Log | Durable audit | Notification |
|---|---|---|---|---|
report.definition.load |
user, reportId/version, ok/fail/denied | Info / Error with cause | Denied only | UI error on fail |
report.definition.save |
user, reportId, version, ok/conflict/fail/denied | Info / Warn / Error | Yes, all outcomes | UI toast |
report.definition.delete / restore |
user, reportId, version | Info / Error | Yes | UI toast |
report.definition.validate |
reportId, diagnostic counts | Debug | No | Designer error list |
report.run (preview/normal) |
user, reportId, params digest (redacted), rows, pages, duration, outcome | Info / Error | Yes for Normal; Preview: no | UI on fail |
report.export (sync/async) |
user, reportId, format, size, outcome | Info / Error | Yes (sensitive read) | Async: Notification Service on complete/fail |
report.job.* (queued/started/completed/failed/cancelled/dead-lettered) |
job id, report id, outcome | Info / Error | Completed/failed/cancelled | Requester inbox + subscribed channels |
report.schedule.* (create/update/delete/trigger/missed) |
user, schedule id | Info / Warn | Yes for changes | Owner on failure |
report.delivery.* (email/file/inbox attempt, retry, final failure) |
delivery id, channel, recipient scope | Info / Warn / Error | Final outcome | Owner on final failure |
data.read |
user, datasource/entity, rows, strategy, duration | Debug | No (covered by run) | No |
data.access.denied |
user, datasource/entity/field | Warn | Yes | No (UI shows generic denied) |
expression.error |
reportId, itemId, code | Warn | No | Designer inline |
security.scripts.enabled / config.changed |
admin, setting | Warn | Yes | Admin channel |
designer.session (open/close/autosave/recover) |
user, reportId | Debug / Info | No | UI on recovery offer |
collab.* (join/leave/conflict) |
user, reportId | Debug / Info | No | Presence UI |
| unhandled exception at any boundary | component, operation | Error/Critical with cause | Related action outcome Failed | UI generic message + reference ID |
Exclusions with rationale: individual designer edit commands are not audited (high volume; the save is audited); data row values are never logged.
Failure, data and delivery contracts
- Every record: stable event ID, UTC timestamp, severity, component/operation, correlation ID (run/request id), tenant.
- Exception ownership: the outermost boundary of an operation (Service method / API endpoint / job worker / designer
command executor) writes the primary diagnostic record with the preserved exception; inner layers return
OutcomewithCauseand do not log the same exception again. - Audit consistency: audit
outcomereflects what committed (save written and renamed = Succeeded; temp written but rename failed = Failed). Save/delete/export are blocked when audit persistence fails (BR8001). - Redaction: parameters flagged
sensitiveand all parameter values by default in audit (digest only); connection names allowed, connection strings never; exception messages from drivers pass through a redactor for credentials. - Notifications: retry with exponential backoff (max 5), deduplication by
deliveryId, dead-letter list visible to admins; requester always gets an inbox entry (INotificationService inbox is always on — Observed doc comment). - Single reporting path: all outcomes go through
IOperationReporter.ReportAsync(Log, then Audit, then UI). Nothing is swallowed (owner directive 2026-10-28; enforced byNoSwallowedExceptionsTests).ReportingPathTestsforbids a second logging mechanism (ILogger/Console/Trace/Debugoutside Operations and Cli) and asserts the reporter is the one type that owns all three channels. Fail-closed audit sites use the sameIReportAuditSinkcontract; they do not add another logger. - Failing channel: if the Log, Audit or UI channel throws, the reporter returns a
BR9012diagnostic for the caller to attach to its outcome, writes aCriticallog event with the preserved exception (when the log still works), writes aTraceline with the full exception, and raisesChannelFailedso hosts and health checks see it. Remaining channels still run. An audit failure blocks the audited action. Re-entrant reporting (a sink reporting from inside a write) is reported the same way instead of recursing. Default log when the host supplies none:TraceReportLog(nothing is discarded).
UI scope
Designer and viewers in Blazor, WinForms, WPF, Avalonia (and MAUI viewer): notifications scoped to the signed-in user/session; Blazor Server circuits must not share notification state; messages contain safe text + reference ID, never stack traces; severity mapping (info/success/warning/error); accessible live-region announcements in web, screen-reader friendly in desktop hosts.
Acceptance scenarios (tests planned in P07/P10/P14)
| Scenario | Required outcome | Status |
|---|---|---|
| Render throws in an item | Error log with cause + correlation; run Failed; audit run Failed; UI shows reference ID | not_run |
| Async export cancelled | Classified Cancelled (not Failed); temp files removed; inbox entry says cancelled | partial: Cancelled classification verified (OperationalScenarioTests (tests/Beep.Reports.Service.Tests); a bug was found and fixed: the service turned a cancelled step into a failure); temp-file cleanup and the inbox entry are not verified |
| Save conflict / denied / failed rename | Audit records Conflict / Denied / Failed truthfully | partial: a stale-ETag save is refused with the conflict code and audited as Failed (OperationalScenarioTests (tests/Beep.Reports.Service.Tests)); denied is covered by the store tests; failed rename is not run |
| Audit store down | Save/export blocked with BR8001; logged | partial: save blocked with BR8001 under a strict audit policy (OperationalScenarioTests (tests/Beep.Reports.Service.Tests)); export and the log line are not asserted |
| Email channel down | Delivery retried then dead-lettered; job result still available; owner notified via inbox | partial: three attempts, dead letter, warning on the job and a downloadable result verified (OperationalScenarioTests (tests/Beep.Reports.Service.Tests)); the owner gets an inbox message with the export attached (ExportJobRunner ownerNotices; subject text is English, not yet localised) |
| Duplicate job submission with same idempotency key | Same job returned; one audit record | verified (OperationalScenarioTests (tests/Beep.Reports.Service.Tests)): same job id, one export report |
| Sensitive parameter value | Not present in logs/audit/notifications | partial: password/token text is redacted in log and UI messages (OperationalScenarioTests (tests/Beep.Reports.Service.Tests); a bug was found and fixed: UI text was not redacted); audit properties and notification inbox are not asserted |
| Logger throws | No recursion; emergency trace written; operation outcome unaffected | verified (OperationalScenarioTests (tests/Beep.Reports.Service.Tests)): audit still written, failure returned as a diagnostic and raised once as ChannelFailed |
| Two users on Blazor Server | Each sees only own UI notifications | not_run |
| Server restart with queued jobs and schedules | Jobs resume or are marked failed truthfully; schedules preserved | verified (OperationalScenarioTests (tests/Beep.Reports.Service.Tests)) with the file-backed document store: interrupted job marked Failed with BR8100, schedule survives |