docs(v2): cut duplicated and non-load-bearing comment prose

Five rationales were written three to five times each by parallel agents
that could not see one another. Each now has one home and the rest point
at it:

- HEAD existence oracle -> the headSafe option on defineV2JsonRoute
- cursor query binding -> cursorScopeKey in lib/api/cursor-binding.ts
- storage-key prefix budget -> buildStorageKeySegment
- NUL / U+0000 -> the containsNulCharacter predicate
- blank and duplicate query values -> their own implementations

Also drops changelog-in-source (prose narrating what the code used to
do), anchorless module headers attached to no declaration, rejected-
alternative essays, and @PARAM tags that only restate the signature.

Comments only: the diff contains no executable-code change.

Author: waleedlatif1

apps/sim/app/api/v2/billing/logs/route.test.ts

@@ -148,9 +148,8 @@ describe('GET /api/v2/billing/logs', () => {
   })
 
   /**
-   * The envelope check used to accept any string as the inner token, so an
-   * empty one passed it and then read as falsy in the ledger reader: no cursor
-   * condition was applied and the caller walked the first page again — the very
+   * An empty inner token reads as falsy in the ledger reader, so no cursor
+   * condition is applied and the caller walks the first page again — the very
    * failure {@link UNKNOWN_CURSOR_MESSAGE} exists to make visible.
    */
   it('rejects a cursor whose inner token is empty instead of restarting at page one', async () => {

apps/sim/app/api/v2/files/[fileId]/route.test.ts

@@ -121,11 +121,10 @@ describe('v2 single-file routes', () => {
   })
 
   /**
-   * The download `HEAD` short-circuit used to sit between admission and parsing,
-   * so it answered before the workspace-scoped file resolution that lives in the
-   * use case. Any valid API key therefore drew a bodiless 200 for a file id it
-   * cannot reach, while the `GET` for the same URL answered 404. These pin the
-   * probe to the answer the download gives, and to still not auditing one.
+   * A download `HEAD` answered before the use case's workspace-scoped file
+   * resolution is an existence oracle: any valid API key draws a bodiless 200
+   * for a file id whose `GET` answers 404. These pin the probe to the answer the
+   * download gives, and to still not auditing one.
    */
   it('answers an authorized HEAD bodiless without auditing a download', async () => {
     const response = await GET(headRequest(`workspaceId=${WORKSPACE_ID}`), context)

apps/sim/app/api/v2/files/[fileId]/route.ts

@@ -29,16 +29,8 @@ export const revalidate = 0
  *
  * A generated doc whose artifact is still compiling renders `CONFLICT`; retry.
  *
- * Downloading is not a safe read: it records a `FILE_DOWNLOADED` audit event and
- * pulls the bytes out of object storage. Next aliases `HEAD` onto `GET`, and RFC
- * 9110 §9.2.1 defines `HEAD` as safe, so this route declares itself not
- * head-safe. A `HEAD` is admitted, parsed, and authorized through
- * `downloadWorkspaceFileStream.authorize` — the same workspace-scoped file
- * resolution and access check the `GET` performs — then answered bodiless
- * without auditing or fetching. Without the not-head-safe declaration an uptime
- * monitor walking the documented URL list would fabricate a download event on
- * every probe; without the authorization step the probe would instead confirm a
- * file id the caller has no right to know exists.
+ * `headSafe: false` because downloading records a `FILE_DOWNLOADED` audit event
+ * and pulls the bytes out of object storage.
  */
 export const GET = defineV2BinaryRoute({
   contract: v2DownloadFileContract,

apps/sim/app/api/v2/files/route.test.ts

@@ -106,9 +106,9 @@ describe('/api/v2/files', () => {
 
   /**
    * `?limit=` is not `limit` omitted. `Number('') === 0`, and this list clamps
-   * out-of-range values, so the blank used to reach the query as `LIMIT 1` and
-   * return a single row where the omitted param returns a hundred — a silently
-   * wrong page, not an error. Whitespace-only is the same value.
+   * out-of-range values, so an unrejected blank reaches the query as `LIMIT 1`
+   * and returns a single row where the omitted param returns a hundred — a
+   * silently wrong page, not an error. Whitespace-only is the same value.
    */
   it.each(['limit=', 'limit=%20', 'sortBy=', 'cursor='])(
     'rejects the blank query value %s instead of coercing it',

apps/sim/app/api/v2/knowledge/search/route.test.ts

@@ -168,10 +168,9 @@ describe('POST /api/v2/knowledge/search', () => {
   })
 
   /**
-   * `rerankerEnabled` on its own used to satisfy the schema, fail the use case's
-   * model guard, and answer 200 in plain vector order — after paying for the
-   * widened candidate retrieval. The default closes that, matching the internal
-   * search contract.
+   * Without the default, `rerankerEnabled` alone satisfies the schema, fails the
+   * use case's model guard, and answers 200 in plain vector order — after paying
+   * for the widened candidate retrieval.
    */
   it('defaults the reranker model so enabling reranking is enough to run it', async () => {
     const response = await POST(
@@ -280,9 +279,9 @@ describe('POST /api/v2/knowledge/search', () => {
    * The search body is strict, so an undeclared key is refused rather than
    * stripped. That matters most for a bring-your-own reranker key: dropping it
    * silently left the caller believing the secret it sent was in use. It
-   * matters for an ordinary mis-spelling too — `rerankerenabled` used to parse
-   * to 200 with reranking off, and `topk` with `topK` back at its default, both
-   * of which change what the search is billed.
+   * matters for an ordinary mis-spelling too: a stripped `rerankerenabled` is a
+   * 200 with reranking off, and a stripped `topk` leaves `topK` at its default —
+   * both change what the search is billed.
    */
   it('refuses a caller-supplied reranker key instead of silently dropping it', async () => {
     const response = await POST(

apps/sim/app/api/v2/logs/route.test.ts

@@ -196,9 +196,8 @@ describe('GET /api/v2/logs', () => {
   })
 
   /**
-   * The envelope check used to accept any string as the inner token, so an
-   * empty one passed it and then read as falsy in the domain codec: no cursor
-   * condition was applied and the caller silently got page one back, with a
+   * An empty inner token reads as falsy in the domain codec, so no cursor
+   * condition is applied and the caller silently gets page one back, with a
    * `nextCursor` inviting it to do the same thing forever.
    */
   it('rejects a cursor whose inner token is empty instead of restarting at page one', async () => {

apps/sim/app/api/v2/mcp-servers/[id]/tools/route.test.ts

@@ -128,12 +128,11 @@ describe('/api/v2/mcp-servers/[id]/tools', () => {
   })
 
   /**
-   * The `HEAD` short-circuit used to sit between admission and parsing, so it
-   * answered before resource authorization ever ran — which lives in the use
-   * case. Any valid API key therefore drew a bodiless 200 for a server id in a
-   * workspace it cannot read, a server id that does not exist, and a principal
-   * kind this operation refuses outright, while the `GET` for the same URL
-   * answered 403 or 404. These four pin the probe to the answer the `GET` gives.
+   * A `HEAD` answered before the use case's resource authorization is an
+   * existence oracle: any valid API key draws a bodiless 200 for a server id in
+   * a workspace it cannot read, for one that does not exist, and for a principal
+   * kind this operation refuses outright. These four pin the probe to the answer
+   * the `GET` gives.
    */
   it('does not confirm a server to a principal kind the operation refuses', async () => {
     mocks.authorizeDiscover.mockRejectedValueOnce(new WorkspaceApiKeyAuthorizationError())
@@ -260,11 +259,10 @@ describe('/api/v2/mcp-servers/[id]/tools', () => {
   })
 
   /**
-   * The 503 wording used to be selected by searching the error message for
-   * `cooldown`. `McpConnectionError` interpolates the server's display name into
-   * that message, so a server the caller happened to name after the word
-   * borrowed the negative-cache wording and told them to wait out a cooldown
-   * that was never entered.
+   * `McpConnectionError` interpolates the server's display name into its
+   * message, so selecting the 503 wording by searching that message for
+   * `cooldown` hands a server named after the word the negative-cache wording
+   * for a cooldown it was never in.
    */
   it('does not read cooldown wording out of a server display name', async () => {
     mocks.discover.mockRejectedValueOnce(new McpConnectionError('ECONNREFUSED', 'Cooldown Docs'))

apps/sim/app/api/v2/mcp-servers/[id]/tools/route.ts

@@ -14,17 +14,8 @@ export const revalidate = 0
  * as `mcp-<hash>` from the workspace and endpoint URL, and the registration
  * contract requires a URL.
  *
- * Discovery is not a safe read: it opens a live connection to the registered
- * endpoint and records the outcome on the server row. Next aliases `HEAD` onto
- * `GET`, and RFC 9110 §9.2.1 defines `HEAD` as safe, so this route declares
- * itself not head-safe. A `HEAD` is admitted, parsed, and authorized through
- * `discoverMcpServerToolsUseCase.authorize` — the same principal-kind check,
- * server resolution, and workspace access check the `GET` performs — then
- * answered bodiless without connecting or writing. Without the not-head-safe
- * declaration an uptime monitor walking the documented URL list would drive
- * outbound third-party traffic and mutate rows on every probe; without the
- * authorization step the probe would instead confirm that a server id exists in
- * a workspace the caller cannot read.
+ * `headSafe: false` because discovery opens a live connection to the registered
+ * endpoint and records the outcome on the server row.
  */
 export const GET = defineV2JsonRoute({
   contract: v2ListMcpServerToolsContract,

apps/sim/app/api/v2/mcp-servers/utils.ts

@@ -54,10 +54,9 @@ export const MCP_SERVER_REAUTHORIZATION_REQUIRED = 'MCP_SERVER_REAUTHORIZATION_R
  * Every branch returns a constant, so an upstream message — which may quote a
  * hostname, a token endpoint, or a stack — never reaches the caller.
  *
- * Selection is typed for the same reason classification is. The cooldown branch
- * used to search the message for `cooldown`, but `McpConnectionError`
- * interpolates the server's display name into its message, so a server a caller
- * named after the word was told to wait out a cooldown it was never in.
+ * Selection is typed, never matched on message text: `McpConnectionError`
+ * interpolates the server's display name into its message, so a server named
+ * after the word `cooldown` would select the cooldown branch it is not in.
  */
 function unreachableServerMessage(error: unknown): string {
   if (isTimeoutError(error)) return 'The MCP server took too long to respond'

apps/sim/app/api/v2/skills/route.test.ts

@@ -314,12 +314,9 @@ describe('/api/v2/skills', () => {
   })
 
   /**
-   * The workspace-key create used to be the case this file pinned analytics
-   * against: it succeeded, and the assertion was that no `skill_created` event
-   * was attributed to a principal with no human subject. `skills.create` now
-   * denies the key outright, so what needs pinning here is the surface's half of
-   * that — the refusal reaches the caller as the operation's own 403, and a
-   * create that never happened emits nothing.
+   * `skills.create` denies a workspace key outright, so what this pins is the
+   * surface's half: the refusal reaches the caller as the operation's own 403,
+   * and a create that never happened emits no analytics.
    */
   it('refuses a workspace-key create and records no analytics for it', async () => {
     mocks.create.mockRejectedValueOnce(