From 1275368151dddced3c606eaf74e97ef7a3d72c73 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 03:12:47 -0400
Subject: [PATCH] docs: document infra install helpers

---
 src/infra/approval-gateway-resolver.ts                           | 1 +
 src/infra/clawhub.ts                                             | 1 +
 src/infra/diagnostic-flags.ts                                    | 1 +
 src/infra/diagnostics-timeline.ts                                | 1 +
 src/infra/exec-approval-surface.ts                               | 1 +
 src/infra/fetch-headers.test.ts                                  | 1 +
 src/infra/fixed-window-rate-limit.test.ts                        | 1 +
 .../heartbeat-runner.respects-ackmaxchars-heartbeat-acks.test.ts | 1 +
 src/infra/install-from-npm-spec.ts                               | 1 +
 src/infra/install-mode-options.ts                                | 1 +
 src/infra/install-safe-path.test.ts                              | 1 +
 src/infra/install-safe-path.ts                                   | 1 +
 src/infra/node-pairing-authz.test.ts                             | 1 +
 src/infra/openclaw-root.ts                                       | 1 +
 src/infra/private-temp-workspace.ts                              | 1 +
 src/infra/provider-usage.fetch.shared.test.ts                    | 1 +
 src/infra/provider-usage.format.test.ts                          | 1 +
 src/infra/regular-file.ts                                        | 1 +
 src/infra/session-delivery-queue-recovery.ts                     | 1 +
 src/infra/system-run-approval-binding.test.ts                    | 1 +
 src/infra/update-package-manager.test.ts                         | 1 +
 src/infra/update-restart-sentinel-payload.ts                     | 1 +
 src/infra/windows-encoding.test.ts                               | 1 +
 src/infra/wsl.test.ts                                            | 1 +
 24 files changed, 24 insertions(+)

diff --git a/src/infra/approval-gateway-resolver.ts b/src/infra/approval-gateway-resolver.ts
index 89124804ce3d..78e7412f3ea5 100644
--- a/src/infra/approval-gateway-resolver.ts
+++ b/src/infra/approval-gateway-resolver.ts
@@ -1,3 +1,4 @@
+// Resolves exec and plugin approvals through the gateway client.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { withOperatorApprovalsGatewayClient } from "../gateway/operator-approvals-client.js";
 import { isApprovalNotFoundError } from "./approval-errors.js";
diff --git a/src/infra/clawhub.ts b/src/infra/clawhub.ts
index 688287b24f0c..eff6362dbb35 100644
--- a/src/infra/clawhub.ts
+++ b/src/infra/clawhub.ts
@@ -1,3 +1,4 @@
+// Fetches and validates ClawHub package metadata and artifacts.
 import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import os from "node:os";
diff --git a/src/infra/diagnostic-flags.ts b/src/infra/diagnostic-flags.ts
index 2ae0ae2ebe0c..ea0b3c7dc3a2 100644
--- a/src/infra/diagnostic-flags.ts
+++ b/src/infra/diagnostic-flags.ts
@@ -1,3 +1,4 @@
+// Resolves diagnostics feature flags from config and environment.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { normalizeUniqueStringEntriesLower } from "@openclaw/normalization-core/string-normalization";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
diff --git a/src/infra/diagnostics-timeline.ts b/src/infra/diagnostics-timeline.ts
index 0367c1853e31..68d50c40c53f 100644
--- a/src/infra/diagnostics-timeline.ts
+++ b/src/infra/diagnostics-timeline.ts
@@ -1,3 +1,4 @@
+// Records structured diagnostics timeline events and spans.
 import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
 import { mkdirSync } from "node:fs";
diff --git a/src/infra/exec-approval-surface.ts b/src/infra/exec-approval-surface.ts
index 83ce8ff5cb8a..a3c4d6b06062 100644
--- a/src/infra/exec-approval-surface.ts
+++ b/src/infra/exec-approval-surface.ts
@@ -1,3 +1,4 @@
+// Resolves native approval support for the initiating channel surface.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import {
   getChannelPlugin,
