tywrap 0.8.0 → 0.10.0

package/dist/core/generator.js

@@ -6,6 +6,28 @@ import { emitArgGuards, emitCallPrelude, } from './emit-call.js';
 import { TypeMapper } from './mapper.js';
 export class CodeGenerator {
     mapper;
+    onTypeDegrade;
+    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.
+    nonDecodableReturnGenerics = new Set([
+        'Generator',
+        'AsyncGenerator',
+        'Iterator',
+        'AsyncIterator',
+    ]);
     reservedTsIdentifiers = new Set([
         'default',
         'delete',
@@ -34,8 +56,9 @@ export class CodeGenerator {
         'true',
         'false',
     ]);
-    constructor(mapper = new TypeMapper()) {
+    constructor(mapper = new TypeMapper(), options = {}) {
         this.mapper = mapper;
+        this.onTypeDegrade = options.onTypeDegrade;
     }
     /**
      * Convert Python snake_case to TypeScript camelCase and escape reserved words
@@ -93,7 +116,7 @@ export class CodeGenerator {
     getTypeParameters(typeParameters) {
         return typeParameters ?? [];
     }
-    buildGenericRenderContext(typeParameters, types, currentModule) {
+    buildGenericRenderContext(typeParameters, types, currentModule, localDeclaredNames = new Set()) {
         const callableParamSpecs = new Set();
         types.forEach(type => this.collectCallableParamSpecs(type, callableParamSpecs));
         const emitted = [];
@@ -116,6 +139,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(', ')}>` : '',
             emittedNames,
@@ -125,6 +149,7 @@ export class CodeGenerator {
     mergeGenericRenderContexts(outer, inner) {
         return {
             currentModule: inner.currentModule ?? outer.currentModule,
+            localDeclaredNames: inner.localDeclaredNames,
             declaration: inner.declaration,
             typeArguments: inner.typeArguments,
             emittedNames: new Set([...outer.emittedNames, ...inner.emittedNames]),
@@ -240,7 +265,18 @@ export class CodeGenerator {
         }
     }
     typeToTsFromPython(type, ctx, mappingContext) {
-        return this.typeToTs(this.mapper.mapPythonType(this.sanitizeType(type, ctx), mappingContext));
+        return this.typeToTs(this.mapper.mapPythonType(this.sanitizeType(type, ctx), mappingContext), ctx, mappingContext);
+    }
+    isLocalTypeIdentity(type, ctx) {
+        if (!ctx.localDeclaredNames.has(type.name)) {
+            return false;
+        }
+        return type.module === undefined || type.module === ctx.currentModule;
+    }
+    degradeType(type) {
+        const identity = type.module ? `${type.module}.${type.name}` : type.name;
+        this.onTypeDegrade?.(identity);
+        return 'unknown';
     }
     renderLooksLikeKwargsExpr(valueExpr, options) {
         const base = `typeof ${valueExpr} === 'object' && ${valueExpr} !== null && !globalThis.Array.isArray(${valueExpr}) && (Object.getPrototypeOf(${valueExpr}) === Object.prototype || Object.getPrototypeOf(${valueExpr}) === null)`;
@@ -270,7 +306,154 @@ export class CodeGenerator {
             renderLooksLikeKwargsExpr: (valueExpr, options) => this.renderLooksLikeKwargsExpr(valueExpr, options),
         };
     }
-    generateFunctionWrapper(func, moduleName, annotatedJSDoc = false) {
+    /**
+     * 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.
+     */
+    returnSchema(type, definitions = new Set()) {
+        // 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) => {
+            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' };
+                    }
+                    if (['csr_matrix', 'csc_matrix', 'coo_matrix', 'spmatrix'].includes(leaf) &&
+                        (!current.module || current.module.startsWith('scipy'))) {
+                        return { kind: 'marker', marker: 'scipy.sparse' };
+                    }
+                    if (leaf === 'Tensor' && (!current.module || current.module.startsWith('torch'))) {
+                        return { kind: 'marker', marker: 'torch.tensor' };
+                    }
+                    if (leaf === 'BaseEstimator' &&
+                        (!current.module || current.module.startsWith('sklearn'))) {
+                        return { kind: 'marker', marker: 'sklearn.estimator' };
+                    }
+                    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);
+    }
+    returnDefinitions(module) {
+        return new Set(module.classes
+            .filter(cls => cls.kind === 'typed_dict' || cls.decorators.includes('__typed_dict__'))
+            .map(cls => cls.name));
+    }
+    emitReturnDefinitions(module) {
+        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, moduleName, annotatedJSDoc = false, localDeclaredNames = new Set(), returnDefinitions = new Set()) {
         const jsdoc = this.generateJsDoc(func.docstring, annotatedJSDoc ? func.parameters.map(p => String(p.type)) : undefined);
         const filteredParams = func.parameters.filter(p => p.name !== 'self' && p.name !== 'cls');
         const keywordOnlyParams = filteredParams.filter(p => p.keywordOnly);
@@ -280,7 +463,7 @@ export class CodeGenerator {
         const varArgsParam = filteredParams.find(p => p.varArgs);
         const needsVarArgsArray = Boolean(varArgsParam) && needsKwargsParam;
         const positionalParams = filteredParams.filter(p => !p.keywordOnly && !p.varArgs && !p.kwArgs);
-        const genericContext = this.buildGenericRenderContext(this.getTypeParameters(func.typeParameters), [func.returnType, ...filteredParams.map(param => param.type)], moduleName);
+        const genericContext = this.buildGenericRenderContext(this.getTypeParameters(func.typeParameters), [func.returnType, ...filteredParams.map(param => param.type)], moduleName, localDeclaredNames);
         const typeParamDecl = genericContext.declaration;
         const tsTypeForValue = (p) => this.typeToTsFromPython(p.type, genericContext, 'value');
         const kwargsType = (() => {
@@ -336,6 +519,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
         // `fn(a)`, `fn(a, b)`, ... all to typecheck. We emit a family of overloads that progressively
@@ -413,8 +598,8 @@ export class CodeGenerator {
         const guards = guardLines.length > 0 ? `${guardLines.join('\n')}\n` : '';
         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});
 }
 `;
         const declarationBody = overloads.length > 0
@@ -422,7 +607,9 @@ ${callPrelude}${guards}  return getRuntimeBridge().call('${moduleId}', '${func.n
             : `export function ${fname}${typeParamDecl}(${paramDecl}): Promise<${returnType}>;\n`;
         return this.wrap(ts, `${jsdoc}${declarationBody}`, [func.name]);
     }
-    generateClassWrapper(cls, moduleName, _annotatedJSDoc = false) {
+    generateClassWrapper(cls, moduleName, _annotatedJSDoc = false, localDeclaredNames = new Set(), returnDefinitions = new Set()) {
+        const moduleDeclaredNames = new Set(localDeclaredNames);
+        moduleDeclaredNames.add(cls.name);
         const jsdoc = this.generateJsDoc(cls.docstring);
         const classGenericContext = this.buildGenericRenderContext(this.getTypeParameters(cls.typeParameters), [
             ...cls.properties.map(property => property.type),
@@ -431,11 +618,9 @@ ${callPrelude}${guards}  return getRuntimeBridge().call('${moduleId}', '${func.n
                 method.returnType,
                 ...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) => this.typeToTsFromPython(p.type, classGenericContext, 'value');
         const wrapAlias = (body) => {
             const ts = `${jsdoc}export type ${cname}${classTypeParamDecl} = ${body}\n`;
             return this.wrap(ts, ts, [cls.name]);
@@ -469,7 +654,7 @@ ${callPrelude}${guards}  return getRuntimeBridge().call('${moduleId}', '${func.n
                 .filter(m => m.name !== '__init__')
                 .map(m => {
                 const fparams = m.parameters.filter(p => p.name !== 'self' && p.name !== 'cls');
-                const methodOwnGenericContext = this.buildGenericRenderContext(this.getTypeParameters(m.typeParameters), [m.returnType, ...fparams.map(param => param.type)], moduleName);
+                const methodOwnGenericContext = this.buildGenericRenderContext(this.getTypeParameters(m.typeParameters), [m.returnType, ...fparams.map(param => param.type)], moduleName, moduleDeclaredNames);
                 const methodGenericContext = this.mergeGenericRenderContexts(classGenericContext, methodOwnGenericContext);
                 const methodTypeParamDecl = methodOwnGenericContext.declaration;
                 const paramsDecl = fparams
@@ -497,16 +682,14 @@ ${callPrelude}${guards}  return getRuntimeBridge().call('${moduleId}', '${func.n
         const methodBodies = [];
         const methodDeclarations = [];
         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);
+            const methodOwnGenericContext = this.buildGenericRenderContext(this.getTypeParameters(method.typeParameters), [method.returnType, ...fparams.map(param => param.type)], moduleName, moduleDeclaredNames);
             const methodGenericContext = this.mergeGenericRenderContexts(classGenericContext, methodOwnGenericContext);
             const methodTypeParamDecl = methodOwnGenericContext.declaration;
             const methodTsValueType = (p) => this.typeToTsFromPython(p.type, methodGenericContext, 'value');
@@ -553,6 +736,8 @@ ${callPrelude}${guards}  return getRuntimeBridge().call('${moduleId}', '${func.n
             const requiredKwOnlyNames = keywordOnlyParams.filter(p => !p.optional).map(p => p.name);
             const returnType = this.typeToTsFromPython(method.returnType, methodGenericContext, '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 = [];
             if (needsKwargsParam && requiredKwOnlyNames.length > 0) {
                 const firstOptionalIndex = positionalParams.findIndex(p => p.optional);
@@ -589,154 +774,33 @@ ${callPrelude}${guards}  return getRuntimeBridge().call('${moduleId}', '${func.n
             const callPrelude = callPreludeLines.length > 0 ? `${callPreludeLines.join('\n')}\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: [],
-                };
-            }
-            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, forceRequired = false) => {
-                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 = [];
-            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 = [];
-            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 = [];
-                    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 = {
-                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 = [];
-        const accessorDeclarations = [];
-        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, moduleName) {
-        const genericContext = this.buildGenericRenderContext(this.getTypeParameters(alias.typeParameters), [alias.type], moduleName);
+    generateTypeAlias(alias, moduleName, localDeclaredNames = new Set()) {
+        const genericContext = this.buildGenericRenderContext(this.getTypeParameters(alias.typeParameters), [alias.type], moduleName, localDeclaredNames);
         const aliasName = this.escapeIdentifier(alias.name, { preserveCase: true });
         const body = this.typeToTsFromPython(alias.type, genericContext, 'value');
         const ts = `export type ${aliasName}${genericContext.declaration} = ${body}\n`;
@@ -761,15 +825,19 @@ ${ctorSpec.declaration}  static fromHandle${classTypeParamDecl}(handle: string):
         return result;
     }
     generateModuleDefinition(module, annotatedJSDoc = false) {
+        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');
         const typeAliasCodes = typeAliasResults.map(result => result.typescript).join('\n');
@@ -780,7 +848,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
             .map(result => result.declaration)
@@ -818,53 +888,67 @@ ${ctorSpec.declaration}  static fromHandle${classTypeParamDecl}(handle: string):
             },
         };
     }
-    typeToTs(type) {
+    typeToTs(type, ctx, mappingContext = 'value') {
         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;
-                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}>`;
                     }
                 }
                 const props = t.properties
-                    .map(p => `${p.readonly ? 'readonly ' : ''}${p.name}${p.optional ? '?' : ''}: ${this.typeToTs(p.type)};`)
+                    .map(p => `${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)}`)
+                    .map(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;
-                const args = g.typeArgs.map(a => this.typeToTs(a)).join(', ');
+                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;
                 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;
             }