docs(observability): disambiguate audit.ts from recordAuditEvent, document gate-check-publish audit decision

[JSONbored]

Summary

Re-investigated all four sub-items originally filed under #2908 against current main (it moved substantially since the audit that filed this issue). Two were already resolved by other merged work; two dead-export candidates turned out not to be dead on closer inspection. What's left is two doc-only clarifications:

• src/selfhost/audit.ts's logAudit is a stdout-only logger for exactly 4 queue-lifecycle events (job_complete/job_dead/job_error/job_rate_limited), not the durable audit_events DB writer — a naming trap that's easy to fall into (this repo's own prior audit did). Added a doc-comment cross-reference to recordAuditEvent in db/repositories.ts.
• The successful gate-check-run publish path (src/queue/processors.ts's recordPublishedGateCheckSummary) writes to check_summaries but not audit_events. Documented this as an intentional decision rather than a gap: check_summaries is the purpose-built canonical record for this specific, very-high-frequency event (repo/PR/headSha/checkRunId/conclusion/detailsUrl), and the downstream actions the verdict triggers (merge/close/hold) are already fully audited elsewhere. A parallel audit_events row would roughly double that table's volume with no new queryable information.

Already resolved by other work (verified, not touched here):

• Notification send/suppress/fail audit coverage — fix(notifications): route Discord actions through audited webhooks #2881 already added notify-discord.ts's auditExternalNotification, called for every Discord/Slack completed/denied/error outcome.

Not actually dead (correcting the original audit's classification after re-checking against current main):

• registerMetricMeta/resetMetrics (src/selfhost/metrics.ts) — extensively used by test setup/teardown across dozens of test files; resetMetrics in particular is essential test-isolation infrastructure, not dead code.
• DEFAULT_BUCKETS (src/selfhost/metrics.ts) — used internally as observe()'s own default parameter value; exported so a caller COULD override with a variant, not unused.
• flushOpenTelemetry (src/selfhost/otel.ts) — confirmed shutdownOpenTelemetry does NOT need to call it: NodeTracerProvider.shutdown() already flushes pending spans as part of its own OTel SDK contract, so this is a legitimate standalone "flush now without shutting down" utility, not a missing step.
• (I did confirm registerMetricMeta genuinely has zero production callers, meaning /metrics currently emits no Prometheus HELP/TYPE lines for any metric — real, but authoring HELP text for every metric in the system is a much larger, separate undertaking than this issue's scope; not attempted here.)

Resolves #2908. Part of the #1667 self-host review-stack roadmap.

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• Linked issue: chore(observability): audit-trail coverage for notifications, gate-verdict publish, and dead exports #2908.

Validation

• git diff --check
• npm run typecheck
• vitest run on tests touching both changed files (test/unit/queue.test.ts gate-check tests, test/unit/selfhost-sqlite-queue.test.ts, test/unit/selfhost-pg-queue.test.ts) — all passed
• npm run test:changed — 61 files / 1907 tests passed, 0 failed
• npm run actionlint / npm run test:workers / npm run build:mcp / npm run test:mcp-pack / npm audit / ui:* — not run locally; no workflow, worker-pool, MCP-package, or UI files touched. CI runs the full gate.

If any required check was skipped, explain why:

• test:coverage/test:ci not run locally — this diff is 13 added comment lines across 2 files, zero behavior change, so there is no new code path for Codecov's patch-coverage gate to evaluate.

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests. (N/A.)
• API/OpenAPI/MCP behavior is updated and tested where needed. (N/A — comments only.)
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks. (N/A.)
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs. (N/A — no changelog edit.)

[gittensory-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-04 05:56:52 UTC}

2 files · 1 AI reviewer · 1 blocker · readiness 100/100 · CI pending · blocked

⏸️ Suggested Action - Manual Review

• Maintainer test expectations unmet — Add or update tests, or attach passing validation output that satisfies the maintainer's test expectations.

Review summary
This is a doc-only clarification: it distinguishes the self-host stdout queue-lifecycle logger from the durable audit-event writer, and it documents why successful gate-check summary publication records only in check_summaries. The change does not alter runtime behavior, data writes, or public APIs, and the comments align with the stated intent of making an existing observability decision explicit. The main maintainability detail is that the processors comment is very long for an inline function comment, but it is still technically useful and non-blocking.

Nits — 4 non-blocking

• nit: src/queue/processors.ts:5238 embeds a long issue-specific rationale directly above the helper; consider trimming the inline comment to the invariant and moving the detailed volume/queryability explanation to a design note or issue reference.
• src/queue/processors.ts:5238 could be easier to maintain as a short invariant comment plus a pointer to chore(observability): audit-trail coverage for notifications, gate-verdict publish, and dead exports #2908, because the exact event frequency and table-volume rationale may drift over time.
• PR author also opened the linked issue — Link an issue that was opened by a different contributor, or provide a rationale for why this self-authored issue represents genuine discovery work.
• Code changes lack test evidence — Add focused regression tests or explain why existing coverage is sufficient.

Concerns raised — review before merging

• Maintainer test expectations unmet — Add or update tests, or attach passing validation output that satisfies the maintainer's test expectations.

Signal	Result	Evidence
Code review	❌ 1 blocker	1 reviewer
Linked issue	✅ Linked	#2908
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 60 registered-repo PR(s), 51 merged, 437 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 60 PR(s), 437 issue(s).
Gate result	❌ Blocking	Repo-configured hard blocker found.

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: not available
• Official Gittensor activity: 60 PR(s), 437 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.
• No action.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.05%. Comparing base (95179d8) to head (d52575b).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2933   +/-   ##
=======================================
  Coverage   96.05%   96.05%           
=======================================
  Files         259      259           
  Lines       28460    28460           
  Branches    10350    10350           
=======================================
  Hits        27338    27338           
  Misses        489      489           
  Partials      633      633           

Files with missing lines	Coverage Δ
src/queue/processors.ts	92.70% <ø> (ø)
src/selfhost/audit.ts	100.00% <ø> (ø)

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.