docs(tools): widen the ungated language-prose list and correct three JSDoc claims

packages/core/tools/src/code-mode.ts

@@ -72,10 +72,10 @@ interface RunCodeFlavor {
 }
 
 /**
- * The TypeScript flavor: the historical default, and the fallback the schema
- * harvest degrades to when no runtime is mounted (the doc-catalog generator
- * reads `schemas()` without one). A real assembly always resolves a runtime
- * first, so the model never sees this fallback outside its own language.
+ * The TypeScript flavor: the historical default, and the fallback for a schema
+ * read with no runtime mounted ({@link resolveFlavor} owns which readers reach
+ * that). A real assembly always resolves a runtime first, so the model never
+ * sees this fallback outside its own language.
  */
 const TYPESCRIPT_FLAVOR: RunCodeFlavor = {
   description:
@@ -301,8 +301,9 @@ export interface RunCodeBridgeOptions {
   requireRuntime: () => CodeRuntime
   /**
    * Reads `ctx.codeRuntime` without throwing: `undefined` when none is
-   * mounted. Lets schema emission tell "no runtime" (the doc-catalog harvest,
-   * degrade to TS) apart from "unknown language" (fail loud).
+   * mounted. Lets schema emission tell "no runtime" (degrade to TS; the
+   * readers that reach it are {@link resolveFlavor}'s) apart from "unknown
+   * language" (fail loud).
    */
   peekRuntime: () => CodeRuntime | undefined
   /** The run's overlap cap for parallel-classified sub-calls (the registry passes its validated `maxParallelSubCalls`). */

packages/core/tools/src/index.ts

@@ -37,10 +37,11 @@ import { renderToolsSdkPy } from './py-types.ts'
  * its `run_code` schema strings — plus the renderer function this table points
  * at. The `satisfies` clause pins this table's key set to that union, which
  * the flavor table is checked against too, so any of the three left out is a
- * typecheck failure. A further edit is not checked anywhere: the seam's
- * well-known-value list — `dsh-code-runtime`'s README pair, its
+ * typecheck failure. What no check reaches is the prose that names the values
+ * instead of deriving them: the seam's `dsh-code-runtime` README pair, its
  * `CodeRuntime.language` JSDoc, and `docs/core-data-structures/code-runtime.md`
- * with its zh pair — names the languages this table presents.
+ * with its zh pair, plus this package's own README pair and the
+ * {@link Config.mode} JSDoc.
  */
 const SDK_RENDERERS: Record<string, (schemas: ToolSdkSchema[]) => string> = {
   typescript: renderToolsSdk,

packages/core/tools/src/py-types.ts

@@ -60,7 +60,10 @@ const IDENTIFIER = /^[\p{XID_Start}_]\p{XID_Continue}*$/u
  * {@link UNPRINTABLE}, {@link LONE_SURROGATE} and {@link MAX_LIST_NESTING}
  * exist for. Both properties carry it: a character added only to `XID_Continue`
  * passes the trailing `\p{XID_Continue}*` in a tail position and fails the same
- * way. A CPython newer than the engine only routes a legal name to the
+ * way — U+200C ZWNJ and U+200D ZWJ are that case, gaining `XID_Continue` in UCD
+ * 15.1 and absent from it in 13.0.0, 14.0.0 and 15.0.0, so `a\u{200C}b` is
+ * emitted bare here while `isidentifier()` is False on 3.9.6 and on 3.12.13
+ * (15.0.0). A CPython newer than the engine only routes a legal name to the
  * subscript/`dict[str, Any]` path: less readable, still correct. The NFKC
  * condition reduces to the same skew, since normalization stability guarantees
  * an assigned character's normalization never changes afterwards.
@@ -85,8 +88,10 @@ const IDENTIFIER = /^[\p{XID_Start}_]\p{XID_Continue}*$/u
  * unpublished on this base, so the note records it as that PR's decision.
  *
  * The `ts-types` sibling keeps its own ASCII rule rather than sharing this
- * one: ECMAScript identifiers are a different set (`$`, ZWJ/ZWNJ) and are
- * never normalized, so one predicate cannot be correct for both.
+ * one: ECMAScript identifiers are a different set (`$`) and are never
+ * normalized, so one predicate cannot be correct for both. ZWJ/ZWNJ are not
+ * part of that difference — both sets carry them on the engine's tables; what
+ * separates the two there is the CPython table version above.
  * @param name - the raw schema field or tool name.
  * @returns whether the name can be emitted bare.
  */
@@ -440,10 +445,13 @@ function pyScalar(value: JsonSchemaScalar): string {
 /**
  * Render a validated scalar `const`/`enum` as `Literal[...]`, falling back to
  * the broad type. Deliberately deviates from PEP 586, which restricts `Literal`
- * parameters to int/bool/str/bytes/enum/None: a number `const`/`enum` emits a
- * float literal (`Literal[1.5]`) a strict checker would reject. Harmless here —
- * the stub is advisory prompt text, only required to parse — and keeping the
- * exact value communicates the constraint to the model.
+ * parameters to int/bool/str/bytes/enum/None: a non-integral number
+ * `const`/`enum` emits a float literal (`Literal[1.5]`) a strict checker would
+ * reject. An integral one does not deviate — {@link pyScalar} emits int digits,
+ * including for the beyond-safe-range values it widens through `BigInt`, and
+ * PEP 586 admits int parameters. Harmless either way — the stub is advisory
+ * prompt text, only required to parse — and keeping the exact value
+ * communicates the constraint to the model.
  */
 function renderConstrainedScalar(node: JsonSchemaNode, broad: string, state: RenderState): string {
   if (node.const !== undefined) {

packages/core/tools/tests/code-mode.spec.ts

@@ -406,11 +406,13 @@ describe('mode-aware wire contribution', () => {
       .toThrow(/no run_code schema flavor registered for runtime language "ruby" \(known: "typescript", "python"\)/)
   })
 
-  it('degrades the run_code flavor to TypeScript when no runtime is mounted (doc-catalog schema harvest)', async () => {
-    // The tool-catalog generator boots the registry under `mode: code` and
-    // reads run_code's schema WITHOUT a runtime; peekRuntime returns undefined
-    // there, so the flavor getter degrades to the TS default rather than
-    // throwing (that harvest never feeds a model).
+  it('degrades the run_code flavor to TypeScript when no runtime is mounted', async () => {
+    // Any reader of the definition without a mounted runtime lands here; the
+    // shipped one is the tool-catalog generator, which boots the registry under
+    // `mode: code` and reads run_code's schema WITHOUT a runtime. peekRuntime
+    // returns undefined there, so the flavor getter degrades to the TS default
+    // rather than throwing. None of those readers feeds a model: assembly goes
+    // through wireSchemas, which requires a runtime first.
     const { ctx } = await setup({ mode: 'code', runtime: false })
     const definition = ctx.tools.get(RUN_CODE_NAME)
     expect(definition?.description).toContain('Execute a TypeScript program')