docs(permissions): state each read-audit degradation's real reporting granularity

[objectstack-fleet]

Fixes #19216
Clause-②: no

What

content/docs/permissions/record-view-auditing.mdx, section "Failure posture": the lead-in said both read-audit degradations are reported once per process. That was true of one and false of the other, measured on origin/main 502f179cc:

degradation	implementation (packages/plugins/plugin-audit/src/read-audit.ts)	real granularity
buffer overflow	:240 let overflowReported = false; (one boolean in the batcher closure; repeats go to debug)	once per process
failed ledger write	:542 const reportedReadAuditFailureCauses = new Set<string>();, keyed by auditFailureCauseKey('sys_audit_log', err) (the error code, uncoded errors collapse to one bucket); docblock at :499 says once per CAUSE	once per distinct cause

The lead-in now says only what holds for both (neither is retried; each is reported once), and each bullet states its own granularity. The ledger-write bullet uses the same definition of "cause" as the sibling page content/docs/kernel/runtime-services/audit-service.mdx (recordAuthEvent), so the two pages agree. The implementation matches its own docblock, so no code changed. Frontmatter and headings are untouched.

Changeset

Docs-only. The one changed path is under content/docs/**, and no published package source or files[] entry is touched, so this is skip-changeset territory.

Verification

Gates derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands (change set from merge base 502f179cc: 1 path). All 44 derived families ran on head ceefc645 and every one exited 0, including pnpm check:doc-authoring, pnpm check:doc-anchors and pnpm check:nul-bytes. Reconciliation with --ran (exit codes recorded): "44 derived, 44 run, 0 NOT-MEASURED, 0 UNRUN". Two gates first answered PREREQUISITE NOT MET (exit 3: check:docs-transcript-drift, which needs @objectstack/lint dist, and spec check:skill-examples, which needs @objectstack/client-react dist). After those closures were built under the verify lock, both were re-run and exited 0. The control-byte self-scan of the changed file found nothing.

Acceptance notes

• "Once per process" for overflow means once per batcher instance, and installReadAuditWriter creates one batcher per install. In practice that is one per process, so the page keeps the wording the card accepted.

---

Generated by Claude Code

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: ceefc6454207908b5a1772ea2c8ab297c74d2a70

① Derived judgments

• "Neither degradation is retried": overflow path drops oldest and only logs (packages/plugins/plugin-audit/src/read-audit.ts:294-298); failed flush is reported and swallowed by persist's contract (:274-279, :566-588). True.
• "Buffer overflow … warn logged once per process; later overflows drop to debug": :240 let overflowReported = false;, :242-244 repeat → logger?.debug?.(...), :246-256 first → warn. One batcher per installReadAuditWriter, so once per process. True.
• "Failed ledger write … reported once per cause, at error where the host's logger provides one and at warn where it does not": :542 reportedReadAuditFailureCauses (a new Set of strings), :558-563 cause key / debug on repeat, :590-594 logger.error else logger?.warn?.. True.
• "A cause is the error's code (every uncoded failure collapses into one bucket)": packages/plugins/plugin-audit/src/audit-writers.ts:809-816 auditFailureCauseKey keys on code, non-scalar/absent → '(no code)'. True; wording matches the sibling content/docs/kernel/runtime-services/audit-service.mdx:76-80.
• "a repeat … drops to debug while a new cause gets its own line, once": :559-561, docblock :499-500. True.
• Diff is body prose only in content/docs/permissions/record-view-auditing.mdx (no frontmatter, no heading changed); no accept set or public surface touched; Clause-②: no is right. No generated/release/governed path.

② Semver level

Docs-only, one content/docs/** file; not in any package files[]; no .changeset/*.md added or edited. No changeset is correct; skip-changeset is the route.

③ Boundary flags

• none. Card fenced frontmatter/headings (epic epic(docs-site): the site is technically un-indexable — fix robots/sitemap/canonical/OG first, then the keyword shape #12243); diff stays inside body prose. Pre-existing "fixed ceiling of 10,000" wording is unchanged (default maxBufferedEvents = 10_000 at :229, configurable) and not a claim this diff makes.

Implemented-by: claude/issue-19216-read-audit-once-per-cause
Reviewed-by: session_01VDtqoecgES7ScQYGbFVDRv

VERDICT: PASS

Isolated at-tier reviewer, adopted by the domain:devx#1 seat. Reviewed with the seat's own ACCEPT excluded from its inputs.

---

Generated by Claude Code