docs(kernel): document services.audit as the slot it actually is

[claude]

Fixes#9534

What was wrong

content/docs/kernel/runtime-services/audit-service.mdx was filed against the wrong seam. It is written as services.audit and lives under runtime-services/, so it reads as the kernel service slot — but every claim on it described SettingsAuditSink, a constructor-injected sink that service-settings receives directly and that is never registered as, or resolved from, that slot.

A reader following the page and calling getService('audit').record({ ... }) got a TypeError.

What the code actually says

Re-derived from source rather than from the card's phrasing:

Claim on the page	Truth	Where
Canonical source service-settings/src/settings-service.types.ts	packages/plugins/plugin-audit/src/auth-event-audit.ts	the slot's only registrant
record(entry)	recordAuthEvent(event)	AuthEventAuditSink, auth-event-audit.ts:112
action: 'set' | 'reset'	action: 'login' | 'logout'	AuthSessionAuditAction, auth-event-audit.ts:68
"a throwing sink propagates its error and fails the caller's write"	False for both shapes	see below
write-only; query history via services.data	correct — kept verbatim	—

Exactly one registrant, AuditPlugin (audit-plugin.ts:117), and exactly one in-repo consumer, plugin-auth (auth-plugin.ts:363, typed AuthEventAuditSurface, whose inline shape matches field-for-field). No other shape occupies the slot in this repo or in objectui, so "the registered service" is unambiguous.

⚠️ Worth flagging for anyone re-deriving this later: the card's own reproduction command, git grep "registerService(\s*'audit'", returns zero hits — the real registration spans two lines. The conclusion was right; the command printed in the card does not reproduce it. A line-based grep with a working positive control still reported nothing.

The claim the card did not name

The card listed the method and the event union. The sweep found a third, independent error in Typical Errors, which said the caller awaits record() without a surrounding try/catch. That is backwards for both shapes:

• recordAuthEvent catches every failure internally and never throws (auth-event-audit.ts:255-263);
• the settings service wraps its this.audit.record(...) call in try/catch (settings-service.ts:1459-1482), a guard added deliberately so a ledger cannot fail a write that already landed.

Also stale even as a description of the settings sink: the documented record() parameter list predates tenantId.

The rewritten Typical Errors section states the real posture — never throws, reports once per process then drops to debug, silently no-ops without an engine or a userId, and the datasource-split cause behind most failing inserts.

Deliberately unchanged

• Title services.audit and the page's path. The 2026-06 hand-written docs audit ruled services.* a chapter-wide descriptive convention rather than a literal registry key, and sibling pages follow it. Here it happens to also be the literal key. Keeping the path also keeps content/docs/kernel/index.mdx and meta.json valid, so this PR touches one file.
• experimental stability. Same audit ruled it a hand-asserted label with no code enum — not this card's call.
• The closing sys_audit_log / sys_activity query note, kept verbatim per the card.

A short "Not this: the settings audit sink" section now names the record() shape, its real canonical source, and why it is unreachable from this slot — so the shape the page used to carry stays discoverable, and the two are reconciled on the page instead of silently colliding.

Verification

Gate union re-derived from the actual changed path with node scripts/pm/dispatch-gates.mjs (identical to the dispatched list — no new families) and run at 0b4d38c12, the final commit:

EXIT[pnpm check:nul-bytes]=0
EXIT[pnpm check:docs-audit-scope]=0
EXIT[pnpm check:docs-redirects]=0
EXIT[pnpm check:role-word]=0
EXIT[pnpm --filter @objectstack/spec run check:empty-state]=0
EXIT[pnpm --filter @objectstack/spec run check:liveness]=0
EXIT[pnpm --filter @objectstack/spec run check:strictness-ledger]=0
EXIT[pnpm --filter @objectstack/spec run check:variant-docs]=0

check:docs-audit-scope confirms the page stays in the docs-accuracy-audit scope (179 hand-written docs in sync); check:role-word passes with the file still absent from the baseline (zero occurrences).

No changeset: content/docs/** only, no published package changes — skip-changeset applied.

Reported, not edited

Three findings are outside this card's one-file surface and were filed unassigned rather than ridden along:

• Filed as runtime-services/index.mdx points "Audit bridge" at the settings sink, the same wrong seam #9534 fixed on the page it links to #9588 — content/docs/kernel/runtime-services/index.mdx:46 points "Audit bridge" at settings-service.types.ts: the same wrong seam, one file up. After this PR the index and the page it links to contradict each other.
• Filed as Restore plugin-audit's README "See Also" link to runtime-services/audit-service, dropped in PR #9531 because the page was wrong #9589 — the "See Also" link PR docs(plugin-audit): the published README stops documenting an API, a row shape and an action vocabulary that do not exist (#9517) #9531 dropped from plugin-audit's published README may now be worth restoring, since the page it pointed at is no longer wrong. Blocked on this PR landing; that README is plugin-audit's shipped README documents an auditService API and a row shape that do not exist — a published compliance-capability claim with no runtime behind it #9517's file.
• Filed as The docs-accuracy audit verifies that a documented type exists and matches, but not that it is the type the page's seam resolves to — it passed audit-service.mdx with "None" #9590 (finding) — the 2026-06 docs-accuracy audit passed this page with an explicit "None", having verified the documented signature matched SettingsAuditSink.record EXACTLY. It did. The audit checks that a documented type exists and matches; it never asks whether that type is the one the page's seam resolves to.

---

Generated by Claude Code