fix(generator): surface the migration note on mixed classes; docs example corrections (review round 1)

- The migration note now renders whenever instance members were omitted,
  not only when the class ends up empty — a surviving @staticmethod no
  longer hides that instance API vanished. New discriminating test.
- docs/examples: replace the invalid module-level import of Counter's
  most_common with statistics.median, a real top-level function.
- getting-started/llms: numeric output comments match JS interpolation
  (5.86, not 5.860).
- transport.test: cover all three removed methods in the protocol-guard
  rejection test, not just instantiate.

Author: brett-bonner_infodesk

docs/examples/index.md

@@ -59,13 +59,13 @@ console.log(await sin(pi / 4));
 
 ## Value-returning APIs
 
-v0.9 generated wrappers do not keep live Python class instances. Expose an operation as a
-value-returning module function instead:
+v0.9 generated wrappers do not keep live Python class instances. Expose an
+operation as a value-returning module function instead:
 
 ```ts
-import { most_common } from './generated/collections.generated.js';
+import { median } from './generated/statistics.generated.js';
 
-console.log(await most_common([1, 2, 2], 1));
+console.log(await median([1, 2, 2])); // 2
 ```
 
 ## More Docs

docs/guide/getting-started.md

@@ -212,8 +212,8 @@ async function demo() {
   const sum = await add(3.14159, 2.71828, 3);
   const product = await multiply(sum, 2, 3);
 
-  console.log(`Sum: ${sum}`); // Sum: 5.860
-  console.log(`Product: ${product}`); // Product: 11.720
+  console.log(`Sum: ${sum}`); // Sum: 5.86
+  console.log(`Product: ${product}`); // Product: 11.72
 }
 ```
 

docs/public/llms-full.txt

@@ -271,8 +271,8 @@ async function demo() {
   const sum = await add(3.14159, 2.71828, 3);
   const product = await multiply(sum, 2, 3);
 
-  console.log(`Sum: ${sum}`); // Sum: 5.860
-  console.log(`Product: ${product}`); // Product: 11.720
+  console.log(`Sum: ${sum}`); // Sum: 5.86
+  console.log(`Product: ${product}`); // Product: 11.72
 }
 ```
 
@@ -3463,9 +3463,9 @@ v0.9 generated wrappers do not keep live Python class instances. Expose an opera
 value-returning module function instead:
 
 ```ts
-import { most_common } from './generated/collections.generated.js';
+import { median } from './generated/statistics.generated.js';
 
-console.log(await most_common([1, 2, 2], 1));
+console.log(await median([1, 2, 2])); // 2
 ```
 
 ## More Docs

src/core/generator.ts

@@ -798,13 +798,11 @@ ${callPrelude}${guards}    return ${callExpr};
     // The constructor counts: a class whose only member was __init__ loses
     // create(), so it needs the migration note as much as one with methods.
     const omittedInstanceMembers =
-      cls.methods.some(
-        method => method.methodKind !== 'class' && method.methodKind !== 'static'
-      ) || (cls.accessors?.length ?? 0) > 0;
-    const migrationNote =
-      methodBodies.length === 0 && omittedInstanceMembers
-        ? '  // NOTE: Instance members are not generated in v0.9; migrate this API to value-returning module functions.\n'
-        : '';
+      cls.methods.some(method => method.methodKind !== 'class' && method.methodKind !== 'static') ||
+      (cls.accessors?.length ?? 0) > 0;
+    const migrationNote = omittedInstanceMembers
+      ? '  // NOTE: Instance members are not generated in v0.9; migrate this API to value-returning module functions.\n'
+      : '';
     const ts = `${jsdoc}export class ${cname}${classTypeParamDecl} {
 ${migrationNote}${methodsSection}
 }

test/generator.test.ts

@@ -1358,6 +1358,42 @@ describe('CodeGenerator', () => {
     expect(code.declaration).not.toContain('get petName');
   });
 
+  it('keeps the migration note when static methods survive but instance methods are dropped', () => {
+    const method = (name: string, methodKind?: string) => ({
+      name,
+      signature: {
+        parameters: [],
+        returnType: { kind: 'primitive', name: 'int' },
+        isAsync: false,
+        isGenerator: false,
+      },
+      docstring: undefined,
+      decorators: [],
+      isAsync: false,
+      isGenerator: false,
+      ...(methodKind ? { methodKind } : {}),
+      returnType: { kind: 'primitive', name: 'int' },
+      parameters: [],
+    });
+
+    const code = gen.generateClassWrapper(
+      {
+        name: 'Mixed',
+        bases: [],
+        methods: [method('helper', 'static'), method('compute')],
+        properties: [],
+        docstring: undefined,
+        decorators: [],
+      } as any,
+      'mixed_mod'
+    );
+
+    expect(code.typescript).toContain('static async helper');
+    expect(code.typescript).not.toContain('compute(');
+    expect(code.typescript).toContain('Instance members are not generated in v0.9');
+    expect(code.declaration).toContain('Instance members are not generated in v0.9');
+  });
+
   it('emits the same empty class for implicit and explicit instance methods', () => {
     const base = {
       name: 'Widget',

test/transport.test.ts

@@ -239,15 +239,18 @@ describe('Transport Interface', () => {
       expect(isProtocolMessage(msg)).toBe(true);
     });
 
-    it('rejects removed instance protocol messages', () => {
-      const msg = {
-        id: 1,
-        protocol: PROTOCOL_ID,
-        method: 'instantiate',
-        params: { module: 'mymodule', className: 'MyClass', args: [] },
-      };
-      expect(isProtocolMessage(msg)).toBe(false);
-    });
+    it.each(['instantiate', 'call_method', 'dispose_instance'])(
+      'rejects removed instance protocol message: %s',
+      method => {
+        const msg = {
+          id: 1,
+          protocol: PROTOCOL_ID,
+          method,
+          params: { module: 'mymodule', className: 'MyClass', args: [] },
+        };
+        expect(isProtocolMessage(msg)).toBe(false);
+      }
+    );
 
     it('returns false for null', () => {
       expect(isProtocolMessage(null)).toBe(false);