@@ -13,21 +13,15 @@ import type {
 // this write-path module doesn't pull in the request-path lib/index.ts.
 const AUDIT_LOG_DATA_DIR = 'src/audit-logs/data'
 
-// Builds the deduplicated "shared" format (entries pool + fields pool +
-// version index) from in-memory audit log data and writes it to disk.
-//
-// Output is deterministic: versions and pages are iterated in sorted order so
-// that the same input always produces byte-identical files. This lets the sync
-// pipeline (sync.ts) and the standalone rebuild script (rebuild-dedup.ts)
-// produce the exact same files, so the two can never drift apart.
+// Sort versions and pages so sync.ts and rebuild-dedup.ts write byte-identical
+// shared files from the same audit log data.
 export async function writeDeduplicatedAuditLogData(
   auditLogData: VersionedAuditLogData,
 ): Promise<void> {
   console.log(`\n▶️  Writing deduplicated audit log data...\n`)
 
-  // Build fields pool: unique fields arrays
   const fieldsPool: string[][] = []
-  const fieldsMap = new Map<string, number>() // JSON key → index
+  const fieldsMap = new Map<string, number>()
 
   function getFieldsIndex(fields: string[] | undefined): number | undefined {
     if (!fields || fields.length === 0) return undefined
@@ -39,9 +33,8 @@ export async function writeDeduplicatedAuditLogData(
     return index
   }
 
-  // Build entries pool: unique events (with fields replaced by index)
   const entriesPool: DeduplicatedAuditLogEntry[] = []
-  const entriesMap = new Map<string, number>() // JSON key → index
+  const entriesMap = new Map<string, number>()
 
   function getEntryIndex(event: AuditLogEventT): number {
     const fieldsIndex = getFieldsIndex(event.fields)
@@ -61,8 +54,6 @@ export async function writeDeduplicatedAuditLogData(
     return index
   }
 
-  // Build version index. Iterate versions and pages in sorted order so the
-  // output is deterministic regardless of the input's insertion order.
   const versionIndex: AuditLogVersionIndex = {}
   let totalEntries = 0
 
 
@@ -22,15 +22,13 @@ export const AUDIT_LOG_DATA_DIR = 'src/audit-logs/data'
 const auditLogEventsCache = new Map<string, Map<string, AuditLogEventT[]>>()
 const categorizedAuditLogEventsCache = new Map<string, Map<string, CategorizedEvents>>()
 
-// Shared dedup data, loaded once and shared across all versions.
 let sharedEntries: DeduplicatedAuditLogEntry[] | null = null
 let sharedFieldsPool: string[][] | null = null
 let sharedVersionIndex: AuditLogVersionIndex | null = null
-let sharedFormatAvailable: boolean | null = null // null = not checked yet
+let sharedFormatAvailable: boolean | null = null
 
-// A missing shared-format file is expected (per-version files are the fallback),
-// but a corrupt or unparseable file should fail loudly rather than silently
-// degrade to the per-version files and hide bad generated data.
+// Missing shared-format files fall back to per-version files; corrupt shared
+// data must fail loudly so generated data problems stay visible.
 function isFileNotFoundError(err: unknown): boolean {
   if (!(err instanceof Error) || !('code' in err)) return false
   const code = (err as NodeJS.ErrnoException).code
@@ -49,18 +47,17 @@ function loadSharedFormat(): boolean {
     sharedVersionIndex = readCompressedJsonFileFallback(
       path.join(AUDIT_LOG_DATA_DIR, 'version-index.json'),
     ) as AuditLogVersionIndex
-    // Freeze pool data so reconstructed events (which return references into
-    // these pools) can't be mutated by downstream code and leak across versions.
+    // Freeze reused field arrays so downstream mutations cannot leak across reconstructed events.
     Object.freeze(sharedEntries)
     Object.freeze(sharedFieldsPool)
     for (const fields of sharedFieldsPool) Object.freeze(fields)
     sharedFormatAvailable = true
   } catch (err) {
     if (isFileNotFoundError(err)) {
-      // Shared files don't exist, so fall back to per-version files silently.
+      // Missing shared files use per-version files silently.
       sharedFormatAvailable = false
     } else {
-      // Corrupt JSON, schema mismatch, and so on. Surface it instead of hiding it.
+      // Corrupt shared data fails loudly instead of hiding behind the per-version fallback.
       console.error('Failed to load shared audit log dedup format (corrupt data?):', err)
       throw err
     }
@@ -117,11 +114,9 @@ export type TitleResolutionContext = Context & {
   redirects: Record<string, string>
 }
 
-// Memoizes resolved reference links by their input string. The resolved markdown
-// only depends on the link string plus the pages/redirects indexes, and those
-// indexes are process-wide singletons that only change on deploy (a fresh
-// process). Without this, the audit-log pages re-render ~500 page titles on every
-// request (~90–150ms of repeated work). See docs-engineering#6650.
+// Cache reference-link rendering by input string because pages and redirects are
+// process-wide deploy-time indexes. Audit-log pages otherwise re-render about
+// 500 titles on each request, adding about 90 to 150 ms of warm-server work.
 const referenceLinksMarkdownCache = new Map<string, Promise<string>>()
 
 export function resolveReferenceLinksToMarkdown(
@@ -154,7 +149,6 @@ async function computeReferenceLinksToMarkdown(
     try {
       const page = findPage(link, context.pages, context.redirects)
       if (page) {
-        // Create a minimal context for rendering the title
         const renderContext = {
           currentLanguage: 'en',
           currentVersion: 'free-pro-team@latest',
@@ -164,11 +158,9 @@ async function computeReferenceLinksToMarkdown(
         const title = await page.renderProp('title', renderContext, { textOnly: true })
         markdownLinks.push(`[${title}](${link})`)
       } else {
-        // If we can't resolve the link, use the original URL
         markdownLinks.push(link)
       }
     } catch (error) {
-      // If resolution fails, use the original URL
       console.warn(
         `Failed to resolve title for link: ${link}`,
         error instanceof Error
@@ -202,7 +194,6 @@ async function resolveReferenceLinksToTitles(
     try {
       const page = findPage(link, context.pages, context.redirects)
       if (page) {
-        // Create a minimal context for rendering the title
         const renderContext = {
           currentLanguage: 'en',
           currentVersion: 'free-pro-team@latest',
@@ -212,11 +203,9 @@ async function resolveReferenceLinksToTitles(
         const title = await page.renderProp('title', renderContext, { textOnly: true })
         titles.push(title)
       } else {
-        // If we can't resolve the link, use the original URL
         titles.push(link)
       }
     } catch (error) {
-      // If resolution fails, use the original URL
       console.warn(
         `Failed to resolve title for link: ${link}`,
         error instanceof Error
@@ -232,22 +221,10 @@ async function resolveReferenceLinksToTitles(
   return titles.join(', ')
 }
 
-// get audit log event data for the requested page and version
-//
-// returns an array of event objects that look like this:
-//
-// [
-//   {
-//     action: 'account.billing_date_change',
-//     description: 'event description',
-//     docs_reference_links: 'event reference links'
-//   },
-// ]
 export function getAuditLogEvents(page: string, version: string): AuditLogEventT[] {
   const openApiVersion = getOpenApiVersion(version)
 
-  // If the data isn't cached for an entire version or a particular page, read
-  // the data from the shared dedup format or fall back to per-version JSON files
+  // Prefer shared dedup data, but keep per-version JSON as the compatibility fallback.
   if (!auditLogEventsCache.has(openApiVersion)) {
     auditLogEventsCache.set(openApiVersion, new Map())
   }
@@ -256,7 +233,6 @@ export function getAuditLogEvents(page: string, version: string): AuditLogEventT
     if (events) {
       auditLogEventsCache.get(openApiVersion)?.set(page, events)
     } else {
-      // Fall back to per-version JSON file
       const auditLogFileName = path.join(AUDIT_LOG_DATA_DIR, openApiVersion, `${page}.json`)
       auditLogEventsCache
         .get(openApiVersion)
@@ -265,27 +241,14 @@ export function getAuditLogEvents(page: string, version: string): AuditLogEventT
   }
 
   const auditLogEvents = auditLogEventsCache.get(openApiVersion)?.get(page)
-  // If an event doesn't yet have a description (value will be empty string or
-  // "N/A"), then we don't show the event.
+  // Hide events whose upstream description is missing or marked N/A.
   const filteredAuditLogEvents = auditLogEvents?.filter(
     (event) => event.description !== 'N/A' && event.description !== '',
   )
 
   return filteredAuditLogEvents || []
 }
 
-// get categorized audit log event data for the requested page and version
-//
-// Events are grouped by category; the category is the first part of the event
-// action (e.g. category is `repo` for the `repo.create` event) so we extract
-// the categories and then group events under those categories and return an
-// object that looks like this:
-//
-// {
-//   git: [ [Object], [Object] ],
-//   repo: [ [Object] ],
-//   user: [ [Object], [Object] ]
-// }
 export function getCategorizedAuditLogEvents(page: string, version: string): CategorizedEvents {
   const events = getAuditLogEvents(page, version)
   const openApiVersion = getOpenApiVersion(version)
@@ -362,24 +325,10 @@ export async function filterByAllowlistValues({
   return [...minimalEvents, ...currentEvents]
 }
 
-// Filters audit log events based on allowlist values and processes an
-// event's supported GHES versions.
-//
-// Mutates `currentGhesEvents` and updates it with any new filtered for audit
-// log events, the object maps GHES versions to page events for that version e.g.:
-//
-// {
-//   ghes-3.10': {
-//     organization: [...],
-//     enterprise: [...],
-//     user: [...],
-//   },
-//   ghes-3.11': {
-//     organization: [...],
-//     enterprise: [...],
-//     user: [...],
-//   },
-// }
+// Mutates currentGhesEvents so each supported GHES version maps the requested
+// page to filtered events. It ignores upstream GHES versions that docs no
+// longer supports because nightly syncs would otherwise recreate deprecated
+// src/audit-logs/data/ghes-X.Y directories.
 export async function filterAndUpdateGhesDataByAllowlistValues({
   eventsToCheck,
   allowListValue,
@@ -401,11 +350,6 @@ export async function filterAndUpdateGhesDataByAllowlistValues({
 }) {
   if (!currentGhesEvents) currentGhesEvents = {}
 
-  // Upstream `audit-log-allowlists/data/schema.json` lags docs's deprecation
-  // schedule, so events still list `ghes` keys for versions we've already
-  // dropped from `supported` in `enterprise-server-releases.ts`. Without this
-  // filter, the nightly sync would re-add `src/audit-logs/data/ghes-X.Y/`
-  // dirs for those deprecated versions. See docs-engineering#6562.
   const supportedGhesVersionSet = new Set(supportedGhesVersions)
 
   const seenByGhesVersion = new Map()
@@ -454,18 +398,6 @@ export async function filterAndUpdateGhesDataByAllowlistValues({
           }
         }
 
-        // we need to initialize as we go to build up the `minimalEvents`
-        // object that we'll return which will contain the GHES events for
-        // each versions + page type combos e.g. when processing GHES events
-        // for the organization events page we'll end up with something like
-        // this:
-        //
-        // {
-        //   'ghes-3.10': { organization: [Array] },
-        //   'ghes-3.11': { organization: [Array] },
-        //   'ghes-3.8': { organization: [Array] },
-        //   'ghes-3.9': { organization: [Array] }
-        // }
         if (!currentGhesEvents[fullGhesVersion]) {
           currentGhesEvents[fullGhesVersion] = {}
           currentGhesEvents[fullGhesVersion][auditLogPage] = []
@@ -495,17 +427,15 @@ function categorizeEvents(events: AuditLogEventT[]) {
   return categorizedEvents
 }
 
+// The generic API-only description is wrong for api.request, so it gets its own.
+// The schema has no field to identify it, so match on the action name.
 function processAndGetEventDescription(
   event: AuditLogEventT,
   allowlists: string[],
   pipelineConfig: PipelineConfig,
 ) {
   let description = event.description
 
-  // api.request is a unique event because it's an api_only event but is the only
-  // one of these events where the description we append isn't correct so we
-  // have to account for it separately.  There's not yet anything in the schema
-  // we can hook onto to treat it differently.
   if (
     (allowlists.includes('org_api_only') || allowlists.includes('business_api_only')) &&
     event.action !== 'api.request'
 
@@ -1,14 +1,8 @@
-// Rebuilds the deduplicated "shared" audit log format from the per-version page
-// files already on disk: src/audit-logs/data/shared/entries.json and
-// fields-pool.json, plus src/audit-logs/data/version-index.json.
-//
-// Unlike `sync-audit-log`, this does NOT fetch from github/audit-log-allowlists
-// and needs no GITHUB_TOKEN. Use it to regenerate the shared files when the
-// per-version JSON files have changed but the shared files are stale, for
-// example on an older audit-log-pipeline PR that predates the dedup format.
-// That is what makes the `deduplication` test fail.
-//
-//   npm run rebuild-audit-log-dedup
+// Rebuilds src/audit-logs/data/shared/entries.json, fields-pool.json, and
+// src/audit-logs/data/version-index.json from per-version JSON already on disk.
+// It does not fetch github/audit-log-allowlists and does not need GITHUB_TOKEN.
+// Use it when src/audit-logs/data/shared or version-index.json is stale.
+// Run with npm run rebuild-audit-log-dedup.
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
 import path from 'path'
 
@@ -17,7 +11,6 @@ import type { AuditLogEventT, VersionedAuditLogData } from '../types'
 
 const AUDIT_LOG_DATA_DIR = 'src/audit-logs/data'
 
-// Directories under the data dir that are not per-version event data.
 const NON_VERSION_DIRS = new Set(['shared'])
 
 function loadAuditLogDataFromDisk(): VersionedAuditLogData {