@an5/orm 1.0.9 → 1.1.0

package/dist/generator/src/push-schema.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Reading `.an5` files for `db:push`.
+ *
+ * `SchemaParser` and `parseSchemaText` cover the generators and `db:migrate`;
+ * this is the third reader, and it exists because push needs a shape of its own:
+ * raw `@default` expressions rather than rendered SQL, and the schema a table
+ * lands in. It is kept here rather than inline in `push.ts` so the mapping from
+ * schema text to a column can be tested without a database.
+ */
+import { FieldTypeIssue, Provider } from './field-types';
+/** A column, as push needs it: the type as written plus what the dialect renders. */
+export interface PushField {
+    name: string;
+    sqlType: string;
+    isOptional: boolean;
+    isId: boolean;
+    isUnique: boolean;
+    /** The `@default(...)` expression, not SQL: only the dialect knows the spelling. */
+    defaultExpr?: string | undefined;
+}
+export interface PushModel {
+    name: string;
+    tableName: string;
+    /** The schema to create the table in; `''` when the provider has none. */
+    schema: string;
+    /** Set only when the schema file named one, so a wrong one can be reported. */
+    declaredSchema?: string | undefined;
+    fields: PushField[];
+    /** `@@unique([a, b])`, as field lists. */
+    compoundUniques: PushIndex[];
+    /** `@@index([a, b])`, as field lists. */
+    indexes: PushIndex[];
+}
+/**
+ * The schema a model lands in when the schema file does not say: none, for every
+ * provider, so the name goes wherever the connection resolves.
+ *
+ * The parser used to default this to `dbo` and push followed it, which failed two
+ * ways: SQLite said "unknown database [dbo]", and a SQL Server login whose default
+ * schema was something else had push look for `[dbo].[widgets]`, miss the table it
+ * had created, and then fail with "there is already an object named ...".
+ */
+export declare function defaultSchemaFor(_provider: Provider): string;
+/**
+ * One `@@unique` or `@@index`, with the options `db:migrate` already understands.
+ *
+ * `name` matters as much as the fields: `map:` is how a schema asks for a specific
+ * artifact name, and if push invented its own the two commands would create two
+ * different constraints for the same directive — and the next migration would keep
+ * trying to add the one push never made.
+ */
+export interface PushIndex {
+    fields: string[];
+    name?: string | undefined;
+    includeFields?: string[] | undefined;
+    filter?: string | undefined;
+    options?: string | undefined;
+}
+export interface PushSchema {
+    models: PushModel[];
+    /** Field types the provider does not have; empty when the schema is valid. */
+    issues: FieldTypeIssue[];
+}
+/**
+ * The name a `@@unique` or `@@index` artifact gets.
+ *
+ * `map:` wins; otherwise the name is derived from the table and fields, which is what
+ * both commands have always done for an unnamed directive.
+ */
+export declare function directiveName(directive: PushIndex, table: string, kind: 'compound' | 'index', position: number): string;
+/**
+ * Reads schema text for push, validating every field type against the provider.
+ *
+ * All bad types come back in `issues` rather than as an exception, so the caller
+ * can print them as a group. A field whose type matches no table is only a
+ * mistake once the whole schema has been read: it may be a relation to a model
+ * declared further down.
+ */
+export declare function parsePushSchema(text: string, provider: Provider): PushSchema;
+/**
+ * The table name to create, `schema.table` unless the model cleared the schema.
+ *
+ * An empty schema has to stay empty: `[].[widgets]` is not valid SQL, which is the
+ * whole reason `@@schema("")` exists.
+ */
+/**
+ * An identifier for a generated artifact name: letters, digits and underscores only.
+ *
+ * The name goes into DDL as an identifier, so anything else is replaced rather than
+ * quoted — `@@map("catalog entries")` must not produce a name the provider rejects.
+ */
+export declare function safeIdentifierName(raw: string): string;
+export declare function qualifiedTableName(model: PushModel): string;

