tywrap 0.7.0 → 0.9.0

package/src/core/generator.ts

@@ -29,14 +29,44 @@ interface GenericRenderParam {
 
 interface GenericRenderContext {
   currentModule?: string;
+  localDeclaredNames: Set<string>;
   declaration: string;
   typeArguments: string;
   emittedNames: Set<string>;
   emittedParamSpecs: Set<string>;
 }
 
+type ReturnDefinitionNames = ReadonlySet<string>;
+
+export interface CodeGeneratorOptions {
+  /** Reports a generated annotation that cannot be represented by emitted declarations. */
+  onTypeDegrade?: (typeName: string) => void;
+}
+
 export class CodeGenerator {
   private readonly mapper: TypeMapper;
+  private readonly onTypeDegrade?: (typeName: string) => void;
+  private readonly builtinGenericNames = new Set([
+    'Array',
+    'AsyncIterator',
+    'Generator',
+    'Iterable',
+    'Iterator',
+    'Promise',
+    'Record',
+  ]);
+  // Iterator-protocol objects can never cross the bridge: the Python side
+  // rejects them loudly at serialization, so a return typed as one of these
+  // could never carry a value. Returns degrade to `unknown` (and count as a
+  // degrade for --fail-on-warn). Iterable/Sequence are NOT here — a list
+  // satisfies those annotations and decodes to an array, which structurally
+  // satisfies the emitted TS type.
+  private readonly nonDecodableReturnGenerics = new Set([
+    'Generator',
+    'AsyncGenerator',
+    'Iterator',
+    'AsyncIterator',
+  ]);
   private readonly reservedTsIdentifiers = new Set([
     'default',
     'delete',
@@ -66,8 +96,9 @@ export class CodeGenerator {
     'false',
   ]);
 
-  constructor(mapper: TypeMapper = new TypeMapper()) {
+  constructor(mapper: TypeMapper = new TypeMapper(), options: CodeGeneratorOptions = {}) {
     this.mapper = mapper;
+    this.onTypeDegrade = options.onTypeDegrade;
   }
 
   /**
@@ -140,7 +171,8 @@ export class CodeGenerator {
   private buildGenericRenderContext(
     typeParameters: readonly PythonGenericParameter[],
     types: readonly PythonType[],
-    currentModule?: string
+    currentModule?: string,
+    localDeclaredNames: Set<string> = new Set()
   ): GenericRenderContext {
     const callableParamSpecs = new Set<string>();
     types.forEach(type => this.collectCallableParamSpecs(type, callableParamSpecs));
@@ -170,6 +202,7 @@ export class CodeGenerator {
 
     return {
       currentModule,
+      localDeclaredNames,
       declaration:
         emitted.length > 0 ? `<${emitted.map(param => param.declaration).join(', ')}>` : '',
       typeArguments: emitted.length > 0 ? `<${emitted.map(param => param.name).join(', ')}>` : '',
@@ -184,6 +217,7 @@ export class CodeGenerator {
   ): GenericRenderContext {
     return {
       currentModule: inner.currentModule ?? outer.currentModule,
+      localDeclaredNames: inner.localDeclaredNames,
       declaration: inner.declaration,
       typeArguments: inner.typeArguments,
       emittedNames: new Set([...outer.emittedNames, ...inner.emittedNames]),
@@ -308,7 +342,27 @@ export class CodeGenerator {
     ctx: GenericRenderContext,
     mappingContext: 'value' | 'return'
   ): string {
-    return this.typeToTs(this.mapper.mapPythonType(this.sanitizeType(type, ctx), mappingContext));
+    return this.typeToTs(
+      this.mapper.mapPythonType(this.sanitizeType(type, ctx), mappingContext),
+      ctx,
+      mappingContext
+    );
+  }
+
+  private isLocalTypeIdentity(
+    type: { name: string; module?: string },
+    ctx: GenericRenderContext
+  ): boolean {
+    if (!ctx.localDeclaredNames.has(type.name)) {
+      return false;
+    }
+    return type.module === undefined || type.module === ctx.currentModule;
+  }
+
+  private degradeType(type: { name: string; module?: string }): string {
+    const identity = type.module ? `${type.module}.${type.name}` : type.name;
+    this.onTypeDegrade?.(identity);
+    return 'unknown';
   }
 
   private renderLooksLikeKwargsExpr(
@@ -357,10 +411,155 @@ export class CodeGenerator {
     };
   }
 
+  /**
+   * Preserve Python provenance in generated return validators instead of
+   * reconstructing a checker from the final TypeScript spelling. In particular
+   * pandas/NumPy values retain their marker contract after Arrow decoding.
+   */
+  private returnSchema(type: PythonType, definitions: ReturnDefinitionNames = new Set()): unknown {
+    // A bare `-> None` return maps to TS void and validates nothing, but a
+    // NESTED None (union member, tuple element) is a real wire value — it
+    // decodes to null and must be checked as null, or a union containing it
+    // would carry an any-member and accept everything.
+    if (type.kind === 'primitive' && type.name === 'None') {
+      return { kind: 'any' };
+    }
+    const schema = (current: PythonType): unknown => {
+      switch (current.kind) {
+        case 'primitive':
+          return current.name === 'int' || current.name === 'float'
+            ? { kind: 'primitive', type: 'number' }
+            : current.name === 'str'
+              ? { kind: 'primitive', type: 'string' }
+              : current.name === 'bool'
+                ? { kind: 'primitive', type: 'boolean' }
+                : current.name === 'bytes'
+                  ? { kind: 'primitive', type: 'Uint8Array' }
+                  : current.name === 'None'
+                    ? { kind: 'primitive', type: 'null' }
+                    : { kind: 'any' };
+        case 'literal':
+          return { kind: 'literal', value: current.value };
+        case 'annotated':
+          return schema(current.base);
+        case 'final':
+        case 'classvar':
+          return schema(current.type);
+        case 'optional':
+          return {
+            kind: 'union',
+            options: [schema(current.type), { kind: 'primitive', type: 'null' }],
+          };
+        case 'union':
+          return { kind: 'union', options: current.types.map(schema) };
+        case 'collection': {
+          if (current.name === 'tuple') {
+            if (current.itemTypes[1]?.kind === 'custom' && current.itemTypes[1].name === '...') {
+              return {
+                kind: 'array',
+                element: schema(current.itemTypes[0] ?? { kind: 'custom', name: 'Any' }),
+              };
+            }
+            return { kind: 'tuple', elements: current.itemTypes.map(schema) };
+          }
+          if (current.name === 'dict') {
+            return {
+              kind: 'record',
+              values: schema(current.itemTypes[1] ?? { kind: 'custom', name: 'Any' }),
+            };
+          }
+          return {
+            kind: 'array',
+            element: schema(current.itemTypes[0] ?? { kind: 'custom', name: 'Any' }),
+          };
+        }
+        case 'generic': {
+          const leaf = current.name.split('.').at(-1) ?? current.name;
+          if (leaf === 'NDArray' || leaf === 'ndarray') {
+            return { kind: 'marker', marker: 'ndarray' };
+          }
+          // Iterator/Generator are deliberately absent: those returns emit
+          // `unknown` (see nonDecodableReturnGenerics) and validate nothing.
+          if (['list', 'List', 'Sequence', 'Iterable', 'set', 'frozenset'].includes(leaf)) {
+            return {
+              kind: 'array',
+              element: schema(current.typeArgs[0] ?? { kind: 'custom', name: 'Any' }),
+            };
+          }
+          if (['dict', 'Dict', 'Mapping', 'MutableMapping'].includes(leaf)) {
+            return {
+              kind: 'record',
+              values: schema(current.typeArgs[1] ?? { kind: 'custom', name: 'Any' }),
+            };
+          }
+          return definitions.has(leaf) ? { kind: 'ref', name: leaf } : { kind: 'any' };
+        }
+        case 'custom': {
+          const leaf = current.name.split('.').at(-1) ?? current.name;
+          const full = `${current.module ?? ''}.${leaf}`;
+          if (leaf === 'None') {
+            return { kind: 'primitive', type: 'null' };
+          }
+          if (leaf === 'Any' || leaf === 'object' || leaf === 'NoReturn' || leaf === 'Never') {
+            return { kind: 'any' };
+          }
+          if (leaf === 'DataFrame' && (!current.module || current.module.startsWith('pandas'))) {
+            return { kind: 'marker', marker: 'dataframe' };
+          }
+          if (leaf === 'Series' && (!current.module || current.module.startsWith('pandas'))) {
+            return { kind: 'marker', marker: 'series' };
+          }
+          if (leaf === 'ndarray' || leaf === 'NDArray' || full.includes('numpy')) {
+            return { kind: 'marker', marker: 'ndarray' };
+          }
+          return definitions.has(leaf) ? { kind: 'ref', name: leaf } : { kind: 'any' };
+        }
+        case 'typevar':
+        case 'paramspec':
+        case 'paramspec_args':
+        case 'paramspec_kwargs':
+        case 'typevartuple':
+        case 'unpack':
+        case 'callable':
+          return { kind: 'any' };
+      }
+    };
+    return schema(type);
+  }
+
+  private returnDefinitions(module: PythonModule): ReturnDefinitionNames {
+    return new Set(
+      module.classes
+        .filter(cls => cls.kind === 'typed_dict' || cls.decorators.includes('__typed_dict__'))
+        .map(cls => cls.name)
+    );
+  }
+
+  private emitReturnDefinitions(module: PythonModule): string {
+    const definitions = this.returnDefinitions(module);
+    const entries = module.classes
+      .filter(cls => cls.kind === 'typed_dict' || cls.decorators.includes('__typed_dict__'))
+      .map(cls => {
+        const fields = Object.fromEntries(
+          cls.properties.map(property => [
+            property.name,
+            {
+              schema: this.returnSchema(property.type, definitions),
+              optional: property.optional === true,
+            },
+          ])
+        );
+        return [cls.name, { kind: 'record', fields }];
+      });
+    return `const __tywrapReturnDefinitions: Record<string, ReturnSchema> = ${JSON.stringify(Object.fromEntries(entries))};\n\n`;
+  }
+
   generateFunctionWrapper(
     func: PythonFunction,
     moduleName?: string,
-    annotatedJSDoc = false
+    annotatedJSDoc = false,
+    localDeclaredNames: Set<string> = new Set(),
+    returnDefinitions: ReturnDefinitionNames = new Set()
   ): GeneratedCode {
     const jsdoc = this.generateJsDoc(
       func.docstring,
@@ -379,7 +578,8 @@ export class CodeGenerator {
     const genericContext = this.buildGenericRenderContext(
       this.getTypeParameters(func.typeParameters),
       [func.returnType, ...filteredParams.map(param => param.type)],
-      moduleName
+      moduleName,
+      localDeclaredNames
     );
     const typeParamDecl = genericContext.declaration;
 
@@ -447,6 +647,8 @@ export class CodeGenerator {
     const returnType = this.typeToTsFromPython(func.returnType, genericContext, 'return');
     const fname = this.escapeIdentifier(func.name);
     const moduleId = moduleName ?? '__main__';
+    const validatorName = `__validate${this.escapeIdentifier(func.name, { preserveCase: true })}Result`;
+    const returnValidator = `const ${validatorName} = createReturnValidator(${JSON.stringify(this.returnSchema(func.returnType, returnDefinitions))}, ${JSON.stringify(`${moduleId}.${func.name}`)}, __tywrapReturnDefinitions);\n\n`;
 
     // Overloads: generate trailing optional parameter drop variants (exclude *args/**kwargs).
     // Why: Python APIs frequently have many optional tail params. TypeScript callers expect
@@ -535,10 +737,8 @@ export class CodeGenerator {
     const callPreludeLines = emitCallPrelude(callDescriptor, this.callEmitHelpers());
     const callPrelude = callPreludeLines.length > 0 ? `${callPreludeLines.join('\n')}\n` : '';
 
-    const ts = `${jsdoc}${overloadDecl}export async function ${fname}${typeParamDecl}(${paramDecl}): Promise<${returnType}> {
-${callPrelude}${guards}  return getRuntimeBridge().call('${moduleId}', '${func.name}', __args${
-      hasKwArgs ? ', __kwargs' : ''
-    });
+    const ts = `${jsdoc}${returnValidator}${overloadDecl}export async function ${fname}${typeParamDecl}(${paramDecl}): Promise<${returnType}> {
+${callPrelude}${guards}  return getRuntimeBridge().call<${returnType}>('${moduleId}', '${func.name}', __args, ${hasKwArgs ? '__kwargs' : 'undefined'}, ${validatorName});
 }
 `;
 
@@ -553,8 +753,12 @@ ${callPrelude}${guards}  return getRuntimeBridge().call('${moduleId}', '${func.n
   generateClassWrapper(
     cls: PythonClass,
     moduleName?: string,
-    _annotatedJSDoc = false
+    _annotatedJSDoc = false,
+    localDeclaredNames: Set<string> = new Set(),
+    returnDefinitions: ReturnDefinitionNames = new Set()
   ): GeneratedCode {
+    const moduleDeclaredNames = new Set(localDeclaredNames);
+    moduleDeclaredNames.add(cls.name);
     const jsdoc = this.generateJsDoc(cls.docstring);
     const classGenericContext = this.buildGenericRenderContext(
       this.getTypeParameters(cls.typeParameters),
@@ -566,14 +770,11 @@ ${callPrelude}${guards}  return getRuntimeBridge().call('${moduleId}', '${func.n
           ...method.parameters.map(p => p.type),
         ]),
       ],
-      moduleName
+      moduleName,
+      moduleDeclaredNames
     );
     const classTypeParamDecl = classGenericContext.declaration;
     const cname = this.escapeIdentifier(cls.name);
-    const classSelfType = `${cname}${classGenericContext.typeArguments}`;
-    const tsValueType = (p: (typeof cls.methods)[number]['parameters'][number]): string =>
-      this.typeToTsFromPython(p.type, classGenericContext, 'value');
-
     const wrapAlias = (body: string): GeneratedCode => {
       const ts = `${jsdoc}export type ${cname}${classTypeParamDecl} = ${body}\n`;
       return this.wrap(ts, ts, [cls.name]);
@@ -621,7 +822,8 @@ ${callPrelude}${guards}  return getRuntimeBridge().call('${moduleId}', '${func.n
           const methodOwnGenericContext = this.buildGenericRenderContext(
             this.getTypeParameters(m.typeParameters),
             [m.returnType, ...fparams.map(param => param.type)],
-            moduleName
+            moduleName,
+            moduleDeclaredNames
           );
           const methodGenericContext = this.mergeGenericRenderContexts(
             classGenericContext,
@@ -659,19 +861,21 @@ ${callPrelude}${guards}  return getRuntimeBridge().call('${moduleId}', '${func.n
     const methodDeclarations: string[] = [];
 
     sortedMethods
-      .filter(method => method.name !== '__init__')
+      .filter(
+        method =>
+          method.name !== '__init__' &&
+          (method.methodKind === 'class' || method.methodKind === 'static')
+      )
       .forEach(method => {
-        // @classmethod and @staticmethod become `static` members invoked through
-        // the class (`Class.method`), not the instance handle. Instance methods
-        // (the default, or an absent methodKind) keep the existing emission so
-        // their output stays byte-identical.
-        const isStatic = method.methodKind === 'class' || method.methodKind === 'static';
-        const staticPrefix = isStatic ? 'static ' : '';
+        // v0.9 wrappers expose only class/static methods. They route through
+        // the ordinary module call path and never retain process-local state.
+        const staticPrefix = 'static ';
         const fparams = method.parameters.filter(p => p.name !== 'self' && p.name !== 'cls');
         const methodOwnGenericContext = this.buildGenericRenderContext(
           this.getTypeParameters(method.typeParameters),
           [method.returnType, ...fparams.map(param => param.type)],
-          moduleName
+          moduleName,
+          moduleDeclaredNames
         );
         const methodGenericContext = this.mergeGenericRenderContexts(
           classGenericContext,
@@ -737,6 +941,8 @@ ${callPrelude}${guards}  return getRuntimeBridge().call('${moduleId}', '${func.n
           'return'
         );
         const mname = this.escapeIdentifier(method.name);
+        const validatorName = `__validate${this.escapeIdentifier(cls.name, { preserveCase: true })}${this.escapeIdentifier(method.name, { preserveCase: true })}Result`;
+        const returnValidator = `const ${validatorName} = createReturnValidator(${JSON.stringify(this.returnSchema(method.returnType, returnDefinitions))}, ${JSON.stringify(`${moduleId}.${cls.name}.${method.name}`)}, __tywrapReturnDefinitions);\n\n`;
 
         const overloads: string[] = [];
         if (needsKwargsParam && requiredKwOnlyNames.length > 0) {
@@ -784,193 +990,49 @@ ${callPrelude}${guards}  return getRuntimeBridge().call('${moduleId}', '${func.n
         const guardLines = emitArgGuards(callDescriptor);
         const guards = guardLines.length > 0 ? `${guardLines.join('\n')}\n` : '';
 
-        const callExpr = isStatic
-          ? `getRuntimeBridge().call('${moduleId}', '${cls.name}.${method.name}', __args${
-              needsKwargsParam ? ', __kwargs' : ''
-            })`
-          : `getRuntimeBridge().callMethod(this.__handle, '${method.name}', __args${
-              needsKwargsParam ? ', __kwargs' : ''
-            })`;
+        const callExpr = `getRuntimeBridge().call<${returnType}>('${moduleId}', '${cls.name}.${method.name}', __args, ${needsKwargsParam ? '__kwargs' : 'undefined'}, ${validatorName})`;
         methodBodies.push(`${overloadDecl}  ${staticPrefix}async ${mname}${methodTypeParamDecl}(${paramsDecl}): Promise<${returnType}> {
-${callPrelude}${guards}    return ${callExpr};
+    ${returnValidator}${callPrelude}${guards}    return ${callExpr};
   }`);
         methodDeclarations.push(
           `${overloadDecl}${overloads.length > 0 ? '' : `  ${staticPrefix}${mname}${methodTypeParamDecl}(${paramsDecl}): Promise<${returnType}>;\n`}`
         );
       });
 
-    const init = cls.methods.find(m => m.name === '__init__');
-    const ctorSpec = (() => {
-      if (!init) {
-        return {
-          overloadDecl: '',
-          declaration: `  static create${classTypeParamDecl}(...args: unknown[]): Promise<${classSelfType}>;\n`,
-          paramsDecl: `...args: unknown[]`,
-          callPrelude: `    const __args: unknown[] = [...args];\n`,
-          hasKwargs: false,
-          guardLines: [] as string[],
-        };
-      }
-
-      const fparams = init.parameters.filter(p => p.name !== 'self' && p.name !== 'cls');
-      const keywordOnlyParams = fparams.filter(p => p.keywordOnly);
-      const positionalOnlyNames = fparams.filter(p => p.positionalOnly).map(p => p.name);
-      const hasVarKwArgs = fparams.some(p => p.kwArgs);
-      const needsKwargsParam = keywordOnlyParams.length > 0 || hasVarKwArgs;
-      const varArgsParam = fparams.find(p => p.varArgs);
-      const needsVarArgsArray = Boolean(varArgsParam) && needsKwargsParam;
-      const positionalParams = fparams.filter(p => !p.keywordOnly && !p.varArgs && !p.kwArgs);
-      const firstOptionalPosIndex = positionalParams.findIndex(p => p.optional);
-      const requiredPosCount =
-        firstOptionalPosIndex >= 0 ? firstOptionalPosIndex : positionalParams.length;
-      const keywordOnlyNames = keywordOnlyParams.map(p => p.name);
-
-      const renderPositionalParam = (
-        p: (typeof positionalParams)[number],
-        forceRequired = false
-      ): string => {
-        const pname = this.escapeIdentifier(p.name);
-        const opt = !forceRequired && p.optional ? '?' : '';
-        return `${pname}${opt}: ${tsValueType(p)}`;
-      };
-
-      const kwargsType = (() => {
-        if (!needsKwargsParam) {
-          return '';
-        }
-        if (keywordOnlyParams.length === 0 && hasVarKwArgs) {
-          return 'Record<string, unknown>';
-        }
-        const props = keywordOnlyParams
-          .map(p => `${JSON.stringify(p.name)}${p.optional ? '?' : ''}: ${tsValueType(p)};`)
-          .join(' ');
-        const obj = `{ ${props} }`;
-        return hasVarKwArgs ? `(${obj} & Record<string, unknown>)` : obj;
-      })();
-
-      const paramsDeclParts: string[] = [];
-      positionalParams.forEach(p => {
-        paramsDeclParts.push(renderPositionalParam(p));
-      });
-      if (varArgsParam) {
-        const vname = this.escapeIdentifier(varArgsParam.name);
-        paramsDeclParts.push(needsVarArgsArray ? `${vname}?: unknown[]` : `...${vname}: unknown[]`);
-      }
-      if (needsKwargsParam) {
-        paramsDeclParts.push(`kwargs?: ${kwargsType}`);
-      }
-      const paramsDecl = paramsDeclParts.join(', ');
-
-      const requiredKwOnlyNames = keywordOnlyParams.filter(p => !p.optional).map(p => p.name);
-      const overloads: string[] = [];
-      if (needsKwargsParam && requiredKwOnlyNames.length > 0) {
-        const firstOptionalIndex = positionalParams.findIndex(p => p.optional);
-        const requiredPosCount =
-          firstOptionalIndex >= 0 ? firstOptionalIndex : positionalParams.length;
-        for (let i = requiredPosCount; i <= positionalParams.length; i++) {
-          const head = positionalParams.slice(0, i).map(p => renderPositionalParam(p, true));
-          const rest: string[] = [];
-          if (varArgsParam) {
-            const vname = this.escapeIdentifier(varArgsParam.name);
-            rest.push(
-              needsVarArgsArray ? `${vname}: unknown[] | undefined` : `...${vname}: unknown[]`
-            );
-          }
-          rest.push(`kwargs: ${kwargsType}`);
-          overloads.push(
-            `  static create${classTypeParamDecl}(${[...head, ...rest].join(', ')}): Promise<${classSelfType}>;`
-          );
-          if (varArgsParam && needsVarArgsArray) {
-            overloads.push(
-              `  static create${classTypeParamDecl}(${[...head, `kwargs: ${kwargsType}`].join(', ')}): Promise<${classSelfType}>;`
-            );
-          }
-        }
-      }
-      const overloadDecl = overloads.length > 0 ? `${overloads.join('\n')}\n` : '';
-      const declaration =
-        overloads.length > 0
-          ? overloadDecl
-          : `  static create${classTypeParamDecl}(${paramsDecl}): Promise<${classSelfType}>;\n`;
-
-      const callDescriptor: CallDescriptor = {
-        positionalParams,
-        varArgsParam,
-        needsVarArgsArray,
-        hasKwArgs: needsKwargsParam,
-        hasVarKwArgs,
-        keywordOnlyNames,
-        requiredKwOnlyNames,
-        positionalOnlyNames,
-        requiredPosCount,
-        indent: '    ',
-        errorLabel: '__init__',
-      };
-      const callPreludeLines = emitCallPrelude(callDescriptor, this.callEmitHelpers());
-      const callPrelude = callPreludeLines.length > 0 ? `${callPreludeLines.join('\n')}\n` : '';
-      const guardLines = emitArgGuards(callDescriptor);
-
-      return {
-        overloadDecl,
-        declaration,
-        paramsDecl,
-        callPrelude,
-        hasKwargs: needsKwargsParam,
-        guardLines,
-      };
-    })();
-
-    // @property / functools.cached_property → TS getters returning Promise<T>.
-    // Reading the attribute fires the getter on the Python side; the bridge
-    // resolves it via callMethod with no args. Sorted for stable output.
-    const accessorBodies: string[] = [];
-    const accessorDeclarations: string[] = [];
-    const sortedAccessors = [...(cls.accessors ?? [])].sort((a, b) => a.name.localeCompare(b.name));
-    sortedAccessors.forEach(accessor => {
-      const aname = this.escapeIdentifier(accessor.name);
-      const accessorType = this.typeToTsFromPython(accessor.type, classGenericContext, 'return');
-      const jsdocAcc = this.generateJsDoc(accessor.docstring);
-      accessorBodies.push(
-        `${jsdocAcc}  get ${aname}(): Promise<${accessorType}> { return getRuntimeBridge().callMethod(this.__handle, '${accessor.name}', []); }`
-      );
-      accessorDeclarations.push(`${jsdocAcc}  get ${aname}(): Promise<${accessorType}>;\n`);
-    });
-    const accessorsImpl = accessorBodies.length > 0 ? `${accessorBodies.join('\n')}\n` : '';
-    const accessorsDecl = accessorDeclarations.length > 0 ? `${accessorDeclarations.join('')}` : '';
-
     const methodsSection = methodBodies.length > 0 ? `\n${methodBodies.join('\n')}\n` : '\n';
     const declarationMethodsSection =
       methodDeclarations.length > 0 ? `\n${methodDeclarations.join('')}\n` : '\n';
-    const ctorGuards = ctorSpec.guardLines.length > 0 ? `${ctorSpec.guardLines.join('\n')}\n` : '';
-    const newClassExpr = `new ${cname}${classGenericContext.typeArguments}(handle)`;
+    // 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 = 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} {
-  private readonly __handle: string;
-  private constructor(handle: string) { this.__handle = handle; }
-${ctorSpec.overloadDecl}  static async create${classTypeParamDecl}(${ctorSpec.paramsDecl}): Promise<${classSelfType}> {
-${ctorSpec.callPrelude}${ctorGuards}    const handle = await getRuntimeBridge().instantiate<string>('${moduleId}', '${cls.name}', __args${
-      ctorSpec.hasKwargs ? ', __kwargs' : ''
-    });
-    return ${newClassExpr};
-  }
-  static fromHandle${classTypeParamDecl}(handle: string): ${classSelfType} { return ${newClassExpr}; }${methodsSection}${accessorsImpl}  async disposeHandle(): Promise<void> { await getRuntimeBridge().disposeInstance(this.__handle); }
+${migrationNote}${methodsSection}
 }
 `;
 
     const declaration = `${jsdoc}export class ${cname}${classTypeParamDecl} {
-  private readonly __handle: string;
-  private constructor(handle: string);
-${ctorSpec.declaration}  static fromHandle${classTypeParamDecl}(handle: string): ${classSelfType};${declarationMethodsSection}${accessorsDecl}  disposeHandle(): Promise<void>;
+${migrationNote}${declarationMethodsSection}
 }
 `;
 
     return this.wrap(ts, declaration, [cls.name]);
   }
 
-  generateTypeAlias(alias: PythonTypeAlias, moduleName?: string): GeneratedCode {
+  generateTypeAlias(
+    alias: PythonTypeAlias,
+    moduleName?: string,
+    localDeclaredNames: Set<string> = new Set()
+  ): GeneratedCode {
     const genericContext = this.buildGenericRenderContext(
       this.getTypeParameters(alias.typeParameters),
       [alias.type],
-      moduleName
+      moduleName,
+      localDeclaredNames
     );
     const aliasName = this.escapeIdentifier(alias.name, { preserveCase: true });
     const body = this.typeToTsFromPython(alias.type, genericContext, 'value');
@@ -1004,15 +1066,35 @@ ${ctorSpec.declaration}  static fromHandle${classTypeParamDecl}(handle: string):
   }
 
   generateModuleDefinition(module: PythonModule, annotatedJSDoc = false): GeneratedCode {
+    const localDeclaredNames = new Set([
+      ...module.classes.map(cls => cls.name),
+      ...(module.typeAliases ?? []).map(alias => alias.name),
+    ]);
     const functionResults = [...module.functions]
       .sort((a, b) => a.name.localeCompare(b.name))
-      .map(f => this.generateFunctionWrapper(f, module.name, annotatedJSDoc));
+      .map(f =>
+        this.generateFunctionWrapper(
+          f,
+          module.name,
+          annotatedJSDoc,
+          localDeclaredNames,
+          this.returnDefinitions(module)
+        )
+      );
     const classResults = [...module.classes]
       .sort((a, b) => a.name.localeCompare(b.name))
-      .map(c => this.generateClassWrapper(c, module.name, annotatedJSDoc));
+      .map(c =>
+        this.generateClassWrapper(
+          c,
+          module.name,
+          annotatedJSDoc,
+          localDeclaredNames,
+          this.returnDefinitions(module)
+        )
+      );
     const typeAliasResults = [...(module.typeAliases ?? [])]
       .sort((a, b) => a.name.localeCompare(b.name))
-      .map(alias => this.generateTypeAlias(alias, module.name));
+      .map(alias => this.generateTypeAlias(alias, module.name, localDeclaredNames));
 
     const functionCodes = functionResults.map(result => result.typescript).join('\n');
     const classCodes = classResults.map(result => result.typescript).join('\n');
@@ -1025,7 +1107,9 @@ ${ctorSpec.declaration}  static fromHandle${classTypeParamDecl}(handle: string):
       return kind === 'class' && !c.decorators.includes('__typed_dict__');
     });
     const needsRuntime = module.functions.length > 0 || hasRuntimeClasses;
-    const bridgeDecl = needsRuntime ? `import { getRuntimeBridge } from 'tywrap/runtime';\n\n` : '';
+    const bridgeDecl = needsRuntime
+      ? `import { createReturnValidator, getRuntimeBridge, type ReturnSchema } from 'tywrap/runtime';\n\n${this.emitReturnDefinitions(module)}`
+      : '';
 
     const ts = `${`${header}${bridgeDecl}${functionCodes}\n${classCodes}\n${typeAliasCodes}`.trimEnd()}\n`;
     const declaration = `${`${declarationHeader}${functionResults
@@ -1067,23 +1151,27 @@ ${ctorSpec.declaration}  static fromHandle${classTypeParamDecl}(handle: string):
     };
   }
 
-  private typeToTs(type: TypescriptType): string {
+  private typeToTs(
+    type: TypescriptType,
+    ctx?: GenericRenderContext,
+    mappingContext: 'value' | 'return' = 'value'
+  ): string {
     switch (type.kind) {
       case 'primitive':
         return type.name;
       case 'array':
-        return `${this.typeToTs(type.elementType)}[]`;
+        return `${this.typeToTs(type.elementType, ctx, mappingContext)}[]`;
       case 'tuple': {
         const t = type as { kind: 'tuple'; elementTypes: TypescriptType[] };
-        const parts = t.elementTypes.map(e => this.typeToTs(e)).join(', ');
+        const parts = t.elementTypes.map(e => this.typeToTs(e, ctx, mappingContext)).join(', ');
         return `[${parts}]`;
       }
       case 'object': {
         const t = type;
         // If it's a simple Record<string, T> pattern, use that syntax
         if (t.properties.length === 0 && t.indexSignature) {
-          const keyType = this.typeToTs(t.indexSignature.keyType);
-          const valueType = this.typeToTs(t.indexSignature.valueType);
+          const keyType = this.typeToTs(t.indexSignature.keyType, ctx, mappingContext);
+          const valueType = this.typeToTs(t.indexSignature.valueType, ctx, mappingContext);
           if (keyType === 'string') {
             return `Record<string, ${valueType}>`;
           }
@@ -1092,34 +1180,56 @@ ${ctorSpec.declaration}  static fromHandle${classTypeParamDecl}(handle: string):
         const props = t.properties
           .map(
             p =>
-              `${p.readonly ? 'readonly ' : ''}${p.name}${p.optional ? '?' : ''}: ${this.typeToTs(p.type)};`
+              `${p.readonly ? 'readonly ' : ''}${p.name}${p.optional ? '?' : ''}: ${this.typeToTs(p.type, ctx, mappingContext)};`
           )
           .join(' ');
         const indexSig = t.indexSignature
-          ? `[key: ${this.typeToTs(t.indexSignature.keyType)}]: ${this.typeToTs(t.indexSignature.valueType)};`
+          ? `[key: ${this.typeToTs(t.indexSignature.keyType, ctx, mappingContext)}]: ${this.typeToTs(t.indexSignature.valueType, ctx, mappingContext)};`
           : '';
         return `{ ${props} ${indexSig} }`;
       }
       case 'union':
-        return type.types.map(t => this.typeToTs(t)).join(' | ');
+        return type.types.map(t => this.typeToTs(t, ctx, mappingContext)).join(' | ');
       case 'function': {
         const ft = type;
         const params = ft.parameters
           .map(
-            p => `${p.rest ? '...' : ''}${p.name}${p.optional ? '?' : ''}: ${this.typeToTs(p.type)}`
+            p =>
+              `${p.rest ? '...' : ''}${p.name}${p.optional ? '?' : ''}: ${this.typeToTs(p.type, ctx, mappingContext)}`
           )
           .join(', ');
-        return `(${params}) => ${this.typeToTs(ft.returnType)}`;
+        return `(${params}) => ${this.typeToTs(ft.returnType, ctx, mappingContext)}`;
       }
       case 'generic': {
-        const g = type as { kind: 'generic'; name: string; typeArgs: TypescriptType[] };
-        const args = g.typeArgs.map(a => this.typeToTs(a)).join(', ');
+        const g = type as {
+          kind: 'generic';
+          name: string;
+          module?: string;
+          typeArgs: TypescriptType[];
+        };
+        if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(g.name)) {
+          return this.degradeType(g);
+        }
+        if (mappingContext === 'return' && this.nonDecodableReturnGenerics.has(g.name)) {
+          return this.degradeType(g);
+        }
+        if (ctx && !this.builtinGenericNames.has(g.name) && !this.isLocalTypeIdentity(g, ctx)) {
+          return this.degradeType(g);
+        }
+        const args = g.typeArgs.map(a => this.typeToTs(a, ctx, mappingContext)).join(', ');
         return `${g.name}<${args}>`;
       }
       case 'custom': {
-        const c = type as { kind: 'custom'; name: string };
+        const c = type as { kind: 'custom'; name: string; module?: string };
         if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(c.name)) {
-          return 'unknown';
+          return this.degradeType(c);
+        }
+        if (
+          ctx &&
+          !this.isLocalTypeIdentity(c, ctx) &&
+          !(c.module === 'typing' && ctx.emittedNames.has(c.name))
+        ) {
+          return this.degradeType(c);
         }
         return c.name;
       }