docs: document diagnostics logs handlers

steipete · steipete · commit 7c5658bd98eb · 2026-05-31T08:50:03.000-04:00
diff --git a/src/gateway/server-methods/diagnostics.ts b/src/gateway/server-methods/diagnostics.ts
@@ -5,9 +5,12 @@ import {
 } from "../../logging/diagnostic-stability.js";
 import type { GatewayRequestHandlers } from "./types.js";
 
+/** Gateway handler for payload-free stability diagnostics. */
 export const diagnosticsHandlers: GatewayRequestHandlers = {
   "diagnostics.stability": async ({ params, respond }) => {
     try {
+      // Normalization owns parameter bounds so malformed diagnostic requests
+      // return a client error instead of leaking logging internals.
       const query = normalizeDiagnosticStabilityQuery(params);
       respond(true, getDiagnosticStabilitySnapshot(query), undefined);
     } catch (err) {
diff --git a/src/gateway/server-methods/logs.ts b/src/gateway/server-methods/logs.ts
@@ -7,6 +7,7 @@ import {
 import { readConfiguredLogTail } from "../../logging/log-tail.js";
 import type { GatewayRequestHandlers } from "./types.js";
 
+/** Gateway handler for bounded reads from the configured gateway log. */
 export const logsHandlers: GatewayRequestHandlers = {
   "logs.tail": async ({ params, respond }) => {
     if (!validateLogsTailParams(params)) {
@@ -23,6 +24,8 @@ export const logsHandlers: GatewayRequestHandlers = {
 
     const p = params as { cursor?: number; limit?: number; maxBytes?: number };
     try {
+      // The log-tail reader enforces cursor/byte limits and source selection;
+      // the handler only maps protocol params and failure shape.
       const result = await readConfiguredLogTail({
         cursor: p.cursor,
         limit: p.limit,