diff --git a/src/infra/fetch-headers.test.ts b/src/infra/fetch-headers.test.ts
index f118bf9607a4..769b2575bdeb 100644
--- a/src/infra/fetch-headers.test.ts
+++ b/src/infra/fetch-headers.test.ts
@@ -1,3 +1,4 @@
+// Covers request header normalization before fetch calls.
 import { describe, expect, it } from "vitest";
 import {
   normalizeHeadersInitForFetch,
diff --git a/src/infra/fixed-window-rate-limit.test.ts b/src/infra/fixed-window-rate-limit.test.ts
index 2146ccc78824..9a11af8dda8c 100644
--- a/src/infra/fixed-window-rate-limit.test.ts
+++ b/src/infra/fixed-window-rate-limit.test.ts
@@ -1,3 +1,4 @@
+// Covers fixed-window rate limiter boundaries.
 import { describe, expect, it } from "vitest";
 import { createFixedWindowRateLimiter } from "./fixed-window-rate-limit.js";
 
diff --git a/src/infra/heartbeat-runner.respects-ackmaxchars-heartbeat-acks.test.ts b/src/infra/heartbeat-runner.respects-ackmaxchars-heartbeat-acks.test.ts
index 01490ed04325..945d8dcc25b6 100644
--- a/src/infra/heartbeat-runner.respects-ackmaxchars-heartbeat-acks.test.ts
+++ b/src/infra/heartbeat-runner.respects-ackmaxchars-heartbeat-acks.test.ts
@@ -1,3 +1,4 @@
+// Covers heartbeat ack truncation limits.
 import fs from "node:fs/promises";
 import { describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
diff --git a/src/infra/install-from-npm-spec.ts b/src/infra/install-from-npm-spec.ts
index 347746ecc03e..36a81abfdeb1 100644
--- a/src/infra/install-from-npm-spec.ts
+++ b/src/infra/install-from-npm-spec.ts
@@ -1,3 +1,4 @@
+// Installs validated registry npm specs through archive install helpers.
 import type { NpmIntegrityDriftPayload } from "./npm-integrity.js";
 import {
   finalizeNpmSpecArchiveInstall,
diff --git a/src/infra/install-mode-options.ts b/src/infra/install-mode-options.ts
index 05463635a82b..3d524ef3b414 100644
--- a/src/infra/install-mode-options.ts
+++ b/src/infra/install-mode-options.ts
@@ -1,3 +1,4 @@
+// Resolves common install/update mode options.
 type InstallMode = "install" | "update";
 
 type InstallModeOptions<TLogger> = {
diff --git a/src/infra/install-safe-path.test.ts b/src/infra/install-safe-path.test.ts
index 82538979223a..654a5686c3f9 100644
--- a/src/infra/install-safe-path.test.ts
+++ b/src/infra/install-safe-path.test.ts
@@ -1,3 +1,4 @@
+// Covers safe plugin install path normalization and boundary checks.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
diff --git a/src/infra/install-safe-path.ts b/src/infra/install-safe-path.ts
index 4686c649592d..747409d708e3 100644
--- a/src/infra/install-safe-path.ts
+++ b/src/infra/install-safe-path.ts
@@ -1,3 +1,4 @@
+// Provides safe path helpers for plugin installation targets.
 import "./fs-safe-defaults.js";
 export {
   assertCanonicalPathWithinBase,
diff --git a/src/infra/node-pairing-authz.test.ts b/src/infra/node-pairing-authz.test.ts
index c2e0ba854765..d7fb222b34ab 100644
--- a/src/infra/node-pairing-authz.test.ts
+++ b/src/infra/node-pairing-authz.test.ts
@@ -1,3 +1,4 @@
+// Covers scope requirements for node pairing approvals.
 import { describe, expect, it } from "vitest";
 import { resolveNodePairApprovalScopes } from "./node-pairing-authz.js";
 
diff --git a/src/infra/openclaw-root.ts b/src/infra/openclaw-root.ts
index 79d6de3cc5da..3af3ef083671 100644
--- a/src/infra/openclaw-root.ts
+++ b/src/infra/openclaw-root.ts
@@ -1,3 +1,4 @@
+// Resolves the OpenClaw package root from runtime and package metadata.
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { openClawRootFs, openClawRootFsSync } from "./openclaw-root.fs.runtime.js";
diff --git a/src/infra/private-temp-workspace.ts b/src/infra/private-temp-workspace.ts
index f46a03bb964e..ab2638413f45 100644
--- a/src/infra/private-temp-workspace.ts
+++ b/src/infra/private-temp-workspace.ts
@@ -1,3 +1,4 @@
+// Exposes private temp workspace helpers with fs-safe defaults.
 import "./fs-safe-defaults.js";
 
 // Private temp workspaces isolate downloads and generated artifacts under a
diff --git a/src/infra/provider-usage.fetch.shared.test.ts b/src/infra/provider-usage.fetch.shared.test.ts
index d05795909c0e..0d31f4911017 100644
--- a/src/infra/provider-usage.fetch.shared.test.ts
+++ b/src/infra/provider-usage.fetch.shared.test.ts
@@ -1,3 +1,4 @@
+// Covers shared provider usage fetch parsing and error snapshots.
 import { MAX_TIMER_TIMEOUT_MS } from "@openclaw/normalization-core/number-coercion";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { withFetchPreconnect } from "../test-utils/fetch-mock.js";
diff --git a/src/infra/provider-usage.format.test.ts b/src/infra/provider-usage.format.test.ts
index 9c2cce9bcaf8..c058d3d57d0f 100644
--- a/src/infra/provider-usage.format.test.ts
+++ b/src/infra/provider-usage.format.test.ts
@@ -1,3 +1,4 @@
+// Covers provider usage report formatting.
 import { describe, expect, it } from "vitest";
 import {
   formatUsageReportLines,
diff --git a/src/infra/regular-file.ts b/src/infra/regular-file.ts
index ecbd539822a4..9f7d3167981e 100644
--- a/src/infra/regular-file.ts
+++ b/src/infra/regular-file.ts
@@ -1,3 +1,4 @@
+// Exposes regular-file IO helpers with fs-safe defaults.
 import "./fs-safe-defaults.js";
 
 // Regular-file IO helpers reject symlinks and non-file targets before reads or
diff --git a/src/infra/session-delivery-queue-recovery.ts b/src/infra/session-delivery-queue-recovery.ts
index 5951f0cb53e0..eecf8d5f2bdb 100644
--- a/src/infra/session-delivery-queue-recovery.ts
+++ b/src/infra/session-delivery-queue-recovery.ts
@@ -1,3 +1,4 @@
+// Recovers queued session deliveries after process crashes.
 import {
   resolveDateTimestampMs,
   resolveExpiresAtMsFromDurationMs,
diff --git a/src/infra/system-run-approval-binding.test.ts b/src/infra/system-run-approval-binding.test.ts
index fe1eee52ce1a..193686dcd0c9 100644
--- a/src/infra/system-run-approval-binding.test.ts
+++ b/src/infra/system-run-approval-binding.test.ts
@@ -1,3 +1,4 @@
+// Covers system-run approval binding normalization and matching.
 import { describe, expect, it } from "vitest";
 import {
   buildSystemRunApprovalBinding,
diff --git a/src/infra/update-package-manager.test.ts b/src/infra/update-package-manager.test.ts
index a495b6e7fc8a..59959d32b36c 100644
--- a/src/infra/update-package-manager.test.ts
+++ b/src/infra/update-package-manager.test.ts
@@ -1,3 +1,4 @@
+// Covers package manager resolution for update build flows.
 import { describe, expect, it } from "vitest";
 import {
   resolveUpdateBuildManager,
diff --git a/src/infra/update-restart-sentinel-payload.ts b/src/infra/update-restart-sentinel-payload.ts
index 55723970cc54..3929af5c9249 100644
--- a/src/infra/update-restart-sentinel-payload.ts
+++ b/src/infra/update-restart-sentinel-payload.ts
@@ -1,3 +1,4 @@
+// Builds restart sentinel payloads for update handoff reporting.
 import {
   buildRestartSuccessContinuation,
   formatDoctorNonInteractiveHint,
diff --git a/src/infra/windows-encoding.test.ts b/src/infra/windows-encoding.test.ts
index b323afe879d5..4ed152b95565 100644
--- a/src/infra/windows-encoding.test.ts
+++ b/src/infra/windows-encoding.test.ts
@@ -1,3 +1,4 @@
+// Covers Windows command-output code page parsing and decoding.
 import { describe, expect, it } from "vitest";
 import {
   createWindowsOutputDecoder,
diff --git a/src/infra/wsl.test.ts b/src/infra/wsl.test.ts
index dec063cdb54f..ab23068c8e66 100644
--- a/src/infra/wsl.test.ts
+++ b/src/infra/wsl.test.ts
@@ -1,3 +1,4 @@
+// Covers WSL detection from platform and release files.
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { captureEnv } from "../test-utils/env.js";
 import { mockProcessPlatform } from "../test-utils/vitest-spies.js";