tai-sql 0.7.20__tar.gz → 0.8.0__tar.gz

{tai_sql-0.7.20 → tai_sql-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tai-sql
-Version: 0.7.20
+Version: 0.8.0
 Summary: SQL database management and code generation tool
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
@@ -192,7 +192,7 @@ usuarios = public_sync_api.usuario.find_many(limit=10, includes=['posts'])
 | [El schema](https://triplealpha-innovation.github.io/tai-sql/schema/) | Todo lo que se puede declarar, y cómo |
 | [El CLI](https://triplealpha-innovation.github.io/tai-sql/cli/) | Qué hace cada comando, y qué puede destruir `push` |
 | [El cliente generado](https://triplealpha-innovation.github.io/tai-sql/cliente/) | La API que vas a usar desde tu aplicación |
-| [Referencia](https://triplealpha-innovation.github.io/tai-sql/referencia/dsl/) | Firmas del DSL, motores, extensión y catálogo de errores |
+| [Referencia](https://triplealpha-innovation.github.io/tai-sql/referencia/dsl/) | Firmas del DSL, motores, extensión, catálogo de errores y qué cambia al actualizar a la 0.8.0 |
 
 ---
 

{tai_sql-0.7.20 → tai_sql-0.8.0}/README.md

@@ -129,7 +129,7 @@ usuarios = public_sync_api.usuario.find_many(limit=10, includes=['posts'])
 | [El schema](https://triplealpha-innovation.github.io/tai-sql/schema/) | Todo lo que se puede declarar, y cómo |
 | [El CLI](https://triplealpha-innovation.github.io/tai-sql/cli/) | Qué hace cada comando, y qué puede destruir `push` |
 | [El cliente generado](https://triplealpha-innovation.github.io/tai-sql/cliente/) | La API que vas a usar desde tu aplicación |
-| [Referencia](https://triplealpha-innovation.github.io/tai-sql/referencia/dsl/) | Firmas del DSL, motores, extensión y catálogo de errores |
+| [Referencia](https://triplealpha-innovation.github.io/tai-sql/referencia/dsl/) | Firmas del DSL, motores, extensión, catálogo de errores y qué cambia al actualizar a la 0.8.0 |
 
 ---
 

{tai_sql-0.7.20 → tai_sql-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tai-sql"
-version = "0.7.20"
+version = "0.8.0"
 description = "SQL database management and code generation tool"
 license = "LicenseRef-Proprietary"
 license-files = ["LICENSE"]

{tai_sql-0.7.20 → tai_sql-0.8.0}/tai_sql/cli/commands/cmd_schema/schemas/chatbot.py

@@ -435,48 +435,130 @@ class ChatbotSchema(SchemaTemplate):
         ''').rstrip()
 
         consumo_diario_sql = dedent('''\
-            -- Vista para el consumo por usuario, día y modelo
+            -- Vista para el consumo por usuario, día y modelo. Los tokens y el importe son todos los
+            -- apuntes, tengan mensaje o no; los mensajes, los que envió el usuario
+            WITH consumo AS (
+                SELECT
+                    tu.username,
+                    DATE(tu.timestamp) as date,
+                    m.provider,
+                    m.model_name,
+                    SUM(tu.prompt_tokens) as total_prompt_tokens,
+                    SUM(tu.completion_tokens) as total_completion_tokens,
+                    SUM(tu.total_tokens) as total_tokens,
+                    SUM(ROUND(((tu.prompt_tokens * t.precio_input_eur_millon
+                              + tu.completion_tokens * t.precio_output_eur_millon)
+                              * t.margen / 1000000)::numeric, 8))::double precision as total_cost_eur,
+                    COUNT(DISTINCT COALESCE(tu.chat_id, me.chat_id)) as chat_count
+                FROM token_usage tu
+                JOIN tarifa t ON t.id = tu.tarifa_id
+                JOIN modelo m ON m.id = t.modelo_id
+                LEFT JOIN mensaje me ON me.id = tu.message_id
+                GROUP BY tu.username, DATE(tu.timestamp), m.provider, m.model_name
+            ),
+            -- Cada mensaje del usuario cuenta en el modelo al que se envió. Los anteriores a guardarlo,
+            -- en el de la respuesta que los siguió; sin ninguno de los dos no se cuentan
+            enviados AS (
+                SELECT
+                    c.username,
+                    DATE(u.timestamp) as date,
+                    COALESCE(u.provider, r.provider) as provider,
+                    COALESCE(u.model_name, r.model_name) as model_name,
+                    COUNT(*) as message_count
+                FROM mensaje u
+                JOIN chat c ON c.id = u.chat_id
+                LEFT JOIN LATERAL (
+                    SELECT a.provider, a.model_name
+                    FROM mensaje a
+                    WHERE a.chat_id = u.chat_id
+                      AND a.role IN ('asistente', 'ai', 'assistant')
+                      AND a.timestamp >= u.timestamp
+                    ORDER BY a.timestamp
+                    LIMIT 1
+                ) r ON u.model_name IS NULL
+                WHERE u.role IN ('usuario', 'human', 'user')
+                  AND COALESCE(u.model_name, r.model_name) IS NOT NULL
+                GROUP BY c.username, DATE(u.timestamp), COALESCE(u.provider, r.provider), COALESCE(u.model_name, r.model_name)
+            )
             SELECT
-                tu.username,
-                DATE(tu.timestamp) as date,
-                m.provider,
-                m.model_name,
-                SUM(tu.prompt_tokens) as total_prompt_tokens,
-                SUM(tu.completion_tokens) as total_completion_tokens,
-                SUM(tu.total_tokens) as total_tokens,
-                SUM(ROUND(((tu.prompt_tokens * t.precio_input_eur_millon
-                          + tu.completion_tokens * t.precio_output_eur_millon)
-                          * t.margen / 1000000)::numeric, 8))::double precision as total_cost_eur,
-                COUNT(DISTINCT COALESCE(tu.chat_id, me.chat_id)) as chat_count,
-                COUNT(*) as message_count
-            FROM token_usage tu
-            JOIN tarifa t ON t.id = tu.tarifa_id
-            JOIN modelo m ON m.id = t.modelo_id
-            LEFT JOIN mensaje me ON me.id = tu.message_id
-            GROUP BY tu.username, DATE(tu.timestamp), m.provider, m.model_name
-            ORDER BY date DESC, total_tokens DESC;
+                COALESCE(co.username, e.username) as username,
+                COALESCE(co.date, e.date) as date,
+                COALESCE(co.provider, e.provider) as provider,
+                COALESCE(co.model_name, e.model_name) as model_name,
+                COALESCE(co.total_prompt_tokens, 0) as total_prompt_tokens,
+                COALESCE(co.total_completion_tokens, 0) as total_completion_tokens,
+                COALESCE(co.total_tokens, 0) as total_tokens,
+                COALESCE(co.total_cost_eur, 0) as total_cost_eur,
+                COALESCE(co.chat_count, 0) as chat_count,
+                COALESCE(e.message_count, 0) as message_count
+            FROM consumo co
+            FULL JOIN enviados e
+                ON e.username = co.username AND e.date = co.date
+               AND e.provider = co.provider AND e.model_name = co.model_name
+            ORDER BY date DESC, username, total_tokens DESC;
         ''').rstrip()
 
         consumo_mensual_sql = dedent('''\
             -- Vista para el consumo y el coste por usuario, mes y modelo. El importe se calcula aquí:
-            -- el apunte guarda con qué tarifa se valora y el margen no sale de la tabla `tarifa`
+            -- el apunte guarda con qué tarifa se valora y el margen no sale de la tabla `tarifa`.
+            -- Los tokens y el importe son todos los apuntes, tengan mensaje o no (una redacción del modal
+            -- de incidencias también); los mensajes, los que envió el usuario
+            WITH consumo AS (
+                SELECT
+                    tu.username,
+                    DATE_TRUNC('month', tu.timestamp)::date as mes,
+                    m.provider,
+                    m.model_name,
+                    SUM(tu.prompt_tokens) as total_prompt_tokens,
+                    SUM(tu.completion_tokens) as total_completion_tokens,
+                    SUM(tu.total_tokens) as total_tokens,
+                    SUM(ROUND(((tu.prompt_tokens * t.precio_input_eur_millon
+                              + tu.completion_tokens * t.precio_output_eur_millon)
+                              * t.margen / 1000000)::numeric, 8))::double precision as coste_eur
+                FROM token_usage tu
+                JOIN tarifa t ON t.id = tu.tarifa_id
+                JOIN modelo m ON m.id = t.modelo_id
+                GROUP BY tu.username, DATE_TRUNC('month', tu.timestamp)::date, m.provider, m.model_name
+            ),
+            -- Cada mensaje del usuario cuenta en el modelo al que se envió. Los anteriores a guardarlo,
+            -- en el de la respuesta que los siguió; sin ninguno de los dos no se cuentan
+            enviados AS (
+                SELECT
+                    c.username,
+                    DATE_TRUNC('month', u.timestamp)::date as mes,
+                    COALESCE(u.provider, r.provider) as provider,
+                    COALESCE(u.model_name, r.model_name) as model_name,
+                    COUNT(*) as message_count
+                FROM mensaje u
+                JOIN chat c ON c.id = u.chat_id
+                LEFT JOIN LATERAL (
+                    SELECT a.provider, a.model_name
+                    FROM mensaje a
+                    WHERE a.chat_id = u.chat_id
+                      AND a.role IN ('asistente', 'ai', 'assistant')
+                      AND a.timestamp >= u.timestamp
+                    ORDER BY a.timestamp
+                    LIMIT 1
+                ) r ON u.model_name IS NULL
+                WHERE u.role IN ('usuario', 'human', 'user')
+                  AND COALESCE(u.model_name, r.model_name) IS NOT NULL
+                GROUP BY c.username, DATE_TRUNC('month', u.timestamp)::date, COALESCE(u.provider, r.provider), COALESCE(u.model_name, r.model_name)
+            )
             SELECT
-                tu.username,
-                DATE_TRUNC('month', tu.timestamp)::date as mes,
-                m.provider,
-                m.model_name,
-                SUM(tu.prompt_tokens) as total_prompt_tokens,
-                SUM(tu.completion_tokens) as total_completion_tokens,
-                SUM(tu.total_tokens) as total_tokens,
-                SUM(ROUND(((tu.prompt_tokens * t.precio_input_eur_millon
-                          + tu.completion_tokens * t.precio_output_eur_millon)
-                          * t.margen / 1000000)::numeric, 8))::double precision as coste_eur,
-                COUNT(*) as message_count
-            FROM token_usage tu
-            JOIN tarifa t ON t.id = tu.tarifa_id
-            JOIN modelo m ON m.id = t.modelo_id
-            GROUP BY tu.username, DATE_TRUNC('month', tu.timestamp), m.provider, m.model_name
-            ORDER BY mes DESC, tu.username, total_tokens DESC;
+                COALESCE(co.username, e.username) as username,
+                COALESCE(co.mes, e.mes) as mes,
+                COALESCE(co.provider, e.provider) as provider,
+                COALESCE(co.model_name, e.model_name) as model_name,
+                COALESCE(co.total_prompt_tokens, 0) as total_prompt_tokens,
+                COALESCE(co.total_completion_tokens, 0) as total_completion_tokens,
+                COALESCE(co.total_tokens, 0) as total_tokens,
+                COALESCE(co.coste_eur, 0) as coste_eur,
+                COALESCE(e.message_count, 0) as message_count
+            FROM consumo co
+            FULL JOIN enviados e
+                ON e.username = co.username AND e.mes = co.mes
+               AND e.provider = co.provider AND e.model_name = co.model_name
+            ORDER BY mes DESC, username, total_tokens DESC;
         ''').rstrip()
 
         modelo_disponible_sql = dedent('''\

{tai_sql-0.7.20 → tai_sql-0.8.0}/tai_sql/generators/python_client/__init__.py

@@ -428,9 +428,31 @@ class PythonClientGenerator(BaseGenerator):
             for m in all_models_data
         )
 
+        # Las columnas bytes viajan en base64 en JSON: su tipo en los DTOs vive en binary.py
+        has_bytes = any(
+            col.get('dto_type') == 'JsonBytes'
+            for m in all_models_data
+            for col in m.get('columns', [])
+        )
+
         # _shared/__init__.py
         init_template = self.jinja_env.get_template('shared/__init__.py.jinja2')
-        (shared_dir / '__init__.py').write_text(init_template.render(has_hierarchy=has_hierarchy, has_vector_encoders=has_vector_encoders), encoding='utf-8')
+        (shared_dir / '__init__.py').write_text(
+            init_template.render(
+                has_hierarchy=has_hierarchy,
+                has_vector_encoders=has_vector_encoders,
+                has_bytes=has_bytes,
+            ),
+            encoding='utf-8',
+        )
+
+        # _shared/binary.py — only when some column is bytes
+        binary_path = shared_dir / 'binary.py'
+        if has_bytes:
+            binary_template = self.jinja_env.get_template('shared/binary.py.jinja2')
+            binary_path.write_text(binary_template.render(), encoding='utf-8')
+        elif binary_path.exists():
+            binary_path.unlink()
 
         # _shared/context.py
         context_template = self.jinja_env.get_template('shared/context.py.jinja2')

{tai_sql-0.7.20 → tai_sql-0.8.0}/tai_sql/generators/python_client/context.py

@@ -204,6 +204,14 @@ class TemplateContextBuilder:
         constraints = self._constraints(column)
         sa_type, sa_type_args = _type_with_params(column)
 
+        # La clave autoincremental solo se filtra por lista. Igualdad no hace falta —para un
+        # registro está `find(id)`— y un rango sobre un contador que pone el motor no dice
+        # nada del dato; pero «estos ids» sí es una pregunta legítima (recorrer un grafo por
+        # niveles, traer lo que otra consulta devolvió), y sin `in_<pk>` solo se podía hacer
+        # con una consulta por id. Hasta 0.7.21 no tenía ningún filtro.
+        if constraints['autoincrement']:
+            filter_fields = ['in']
+
         context = {
             'name': column.name,
             'type': column.type,
@@ -231,6 +239,9 @@ class TemplateContextBuilder:
             # El tamaño máximo de un texto (`column(length=n)`), para quien valide antes de
             # escribir —los esquemas de formulario de tai-api—. `None` si no se declaró.
             'max_length': column.length if column.type == 'str' else None,
+            # Las agregaciones que admite: el DAO rechaza el resto con un error, y tai-api
+            # restringe con esto las columnas de cada operación en su cliente TypeScript.
+            'aggregations': _aggregations(column, descriptor),
         }
 
         if column.is_vector:
@@ -250,6 +261,15 @@ class TemplateContextBuilder:
                 'threshold': vector.threshold,
             })
 
+        # El tipo del campo en los DTOs. Es `pydantic_type` salvo en `bytes`, que en JSON
+        # viaja en base64 (`JsonBytes`, de `_shared/binary.py`): con `bytes` desnudo,
+        # pydantic lee y escribe el texto en UTF-8, así que guardaba el base64 que manda un
+        # frontend como texto y no podía devolver un binario de verdad. `pydantic_type` no
+        # cambia porque es contrato: tai-api lo lee y espera `'bytes'`.
+        context['dto_type'] = (
+            'JsonBytes' if context['pydantic_type'] == 'bytes' else context['pydantic_type']
+        )
+
         return context
 
     def calculated_column(
@@ -566,6 +586,24 @@ def _template_default(default: Any) -> Any:
     return default
 
 
+def _aggregations(column: ColumnModel, descriptor: Any) -> List[str]:
+    """
+    Las agregaciones que admite una columna: las de su tipo, menos lo que la columna misma
+    hace absurdo o peligroso. En esas tres solo queda `count`, que no mira el valor:
+
+    - **cifrada**: el motor ordenaría el texto cifrado —con un vector de inicialización
+      aleatorio, así que sin relación con el valor— y devolvería el cifrado sin descifrar.
+    - **hasheada**: `max` devolvería un hash bcrypt, que el cliente no expone en ninguna
+      lectura (tai-api lo saca de toda respuesta).
+    - **enumerado**: se guarda como texto en los cuatro motores, así que `max` sería el
+      último valor **por orden alfabético**, no el último declarado —que es lo que alguien
+      espera de un estado—. La respuesta honesta es `count` con `group_by`.
+    """
+    if column.encrypt or column.hash or column.options is not None:
+        return ['count']
+    return descriptor.aggregations() if descriptor else ['count']
+
+
 def _type_with_params(column: ColumnModel) -> tuple:
     """
     El tipo SQLAlchemy del modelo generado y sus argumentos: `('String', '(50)')`.

{tai_sql-0.7.20 → tai_sql-0.8.0}/tai_sql/generators/python_client/templates/base.py.jinja2

@@ -38,6 +38,64 @@ class TriggerAborted(ValueError):
         self.message = message
         super().__init__(f"Trigger abortado: {message}")
 
+
+class NestedWriteError(Exception):
+    """
+    Una escritura anidada del `update` no se puede aplicar al registro que se actualiza.
+
+    Un anidado nombra hijos **de ese registro**: los crea colgando de él, o los actualiza y
+    los borra por su clave. Lo que no casa con eso no se ignora —hasta 0.7.21 un hijo que
+    no se encontraba se saltaba sin error— y se lanza una de sus dos subclases. La
+    transacción se deshace entera: ni el padre ni los demás hijos quedan escritos.
+
+    - `message`: el texto para quien hizo la petición, con la solución.
+    - `field`: dónde está en el payload, con la forma del JSON (`resenas.delete.0`,
+      `libros.update.0.values.resenas.update.1`; en una uno a uno, sin índice). Lo
+      construye cada nivel al subir, así que es la ruta completa desde el registro raíz.
+    - `table`: la tabla del hijo. `key`: su clave, tal como llegó.
+    - `reason`: `'not_found'` o `'parent_mismatch'`.
+    """
+
+    #: Para reconocerla sin importar la clase, como `tai_trigger_abort`: tai-api atiende a
+    #: los clientes de varios schemas con un solo manejador, y cada uno tiene la suya.
+    tai_nested_write = True
+    reason: str = ''
+
+    def __init__(self, message: str, *, field: str, table: str, key=None):
+        self.message = message
+        self.field = field
+        self.table = table
+        self.key = key
+        super().__init__(message)
+
+    def _under(self, prefix: str) -> 'NestedWriteError':
+        """La misma excepción, vista desde el padre: antepone su tramo a `field`."""
+        self.field = f'{prefix}.{self.field}'
+        return self
+
+
+class NestedRowNotFound(NestedWriteError, LookupError):
+    """
+    Un `update` o `delete` anidado nombra una fila que no está bajo el registro que se
+    actualiza: no existe, cuelga de otro padre o la regla de RLS no la alcanza.
+
+    Los tres casos son el mismo a propósito —para quien llama, esa fila no es hija de este
+    registro— y distinguirlos delataría filas que la regla oculta. Es lo que tai-api
+    responde con un 404.
+    """
+
+    reason = 'not_found'
+
+
+class NestedParentMismatch(NestedWriteError, ValueError):
+    """
+    Un `update` anidado cambia las columnas que unen el hijo con su padre: lo sacaría del
+    registro bajo el que se ha nombrado. Para mover una fila de padre se usa el DAO de su
+    tabla. Es una petición inválida (un 422 en tai-api), no una fila que falte.
+    """
+
+    reason = 'parent_mismatch'
+
 {% if has_encrypted_columns %}
 
 # Configuración de encriptación

{tai_sql-0.7.20 → tai_sql-0.8.0}/tai_sql/generators/python_client/templates/domain/dao.py.jinja2

@@ -59,7 +59,10 @@ from {{ import_prefix }}_shared import (
     RLS,
     _log_tx,
     _log_commit,
-    OPERATION_TYPE_VALIDATORS,
+    AGG_OPERATIONS,
+    agg_field_error,
+    agg_expression_error,
+    agg_value,
     OPERATION_FUNCTIONS,
     GROUP_BY_FORBIDDEN_TYPES,
     GROUP_BY_DATETIME_TYPES,
@@ -91,6 +94,17 @@ from {{ import_prefix }}_base import verify_hash, HASH_DE_RELLENO
 {% if model.triggers is defined and (model.triggers['create'] or model.triggers['update'] or model.triggers['delete']) %}
 from {{ import_prefix }}_base import TriggerAborted
 {% endif %}
+{# Las escrituras anidadas del `update`: se acotan al padre y lo que no casa se lanza. #}
+{% set _dao_nested = [] %}
+{% for relation in model.relations | default([]) if relation.supports_nested_write and not model.is_view %}
+{% if models | selectattr('name', 'equalto', relation.target) | first %}
+{% set _ = _dao_nested.append(relation.name) %}
+{% endif %}
+{% endfor %}
+{% if _dao_nested %}
+from {{ import_prefix }}_base import NestedWriteError, NestedRowNotFound, NestedParentMismatch
+from {{ import_prefix }}_shared import scope_to_parent
+{% endif %}
 {# ── Collect cross-DAO targets (relations + trigger cross-table ops) ── #}
 {% set _cross_dao_targets = [] %}
 {% for rel in model.relations | default([]) %}
@@ -140,6 +154,41 @@ def _para_log(valores: dict) -> dict:
     """
     return {clave: ('***' if clave in _COLUMNAS_PROTEGIDAS else valor) for clave, valor in valores.items()}
 {% endif %}
+{% if _dao_nested %}
+
+
+def _hijo_que_no_esta(tabla: str, clave: Any, field: str) -> NestedRowNotFound:
+    """La excepción de un `update`/`delete` anidado que no alcanza ninguna fila."""
+    return NestedRowNotFound(
+        f"{tabla} {clave!r} no es hija de este {{ model.tablename }}: no existe, cuelga de "
+        "otro registro o la regla de seguridad no la alcanza. Un update o delete anidado "
+        "solo llega a los hijos del registro que se actualiza: comprueba la clave, o "
+        "escribe esa fila con el DAO de su tabla.",
+        field=field, table=tabla, key=clave,
+    )
+
+
+def _comprobar_union(valores: Any, bajo: Dict[str, Any], tabla: str, field: str) -> None:
+    """
+    Lanza si un `update` anidado cambia la unión del hijo con este registro.
+
+    Sacaría la fila de debajo del registro bajo el que se ha nombrado, que es justo lo que
+    acotar el anidado al padre impide. Reenviar el valor que ya tiene no es un cambio.
+    """
+    cambios = {
+        columna: getattr(valores, columna)
+        for columna, valor in bajo.items()
+        if columna in valores.model_fields_set and getattr(valores, columna) != valor
+    }
+    if cambios:
+        raise NestedParentMismatch(
+            f"Un update anidado no puede cambiar la unión de {tabla} con este "
+            f"{{ model.tablename }} ({cambios}): la sacaría del registro bajo el que se ha "
+            "nombrado. Quita esas columnas de los valores, o mueve la fila con el DAO de "
+            "su tabla.",
+            field=f"{field}.{next(iter(cambios))}", table=tabla, key=None,
+        )
+{% endif %}
 
 {% set vector_cols_with_encoder = model.columns | selectattr('type', 'equalto', 'vector') | selectattr('has_encoder') | list %}
 {% if vector_cols_with_encoder %}
@@ -167,6 +216,16 @@ from {{ import_prefix }}_shared.utils.encoders import {{ 'aencode_pending' if is
    cambiado es quién contesta. Antes lo decidía aquí un bucle que no miraba las
    constraints compuestas, así que `libro` y `resena` se quedaban sin `upsert()`. #}
 {% set ns = namespace(all_pk_autoincrement=(model.natural_key | default([]) | length == 0)) %}
+# Qué agregaciones admite cada columna, {columna: (tipo, operaciones)}. Sale del tipo del
+# schema: el SQLAlchemy no distingue un enumerado ni una columna cifrada de un texto. Lo
+# que no está aquí no se agrega, y pedirlo es un error con su motivo (`agg_field_error`).
+_AGG_COLUMNS = {
+{% for column in model.columns %}
+    '{{ column.name }}': ('{{ column.type }}{% if column.encrypt %}, cifrada{% elif column.hash %}, hasheada{% elif column.options is not none %}, enumerado{% endif %}', ({% for op in column.aggregations %}'{{ op }}'{% if not loop.last or loop.length == 1 %},{% endif %}{% if not loop.last %} {% endif %}{% endfor %})),
+{% endfor %}
+}
+
+
 class {{ model.name }}{{ prefix }}DAO:
     """
     DAO síncrono de acceso a datos para el modelo ``{{ model.name }}``.
@@ -229,9 +288,10 @@ class {{ model.name }}{{ prefix }}DAO:
             ``flush`` y ``_on_create_after`` después. Retorna el DTO del
             registro con los valores generados por la BD (IDs, timestamps...).
 
-        create_many(records, *operative_fields, session) → int:
+        create_many(records, *operative_fields, session) → List[Read]:
             Inserción masiva con hooks de trigger por instancia.
-            Retorna el número de registros creados.
+            Retorna los DTO de los registros creados, en el mismo orden, con
+            los valores que haya generado la BD — como ``create``.
 
         update(*pk_fields, updated_values, *operative_fields, session) → int:
             Actualiza un registro por PK ejecutando ``_on_update_before/after``.
@@ -280,13 +340,16 @@ class {{ model.name }}{{ prefix }}DAO:
             ``result.data`` → ``{"mean_<campo>": float | None}``.
 
         max(agg_fields, *filters, session) → AggregationResult:
-            Valor máximo de campos numéricos o de fecha (ISO 8601).
+            Valor máximo de campos numéricos, de fecha (ISO 8601) o de texto.
             ``result.data`` → ``{"max_<campo>": float | str | None}``.
 
         min(agg_fields, *filters, session) → AggregationResult:
-            Valor mínimo de campos numéricos o de fecha (ISO 8601).
+            Valor mínimo de campos numéricos, de fecha (ISO 8601) o de texto.
             ``result.data`` → ``{"min_<campo>": float | str | None}``.
 
+        Lo que el tipo de una columna no admite (``_AGG_COLUMNS``) es un error:
+        ``success=False``, sin consultar, y ``errors`` dice por qué.
+
         agg(request, *filters, verbose, session) → AggregationResult:
             Motor de agregaciones multi-operación. Acepta un ``AggRequest``
             con múltiples operaciones (sum, mean, max, min, count),