From 657aa6de74eecbff9a7819e619fbde7b75976602 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 19 Sep 2026 23:22:16 +0000 Subject: [PATCH] docs(kernel): correct the audit-write failure report granularity to once per cause `content/docs/kernel/runtime-services/audit-service.mdx` described the failed ledger insert of `recordAuthEvent` as reported at `error` level "once per process", with every later failure dropping to `debug`. That stopped being true when the auth-event sink's dedupe was re-keyed from a process-wide boolean to a per-cause key in `packages/plugins/plugin-audit/src/auth-event-audit.ts`. The bullet now states the real granularity: once per cause, a cause being the error `code` plus the object the row is about; a repeat of an already-reported cause still degrades to `debug`, and a new cause gets its own `error` line once. Claude-Session: https://claude.ai/code/session_017ef78bLdybu3AffehKkhfk Co-authored-by: Claude --- .../docs/kernel/runtime-services/audit-service.mdx | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/content/docs/kernel/runtime-services/audit-service.mdx b/content/docs/kernel/runtime-services/audit-service.mdx index a5d01e85a55..9839f70857f 100644 --- a/content/docs/kernel/runtime-services/audit-service.mdx +++ b/content/docs/kernel/runtime-services/audit-service.mdx @@ -73,10 +73,13 @@ error, so every failure is caught, and callers do not need a surrounding `try`/` The consequences are worth knowing precisely, because none of them are visible from the caller's side: -- A failed ledger insert is reported at `error` level **once per process** — every later - failure drops to `debug` — and the row is simply lost. Nothing retries it. The sign-in - itself succeeded and returned 200, so the shipped `auth_events` list view and the - system-overview widgets keep showing an empty, healthy-looking screen. +- A failed ledger insert is reported at `error` level **once per cause** — a cause is the + error's `code` plus the object the row is about, so every uncoded failure collapses into + one bucket and the object is always `sys_session` on this seam — and the row is simply + lost. Nothing retries it. A repeat of an **already-reported** cause drops to `debug`; a + **new** cause gets its own `error` line, once. The sign-in itself succeeded and returned + 200, so the shipped `auth_events` list view and the system-overview widgets keep showing + an empty, healthy-looking screen. - The call **silently no-ops** when no data engine resolves, or when `userId` is absent. A caller that passes an event without a subject records nothing and is told nothing. - The most common cause of a failing insert is a datasource split rather than a broken