package/dist/generator/src/push-schema.js

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultSchemaFor = defaultSchemaFor;
+exports.directiveName = directiveName;
+exports.parsePushSchema = parsePushSchema;
+exports.safeIdentifierName = safeIdentifierName;
+exports.qualifiedTableName = qualifiedTableName;
+/**
+ * Reading `.an5` files for `db:push`.
+ *
+ * `SchemaParser` and `parseSchemaText` cover the generators and `db:migrate`;
+ * this is the third reader, and it exists because push needs a shape of its own:
+ * raw `@default` expressions rather than rendered SQL, and the schema a table
+ * lands in. It is kept here rather than inline in `push.ts` so the mapping from
+ * schema text to a column can be tested without a database.
+ */
+const field_types_1 = require("./field-types");
+/**
+ * The schema a model lands in when the schema file does not say: none, for every
+ * provider, so the name goes wherever the connection resolves.
+ *
+ * The parser used to default this to `dbo` and push followed it, which failed two
+ * ways: SQLite said "unknown database [dbo]", and a SQL Server login whose default
+ * schema was something else had push look for `[dbo].[widgets]`, miss the table it
+ * had created, and then fail with "there is already an object named ...".
+ */
+function defaultSchemaFor(_provider) {
+    return '';
+}
+/** The field list of `@@unique([a, b], …)`, plus whatever options follow it. */
+const DIRECTIVE = /^@@(?:unique|index)\(\s*\[([\w\s,]+)\]([^)]*)\)/;
+function parseDirective(line, fields) {
+    const options = line.match(DIRECTIVE)?.[2] ?? '';
+    const name = options.match(/\bmap\s*:\s*"([^"]+)"/)?.[1];
+    const include = options.match(/\binclude\s*:\s*\[([\w,\s]+)\]/)?.[1];
+    const filter = options.match(/\bfilter\s*:\s*"([^"]+)"/)?.[1];
+    const opts = options.match(/\boptions\s*:\s*"([^"]+)"/)?.[1];
+    return {
+        fields: fields.split(',').map((field) => field.trim()).filter(Boolean),
+        ...(name ? { name } : {}),
+        ...(include ? { includeFields: include.split(',').map((field) => field.trim()).filter(Boolean) } : {}),
+        ...(filter ? { filter } : {}),
+        ...(opts ? { options: opts } : {}),
+    };
+}
+/**
+ * The name a `@@unique` or `@@index` artifact gets.
+ *
+ * `map:` wins; otherwise the name is derived from the table and fields, which is what
+ * both commands have always done for an unnamed directive.
+ */
+function directiveName(directive, table, kind, position) {
+    if (directive.name)
+        return safeIdentifierName(directive.name);
+    const base = safeIdentifierName(table);
+    return kind === 'compound'
+        ? `UQ_${base}_compound_${position}`
+        : `IX_${base}_${directive.fields.join('_')}`;
+}
+/**
+ * Reads schema text for push, validating every field type against the provider.
+ *
+ * All bad types come back in `issues` rather than as an exception, so the caller
+ * can print them as a group. A field whose type matches no table is only a
+ * mistake once the whole schema has been read: it may be a relation to a model
+ * declared further down.
+ */
+function parsePushSchema(text, provider) {
+    const models = [];
+    const issues = [];
+    const modelRefs = [];
+    let current = null;
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (!line || line.startsWith('//'))
+            continue;
+        const header = line.match(/^model\s+(\w+)\s*\{/);
+        if (header) {
+            current = {
+                name: header[1],
+                tableName: header[1].toLowerCase() + 's',
+                schema: defaultSchemaFor(provider),
+                fields: [],
+                compoundUniques: [],
+                indexes: [],
+            };
+            models.push(current);
+            continue;
+        }
+        if (line === '}') {
+            current = null;
+            continue;
+        }
+        if (!current)
+            continue;
+        if (line.startsWith('@@map')) {
+            const match = line.match(/@@map\("(.+)"\)/);
+            if (match)
+                current.tableName = match[1];
+            continue;
+        }
+        if (line.startsWith('@@schema')) {
+            // `(.*)` rather than `(.+)`, because `@@schema("")` is how a model says "no
+            // schema" and has to survive as an empty string rather than being dropped as
+            // no match — which is how SQLite and MySQL schemas are written.
+            const match = line.match(/@@schema\("(.*)"\)/);
+            if (match) {
+                current.schema = match[1].trim();
+                current.declaredSchema = current.schema;
+            }
+            continue;
+        }
+        if (line.startsWith('@@unique') || line.startsWith('@@index')) {
+            const match = line.match(DIRECTIVE);
+            if (match) {
+                const definition = parseDirective(line, match[1] ?? '');
+                if (line.startsWith('@@unique'))
+                    current.compoundUniques.push(definition);
+                else
+                    current.indexes.push(definition);
+            }
+            continue;
+        }
+        if (line.startsWith('@@'))
+            continue;
+        const head = (0, field_types_1.readFieldLineHead)(line);
+        if (!head)
+            continue;
+        if (!(0, field_types_1.resolveFieldType)(head.type, provider)) {
+            modelRefs.push({ model: current.name, field: head.name, type: head.type });
+            continue;
+        }
+        // The type is kept as written (upper-cased) because that is what the database
+        // is told; which types exist is what `resolveFieldType` just checked.
+        current.fields.push({
+            name: head.name,
+            sqlType: head.type.toUpperCase(),
+            isOptional: head.isOptional,
+            isId: line.includes('@id'),
+            isUnique: line.includes('@unique'),
+            // The expression rather than SQL: `uuid()` and `autoincrement()` are spelled
+            // differently per provider, and only the dialect knows how. `@updatedAt` is
+            // `now()` under another name.
+            defaultExpr: line.match(/@default\((.*)\)/)?.[1]
+                ?? (line.includes('@updatedAt') ? 'now()' : undefined),
+        });
+    }
+    // A declared `dbo` on a provider without schemas would push to a database that
+    // does not exist there; SQLite answers "unknown database [dbo]", which says
+    // nothing about the schema file. Only an explicit declaration is worth reporting:
+    // an absent one now means "whatever the connection resolves", on every provider.
+    for (const model of models) {
+        if (model.declaredSchema === 'dbo' && provider !== 'mssql') {
+            issues.push({
+                path: model.name,
+                message: `schema "dbo" does not exist in ${provider}; remove the @@schema directive or set it ` +
+                    'to the schema this database uses',
+            });
+        }
+    }
+    const modelNames = models.map((model) => model.name);
+    for (const ref of modelRefs) {
+        if (!modelNames.includes(ref.type)) {
+            issues.push({
+                path: `${ref.model}.${ref.field}`,
+                message: (0, field_types_1.unknownFieldTypeMessage)(ref.type, provider, modelNames),
+            });
+        }
+    }
+    return { models, issues };
+}
+/**
+ * The table name to create, `schema.table` unless the model cleared the schema.
+ *
+ * An empty schema has to stay empty: `[].[widgets]` is not valid SQL, which is the
+ * whole reason `@@schema("")` exists.
+ */
+/**
+ * An identifier for a generated artifact name: letters, digits and underscores only.
+ *
+ * The name goes into DDL as an identifier, so anything else is replaced rather than
+ * quoted — `@@map("catalog entries")` must not produce a name the provider rejects.
+ */
+function safeIdentifierName(raw) {
+    return raw.replace(/[^A-Za-z0-9_]/g, '_').replace(/_+/g, '_').replace(/^_|_$/g, '');
+}
+function qualifiedTableName(model) {
+    return model.schema ? `${model.schema}.${model.tableName}` : model.tableName;
+}

