From aeaccf6d360e9475b54adfd61096a9cef1e0ab25 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 7 Jul 2026 22:13:01 +0800
Subject: [PATCH] docs: satisfy the new export-JSDoc gate on the assertion
 signature

Master's verify-export-jsdoc (landed mid-stack) wants @returns on every
exported function including asserts-returning ones; document the narrowing.
---
 packages/core/tools/src/json-schema.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/core/tools/src/json-schema.ts b/packages/core/tools/src/json-schema.ts
index bc0da537e1..4c1036773b 100644
--- a/packages/core/tools/src/json-schema.ts
+++ b/packages/core/tools/src/json-schema.ts
@@ -256,6 +256,8 @@ function checkSchemaNode(node: unknown, path: string, violations: string[], seen
  * (`UNSUPPORTED_SCHEMA`) listing EVERY violation; returns (and narrows) on
  * success. Call this at the seam boundary, before any child is created.
  * @param schema - the caller-supplied schema (unknown until asserted).
+ * @returns nothing — the assertion signature narrows `schema` to
+ * {@link StructuredOutputSchema} in the caller's scope on normal return.
  */
 export function assertSupportedOutputSchema(schema: unknown): asserts schema is StructuredOutputSchema {
   const violations: string[] = []