package/dist/generator/src/python-generator.d.ts

@@ -2,12 +2,30 @@ import { Model } from './types';
 export declare class PythonGenerator {
     private outputPath;
     constructor(outputPath: string);
+    /**
+     * The metadata module name, taken from the configured file name itself.
+     *
+     * The imports used to hardcode `an5_metadata` while `outputPath` was
+     * configurable, so setting `python.metadataFile` to another name (say
+     * `an5Metadata.py`) still generated `from an5_metadata import ...` and the
+     * client broke on import — a failure that only showed up at runtime.
+     */
+    private metadataModule;
+    /** The database being generated for; decides types like `TIMESTAMP`. */
+    private provider;
     generate(models: Model[]): void;
     private getPyFilterType;
     private generateOrmTypes;
     private generateMetadata;
+    /**
+     * The Python type for a field.
+     *
+     * From the declared type, so `DECIMAL` is a `float` and `BIGINT` stays an `int`:
+     * both arrived as `number` before and took the integer branch.
+     */
     private mapPyType;
-    private generateModels;
+    private generateModelFile;
+    private generateModelsIndex;
     private generateClient;
     private generateInit;
     private getAllPropertyVariations;

package/dist/generator/src/python-generator.js

@@ -6,37 +6,53 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PythonGenerator = void 0;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const types_1 = require("./types");
+const type_kinds_1 = require("./type-kinds");
 class PythonGenerator {
     constructor(outputPath) {
         this.outputPath = outputPath;
     }
+    /**
+     * The metadata module name, taken from the configured file name itself.
+     *
+     * The imports used to hardcode `an5_metadata` while `outputPath` was
+     * configurable, so setting `python.metadataFile` to another name (say
+     * `an5Metadata.py`) still generated `from an5_metadata import ...` and the
+     * client broke on import — a failure that only showed up at runtime.
+     */
+    metadataModule() {
+        return path_1.default.basename(this.outputPath).replace(/\.py$/i, '');
+    }
     generate(models) {
+        this.provider = models[0]?.provider;
         const outputDir = path_1.default.dirname(this.outputPath);
         if (!fs_1.default.existsSync(outputDir)) {
             fs_1.default.mkdirSync(outputDir, { recursive: true });
         }
         // 1. Generate an5_metadata.py
         this.generateMetadata(models);
-        // 2. Generate an5_models.py
-        this.generateModels(models, outputDir);
-        // 3. Generate an5_orm_types.py - type-safe ORM filter/args dataclasses
+        // 2. Generate per-model entity files like dotnet (<Model>.py)
+        for (const model of models) {
+            this.generateModelFile(model, outputDir);
+        }
+        // 3. Generate an5_models.py as backward-compat aggregator
+        this.generateModelsIndex(models, outputDir);
+        // 4. Generate an5_orm_types.py - type-safe ORM filter/args dataclasses
         this.generateOrmTypes(models, outputDir);
-        // 4. Generate an5_client.py
+        // 5. Generate an5_client.py
         this.generateClient(models, outputDir);
-        // 5. Generate __init__.py
+        // 6. Generate __init__.py
         this.generateInit(models, outputDir);
     }
-    getPyFilterType(fieldType) {
-        const lower = fieldType.toLowerCase();
-        if (['datetime', 'datetime2', 'date', 'smalldatetime', 'datetimeoffset', 'timestamp'].includes(lower))
-            return 'DateTimeFilter';
-        if (['bool', 'boolean', 'bit'].includes(lower))
-            return 'BoolFilter';
-        if (['int', 'integer', 'smallint', 'tinyint', 'bigint', 'number'].includes(lower))
-            return 'IntFilter';
-        if (['float', 'real', 'double', 'decimal', 'numeric', 'money'].includes(lower))
-            return 'NumberFilter';
-        return 'StringFilter';
+    getPyFilterType(field) {
+        switch ((0, type_kinds_1.fieldKind)(field, this.provider)) {
+            case 'date': return 'DateTimeFilter';
+            case 'bool': return 'BoolFilter';
+            case 'int':
+            case 'bigint': return 'IntFilter';
+            case 'float': return 'NumberFilter';
+            default: return 'StringFilter';
+        }
     }
     generateOrmTypes(models, outputDir) {
         let content = '# This file is auto-generated. Do not edit directly.\n';
@@ -62,7 +78,7 @@ class PythonGenerator {
             content += `    OR: Optional[List['${name}WhereInput']] = None\n`;
             content += `    NOT: Optional['${name}WhereInput'] = None\n`;
             for (const f of model.fields) {
-                const ft = this.getPyFilterType(f.type);
+                const ft = this.getPyFilterType(f);
                 content += `    ${this.toSnakeCase(f.name)}: Optional[${ft}] = None\n`;
             }
             content += '\n';
@@ -77,10 +93,10 @@ class PythonGenerator {
             const optionalFields = model.fields.filter(f => !f.isId && (f.isOptional || f.hasDefault));
             content += `@dataclass\nclass ${name}CreateInput:\n    """Typed data for creating a new ${name} record."""\n`;
             for (const f of requiredFields) {
-                content += `    ${this.toSnakeCase(f.name)}: ${this.mapPyType(f.type)}\n`;
+                content += `    ${this.toSnakeCase(f.name)}: ${this.mapPyType(f)}\n`;
             }
             for (const f of optionalFields) {
-                content += `    ${this.toSnakeCase(f.name)}: Optional[${this.mapPyType(f.type)}] = None\n`;
+                content += `    ${this.toSnakeCase(f.name)}: Optional[${this.mapPyType(f)}] = None\n`;
             }
             if (requiredFields.length === 0 && optionalFields.length === 0)
                 content += '    pass\n';
@@ -89,7 +105,7 @@ class PythonGenerator {
             const updateFields = model.fields.filter(f => !f.isId);
             content += `@dataclass\nclass ${name}UpdateInput:\n    """Typed data for updating an existing ${name} record."""\n`;
             for (const f of updateFields) {
-                content += `    ${this.toSnakeCase(f.name)}: Optional[${this.mapPyType(f.type)}] = None\n`;
+                content += `    ${this.toSnakeCase(f.name)}: Optional[${this.mapPyType(f)}] = None\n`;
             }
             if (updateFields.length === 0)
                 content += '    pass\n';
@@ -115,7 +131,7 @@ class PythonGenerator {
         pyContent += 'MODEL_TO_TABLE = {\n';
         for (const model of models) {
             const props = this.getAllPropertyVariations(model.name);
-            const fullTableName = `[${model.schemaName}].[${model.tableName}]`;
+            const fullTableName = (0, types_1.bracketedTableName)(model);
             for (const prop of props) {
                 pyContent += `    "${prop}": "${fullTableName}",\n`;
             }
@@ -161,49 +177,50 @@ class PythonGenerator {
         pyContent += '}\n';
         fs_1.default.writeFileSync(this.outputPath, pyContent);
     }
-    mapPyType(fieldType) {
-        const lower = fieldType.toLowerCase();
-        if (['int', 'integer', 'smallint', 'tinyint', 'bigint', 'number'].includes(lower)) {
-            return 'int';
-        }
-        if (['float', 'real', 'double', 'decimal', 'numeric', 'money'].includes(lower)) {
-            return 'float';
+    /**
+     * The Python type for a field.
+     *
+     * From the declared type, so `DECIMAL` is a `float` and `BIGINT` stays an `int`:
+     * both arrived as `number` before and took the integer branch.
+     */
+    mapPyType(field) {
+        switch ((0, type_kinds_1.fieldKind)(field, this.provider)) {
+            case 'int':
+            case 'bigint': return 'int';
+            case 'float': return 'float';
+            case 'bool': return 'bool';
+            case 'date': return 'datetime';
+            case 'bytes': return 'bytes';
+            case 'json': return 'Any';
+            case 'vector': return 'List[float]';
+            default: return 'str';
         }
-        if (['bool', 'boolean', 'bit'].includes(lower)) {
-            return 'bool';
-        }
-        if (['datetime', 'datetime2', 'date', 'smalldatetime', 'datetimeoffset', 'timestamp'].includes(lower)) {
-            return 'datetime';
-        }
-        if (['bytes', 'binary', 'varbinary'].includes(lower)) {
-            return 'bytes';
-        }
-        return 'str';
     }
-    generateModels(models, outputDir) {
+    generateModelFile(model, outputDir) {
+        // Single-entity file like dotnet `${model.name}.cs` / typescript `${model.name}.ts`.
+        // Contains the @dataclass entity + TypedDict row shapes for that model only.
         let content = '# This file is auto-generated. Do not edit directly.\n';
         content += 'from dataclasses import dataclass, field\n';
-        content += 'from typing import Optional, List, Any\n';
+        content += 'from typing import Optional, List, Any, TypedDict\n';
         content += 'from datetime import datetime\n\n';
-        for (const model of models) {
-            if (model.description) {
-                content += `"""${model.description}"""\n`;
-            }
-            content += `@dataclass\nclass ${model.name}:\n`;
-            if (model.fields.length === 0 && model.relations.length === 0) {
-                content += '    pass\n\n';
-                continue;
-            }
+        if (model.description) {
+            content += `"""${model.description}"""\n`;
+        }
+        content += `@dataclass\nclass ${model.name}:\n`;
+        if (model.fields.length === 0 && model.relations.length === 0) {
+            content += '    pass\n\n';
+        }
+        else {
             // Required fields first
             const required = model.fields.filter(f => !f.isOptional && !f.hasDefault);
             const optionals = model.fields.filter(f => f.isOptional || f.hasDefault);
             for (const f of required) {
-                const pyType = this.mapPyType(f.type);
+                const pyType = this.mapPyType(f);
                 const snakeName = this.toSnakeCase(f.name);
                 content += `    ${snakeName}: ${pyType}\n`;
             }
             for (const f of optionals) {
-                const pyType = this.mapPyType(f.type);
+                const pyType = this.mapPyType(f);
                 const snakeName = this.toSnakeCase(f.name);
                 content += `    ${snakeName}: Optional[${pyType}] = None\n`;
             }
@@ -218,21 +235,87 @@ class PythonGenerator {
                 }
             }
             content += '\n';
+            // TypedDict row shape: mirrors what the runtime actually returns
+            // (plain dicts), so `AdapterTableClient["<Model>Row"]` delegates
+            // type-check. Required keys stay required via a total=True base;
+            // everything else is optional (total=False), keeping partial
+            // selects valid without extra dependencies.
+            const rowRequired = model.fields.filter(f => !f.isOptional && !f.hasDefault);
+            const rowOptional = model.fields.filter(f => f.isOptional || f.hasDefault);
+            content += `class _${model.name}Required(TypedDict):\n`;
+            content += `    """Required keys of a ${model.name} row."""\n`;
+            if (rowRequired.length === 0) {
+                content += '    pass\n';
+            }
+            for (const f of rowRequired) {
+                content += `    ${this.toSnakeCase(f.name)}: ${this.mapPyType(f)}\n`;
+            }
+            content += `\nclass ${model.name}Row(_${model.name}Required, total=False):\n`;
+            content += `    """Row shape returned for ${model.name} queries."""\n`;
+            if (rowOptional.length === 0 && model.relations.length === 0) {
+                content += '    pass\n';
+            }
+            for (const f of rowOptional) {
+                content += `    ${this.toSnakeCase(f.name)}: ${this.mapPyType(f)}\n`;
+            }
+            for (const rel of model.relations) {
+                const relName = this.toSnakeCase(rel.name);
+                content += rel.isArray ? `    ${relName}: List[Any]\n` : `    ${relName}: Any\n`;
+            }
+            content += '\n';
+        }
+        fs_1.default.writeFileSync(path_1.default.join(outputDir, `${model.name}.py`), content);
+    }
+    generateModelsIndex(models, outputDir) {
+        // Backward-compat aggregator: `from an5_models import User` keeps working.
+        // New code can also import directly: `from .User import User, UserRow`.
+        // Supports both package-relative (`python -m`) and top-level (`sys.path`
+        // pointing at the output dir) imports via try/except fallback.
+        let content = '# This file is auto-generated. Do not edit directly.\n';
+        content += '"""Backward-compat aggregator re-exporting per-model entity files."""\n';
+        for (const model of models) {
+            content += `try:\n`;
+            content += `    from .${model.name} import ${model.name}, ${model.name}Row, _${model.name}Required\n`;
+            content += `except ImportError:\n`;
+            content += `    from ${model.name} import ${model.name}, ${model.name}Row, _${model.name}Required\n`;
+        }
+        if (models.length > 0) {
+            content += '\n__all__ = [\n';
+            for (const model of models) {
+                content += `    "${model.name}", "${model.name}Row", "_${model.name}Required",\n`;
+            }
+            content += ']\n';
+        }
+        else {
+            content += '\n__all__ = []\n';
         }
         fs_1.default.writeFileSync(path_1.default.join(outputDir, 'an5_models.py'), content);
     }
     generateClient(models, outputDir) {
         let content = '# This file is auto-generated. Do not edit directly.\n';
         content += 'import os\n';
-        content += 'from typing import Dict, List, Optional, Any, Callable\n\n';
-        content += 'try:\n';
-        content += '    from an5_adapter import An5Adapter, AdapterTableClient, create_an5_adapter, set_adapter_metadata\n';
-        content += 'except ImportError:\n';
-        content += '    from .an5_adapter import An5Adapter, AdapterTableClient, create_an5_adapter, set_adapter_metadata\n\n';
+        content += 'from typing import Dict, List, Optional, Any, Callable, TYPE_CHECKING\n\n';
+        // Runtime adapter comes from the `an5-adapters` PyPI package
+        // (module `an5_adapter`). There is no local adapter file in the
+        // generated output dir, so no relative-import fallback here — a
+        // relative fallback would be unresolvable and trip Pylance
+        // `reportMissingImports` on every generated client.
+        content += 'from an5_adapter import An5Adapter, AdapterTableClient, create_an5_adapter, set_adapter_metadata\n\n';
+        const metadataModule = this.metadataModule();
         content += 'try:\n';
-        content += '    from .an5_metadata import MODEL_TO_TABLE, MODEL_FIELDS\n';
+        content += `    from .${metadataModule} import MODEL_TO_TABLE, MODEL_FIELDS\n`;
         content += 'except ImportError:\n';
-        content += '    from an5_metadata import MODEL_TO_TABLE, MODEL_FIELDS\n\n';
+        content += `    from ${metadataModule} import MODEL_TO_TABLE, MODEL_FIELDS\n\n`;
+        if (models.length > 0) {
+            content += 'if TYPE_CHECKING:\n';
+            for (const m of models) {
+                content += '    try:\n';
+                content += `        from .${m.name} import ${m.name}Row\n`;
+                content += '    except ImportError:\n';
+                content += `        from .an5_models import ${m.name}Row  # fallback aggregator\n`;
+            }
+            content += '\n';
+        }
         content += 'class An5Client:\n';
         content += '    """AN5 Python ORM Client - type-safe database access.\n\n';
         content += '    Usage:\n';
@@ -251,13 +334,13 @@ class PythonGenerator {
             const propName = this.toSnakeCase(model.name) + 's';
             const singleName = this.toSnakeCase(model.name);
             content += `        client = AdapterTableClient(self.adapter, "${model.name}")\n`;
-            content += `        self.${model.name}: AdapterTableClient = client\n`;
-            content += `        self.${model.name}s: AdapterTableClient = client\n`;
-            content += `        self.${singleName}: AdapterTableClient = client\n`;
-            content += `        self.${propName}: AdapterTableClient = client\n`;
+            content += `        self.${model.name}: AdapterTableClient["${model.name}Row"] = client\n`;
+            content += `        self.${model.name}s: AdapterTableClient["${model.name}Row"] = client\n`;
+            content += `        self.${singleName}: AdapterTableClient["${model.name}Row"] = client\n`;
+            content += `        self.${propName}: AdapterTableClient["${model.name}Row"] = client\n`;
         }
         content += '\n';
-        content += '    def __getattr__(self, name: str) -> AdapterTableClient:\n';
+        content += '    def __getattr__(self, name: str) -> AdapterTableClient[Any]:\n';
         content += '        return self.adapter.table(name)\n\n';
         content += '    def query_raw(self, sql: str, *params) -> List[Dict]:\n';
         content += '        return self.adapter.query_raw(sql, *params)\n\n';
@@ -269,7 +352,7 @@ class PythonGenerator {
     }
     generateInit(models, outputDir) {
         let content = '# This file is auto-generated. Do not edit directly.\n';
-        content += 'from .an5_metadata import MODEL_TO_TABLE, MODEL_DESCRIPTIONS, MODEL_FIELDS, RELATION_MAP\n';
+        content += `from .${this.metadataModule()} import MODEL_TO_TABLE, MODEL_DESCRIPTIONS, MODEL_FIELDS, RELATION_MAP\n`;
         content += 'from .an5_models import *\n';
         content += 'from .an5_orm_types import (\n';
         content += '    StringFilter, IntFilter, NumberFilter, BoolFilter, DateTimeFilter,\n';

package/dist/generator/src/rust-generator.d.ts

@@ -0,0 +1,38 @@
+import { Model } from './types';
+export declare class RustGenerator {
+    private outputDir;
+    /** The database being generated for; decides types like `TIMESTAMP`. */
+    private provider;
+    constructor(outputDir: string);
+    generate(models: Model[]): void;
+    private generateCargoToml;
+    private generateLibRs;
+    private generateFiltersRs;
+    private generateModelsRs;
+    private buildModelsBody;
+    private generateMetadataRs;
+    private generateConfigRs;
+    private generateClientRs;
+    /**
+     * Typed, executing accessors for a model.
+     *
+     * Rust has no dynamic property access, so `db.user` cannot exist the way it
+     * does in TypeScript or Python. Following the Go generator (which emits a
+     * real `ctx.User` field), each model gets a generated method returning a
+     * typed handle whose queries run through the an5-adapters runtime.
+     */
+    private buildModelRuntimeHandle;
+    private isBoolField;
+    /**
+     * The Rust type for a field.
+     *
+     * From the declared type, so `DECIMAL` is an `f64` and `BIGINT` an `i64`: both
+     * arrived as `number` and were written as `i64`.
+     */
+    private mapRustType;
+    private getRustFilterType;
+    private getAllPropertyVariations;
+    private capitalize;
+    private toCamelCase;
+    private toSnakeCase;
+}