equiframe 0.12.4__py3-none-any.whl

equiframe/docs/lectura-conversion.md

@@ -0,0 +1,211 @@
+# Lectura de archivos y conversión de DataFrames
+
+La API `load_dataset`, incluida en el alcance estable de 0.12.0, lee un archivo local, descubre su estructura
+y crea un **DataFrame real de Pandas**. Si se selecciona Polars o DuckDB,
+convierte ese mismo DataFrame y entrega el objeto nativo correspondiente.
+Esta ruta convierte datos; no traduce un programa ni ejecuta transformaciones
+independientes en tres motores. Tampoco entrena detectores ni ejecuta R.
+
+La implementación se añadió el 26 de octubre de 2026. Su estabilización protege
+la interfaz, las conversiones admitidas y sus errores; no promete todas las
+variantes de cada formato o combinación de dependencias. La
+[compatibilidad](compatibility.md) identifica las verificaciones ejecutadas y
+sus límites, sin atribuirlas a otros artefactos.
+
+## Uso desde Python
+
+```python
+import equiframe as ef
+
+datos = ef.load_dataset("ventas.json")
+pandas_df = datos.pandas
+print(datos.info.to_dict())  # columnas, tipos observados, nulos, NaN y número de filas
+
+polars_datos = ef.convert_dataset(datos, target="polars")
+polars_df = polars_datos.frame
+
+# Las conversiones encadenadas consumen el objeto nativo actual.
+with ef.convert_dataset(polars_datos, target="duckdb") as duckdb_datos:
+    pandas_de_vuelta = ef.convert_dataset(duckdb_datos, target="pandas")
+
+# También puede seleccionarse el destino en la misma llamada.
+with ef.load_dataset("ventas.parquet", target="duckdb") as datos_sql:
+    relacion = datos_sql.frame
+    resultado = relacion.limit(10).df()
+# La relación DuckDB depende de la conexión privada, cerrada al salir del with.
+```
+
+`DatasetResult.pandas` conserva el DataFrame de origen y `frame` contiene el
+objeto del destino seleccionado: DataFrame de Pandas, DataFrame de Polars o
+DuckDBPyRelation. `close()` libera la conexión DuckDB que pertenece al resultado;
+no abre archivos DuckDB compartidos. El usuario puede trabajar con esos objetos
+mediante las APIs de sus motores. `inspect_dataset(path)` devuelve solamente
+`DatasetInfo`, pero realiza la lectura completa dentro de los límites declarados.
+
+## Identidad de la fuente y de la conversión
+
+Cada lectura utiliza una única captura de los bytes del archivo y devuelve
+`DatasetResult.provenance`, también accesible desde `info.provenance`.
+`DatasetSource` identifica URI, formato, SHA-256 y tamaño de esos bytes; conserva
+las opciones efectivas en `read_options_json`, consultables como un objeto con
+la propiedad `read_options`. Esto incluye la hoja, el delimitador o el modo de
+texto resueltos durante la lectura, no solamente las opciones iniciales.
+
+`DatasetProvenance` vincula esa fuente con `pandas_sha256`, el destino `target`
+y `target_sha256`. Las conversiones admiten las seis direcciones entre Pandas,
+Polars y DuckDB; leen el objeto nativo seleccionado, sin releer el archivo ni
+sustituirlo por una copia anterior. La conversión rechaza una modificación del
+objeto nativo o del Pandas original posterior a la captura. El esquema nativo
+de Polars o DuckDB se verifica antes de convertir a Arrow; una exportación Arrow
+coincidente no sustituye esa comprobación de tipos. La exportación del origen
+también rechaza una modificación del Pandas original. Para trabajar sobre datos modificados,
+el consumidor debe establecer una nueva entrada y su identidad, sin reutilizar
+la procedencia original como si describiera esos cambios.
+
+```python
+print(datos.provenance.source.sha256)
+print(datos.provenance.source.read_options)
+print(datos.info.to_dict(include_provenance=True))
+```
+
+`info.to_dict()` omite esa procedencia por defecto, porque su URI puede contener
+una ruta privada. `include_provenance=True` la añade explícitamente;
+`include_metadata=True` controla por separado los metadatos originales.
+Estas huellas identifican los datos y opciones observados; no autentican al
+productor del archivo ni aprueban una migración de programas.
+
+## Formatos y decisiones que puede requerir el lector
+
+| Archivo | Representación y opciones |
+|---|---|
+| JSON | Un objeto de registro o una lista de registros. Los escalares y listas de valores se conservan en una columna `value`, sin aplanar sus objetos o arrays. Los números fraccionarios se leen como `Decimal`. Para un contenedor de registros se exige `records_path`, sin expandir otras colecciones. |
+| JSONL / NDJSON | Un registro o valor por línea no vacía. Se rechazan miembros JSON duplicados, NaN e Infinity no estándar. |
+| CSV | Detecta delimitadores consistentes entre coma, punto y coma, tabulación y barra vertical. Si más de uno encaja, solicita elección. Por defecto la primera fila es el encabezado. |
+| TXT / TSV | Texto libre: una columna `text`, una fila por línea. Si también puede interpretarse como tabla, pregunta `lines` o `delimited`. Se puede fijar `delimiter`, `header` y `text_mode`. No se inventa un esquema para texto libre. |
+| Excel | `.xlsx` y `.xlsm` mediante openpyxl; `.xls` mediante xlrd. Selecciona automáticamente solo cuando hay una hoja. Con varias hojas exige `sheet`. Lee las filas/celdas observadas sin truncarlas según dimensiones declaradas por el productor. No ejecuta macros; XLSX/XLSM con fórmulas o errores exige un archivo con valores. |
+| XML | Usa defusedxml y rechaza DTD, entidades y referencias externas. Conserva atributos, campos y elementos repetidos; `records_path` permite seleccionar registros. El XML de contenido mixto que no pueda representarse fielmente se rechaza. |
+| Parquet | Conserva tipos Arrow, unidades, zonas y máscaras de ausencia al construir Pandas con ArrowDtype. |
+| GeoJSON | FeatureCollection, Feature y geometrías. Conserva `geometry` y `properties` originales; expone además `properties.nombre` y los otros miembros como `feature.nombre`. Los metadatos de la colección quedan en `info.metadata`. No requiere GIS ni cambia el sistema de coordenadas. |
+
+Ejemplos de desambiguación:
+
+```python
+opciones = ef.DatasetReadOptions(sheet="Ventas")
+datos = ef.load_dataset("libro.xlsx", options=opciones, target="polars")
+
+opciones = ef.DatasetReadOptions(records_path="/respuesta/ventas")
+datos = ef.load_dataset("respuesta.json", options=opciones)
+
+opciones = ef.DatasetReadOptions(delimiter="\t", header=False)
+datos = ef.load_dataset("mediciones.txt", options=opciones)
+```
+
+En JSON `records_path` es un JSON Pointer RFC 6901. En XML es una ruta de
+elementos de ElementTree, por ejemplo `./ventas/venta` o `.//venta`.
+No se descargan esquemas, no se ejecuta XPath arbitrario ni se evalúa código.
+
+## Tipos y preservación
+
+La inferencia textual es conservadora: enteros canónicos se convierten en
+enteros y números decimales inequívocos se convierten en `Decimal`, sin pasar
+por float. Los ceros iniciales, espacios, representaciones mezcladas y fechas
+permanecen como texto. Un campo vacío sigue siendo una cadena vacía; no se
+interpreta automáticamente como nulo ni se adivinan tokens como `NA`.
+Los números ya almacenados por Excel tienen la precisión que conserva el
+libro; no se recuperan dígitos perdidos antes de llegar a EquiFrame. Los formatos
+Excel de enteros con ceros de relleno, como `000000`, se conservan como texto y
+se informa esa decisión. Las fechas tipadas de Excel conservan su tipo.
+XLS expone valores almacenados o cacheados; su lector no identifica
+independientemente todas las fórmulas del archivo heredado.
+
+`DatasetInfo.notes` informa las inferencias. Para conservar todo texto o
+declarar unas pocas columnas:
+
+```python
+opciones = ef.DatasetReadOptions(
+    infer_text_types=False,
+    column_types={"importe": "decimal", "cantidad": "integer", "codigo": "string"},
+)
+datos = ef.load_dataset("ventas.csv", options=opciones)
+```
+
+Tipos explícitos admitidos: `string`, `integer`, `decimal`, `boolean` y `json`.
+`json` conserva un objeto o array como texto JSON sin convertir sus Decimal a
+float. Es una representación explícita útil para geometrías heterogéneas o
+propiedades anidadas que no admitan una única estructura Arrow:
+
+```python
+opciones = ef.DatasetReadOptions(column_types={"geometry": "json", "properties": "json"})
+datos = ef.load_dataset("mapa.geojson", options=opciones, target="polars")
+```
+
+No se cambia automáticamente a texto cuando un motor no admite un tipo.
+La ruta de conversión comprueba la representación Arrow inicial y recorre por
+completo el resultado nativo para rechazar cambios de contenido, nulos/NaN,
+orden, precisión, escala o zona temporal. Permite cambios de transporte como
+`string` a `large_string` que conservan los valores. Un tipo incompatible genera
+`CapabilityError`; el resultado no se declara equivalente ni se normaliza.
+
+Los campos JSON ausentes se materializan como nulos en las columnas unificadas;
+sus posiciones originales quedan en `info.metadata["absent_json_members_by_row"]`.
+`info.to_dict()` omite metadatos originales por defecto; use
+`info.to_dict(include_metadata=True)` cuando quiera incluirlos explícitamente.
+Los metadatos de una colección GeoJSON pueden contener información del usuario.
+
+## Un comando para leer y elegir destino
+
+```console
+equiframe dataset load ventas.json
+```
+
+La misma invocación muestra la estructura, pregunta las ambigüedades del archivo
+y pregunta: «¿A qué motor quiere migrar desde Pandas? pandas / polars / duckdb».
+Para scripts y entradas no interactivas se pasa el destino:
+
+```console
+equiframe dataset load ventas.json --target polars
+equiframe dataset load libro.xlsx --sheet Ventas --target duckdb
+equiframe dataset load ventas.csv --target polars --output copia.parquet
+equiframe dataset inspect mapa.geojson
+```
+
+Opciones de lectura: `--format`, `--sheet`, `--records-path`, `--delimiter`
+(`tab` significa tabulación), `--header/--no-header`, `--text-mode`,
+`--infer-types/--keep-text`, `--encoding`, `--max-bytes` y `--max-rows`.
+Sin `--output`, el objeto convertido existe durante el comando; en Python
+la API devuelve el objeto para continuar trabajando. `--output` y
+`DatasetResult.to_parquet()` exportan el **Pandas original cargado** a un Parquet
+nuevo; no exportan transformaciones que el usuario aplique después a `frame`.
+La exportación escribe y sincroniza primero un temporal hermano, y publica
+exclusivamente el archivo completo mediante un enlace duro en el mismo sistema
+de archivos. El destino no se sobrescribe. Si el sistema no admite esa operación,
+la exportación falla; no usa una copia parcial como alternativa. El temporal
+propio se retira al terminar. No se promete durabilidad ante corte de energía.
+Un error posterior a la publicación puede dejar el Parquet completo visible;
+inspeccione y compruebe su contenido antes de decidir una recuperación, sin
+suponer que cualquier archivo existente pertenece al intento fallido.
+La conversión no equivale a una comparación
+semántica de dos implementaciones; para esa tarea siguen disponibles `diff`
+y los contratos de equivalencia.
+
+Los fallos CLI conservan el código estable en la primera línea de stderr y la
+guía fija `hint[...]` después. Un `DatasetChoiceRequired` puede añadir entonces
+un objeto JSON con `required_option` y `choices` para resolver una ambigüedad.
+Un error de lectura/configuración termina con código 2; dependencias no
+disponibles y fallos técnicos terminan con código 3. El código 0 sólo indica que
+se completó la lectura y conversión solicitadas, sin aprobar equivalencia.
+
+## Dependencias y límites
+
+El extra `files` añade Pandas, Arrow, openpyxl, xlrd y defusedxml. Polars y DuckDB
+se seleccionan mediante sus extras existentes. Los lectores y motores se importan
+solo al usarlos; un extra faltante produce `MissingDependencyError` con la
+dependencia necesaria. No hay instalaciones automáticas.
+
+Por defecto se admiten hasta 128 MiB de archivo, un millón de filas y dos
+millones de celdas. Son límites de admisión; no son cuotas duras de RAM ni de
+descompresión. La lectura es local y completa, no distribuida ni en streaming.
+Las rutas locales pueden seguir enlaces simbólicos; el llamante debe elegir
+archivos y directorios de confianza. Se rechazan nombres de columnas duplicados,
+filas CSV irregulares y conversiones sin representación fiel. No se infieren
+claves de negocio, monedas, fechas, CRS ni reglas de aceptación del proyecto.

equiframe/docs/licensing.md

@@ -0,0 +1,17 @@
+# License
+
+The owner selected MIT on 2026-10-27 for the original EquiFrame and EquiFrame
+Benchmark code and accompanying project documentation, examples and tools.
+Copyright (c) 2026 Hernán Troya. Each distribution carries the full LICENSE.
+
+MIT permits use, modification, commercial use and redistribution under its
+terms, including preservation of the copyright and permission notice. The
+software is provided without warranty as stated in the license.
+
+Third-party material keeps its existing license. Both core distributions
+include unmodified CycloneDX schemas under Apache-2.0; their upstream license,
+provenance and notices are preserved. See THIRD_PARTY_NOTICES.md in the package.
+
+This decision does not relicense downloaded datasets, the thesis manuscript,
+external dependencies or separately owned components. Publication remains a
+separate owner-authorized task.

equiframe/docs/maintenance.md

@@ -0,0 +1,233 @@
+# Maintenance, support and trust incidents
+
+[Handbook](index.md) · [Adoption](adoption.md) · [Compatibility](compatibility.md) ·
+[Upgrading](upgrading.md) · [Security](security.md) · [Release/rollback](releasing.md)
+
+## Maintainer and best-effort support
+
+The project owner has assigned **Hernán Troya (`htroya`)**
+responsibility for maintenance, releases and security coordination. This is
+best-effort maintenance by one owner, not a staffed service or support contract.
+No backup, on-call coverage, numeric response deadline or SLA is promised.
+
+| Role | Scope | Named owner | Backup |
+|---|---|---|---|
+| Core | Comparison/contracts, typed states, assertions, evidence integrity and historical readers | Hernán Troya (`htroya`) | Not designated |
+| Adapters | Native capture/execution, capabilities, dependencies and measured matrix cells | Hernán Troya (`htroya`) | Not designated |
+| Documentation | Installation, diagnosis, migration guidance and reproducible examples | Hernán Troya (`htroya`) | Not designated |
+| Releases | Exact-byte checks, manual publication/withdrawal and recovery | Hernán Troya (`htroya`) | Not designated |
+| Security | Private intake, exposure review and vulnerability coordination | Hernán Troya (`htroya`) | Not designated |
+
+The core remains independent of a service, domain schema and infrastructure.
+Service/DW ownership, concurrency, authorization and aggregate quotas stay with
+those components' owners; an adapter issue does not authorize redesigning them.
+Keep experimental benchmark/scientific acceptance distinct from operational
+comparison maintenance.
+
+## Report a problem
+
+Use [the public issue channel](https://github.com/htroya/equiframe/issues)
+for nonsensitive bugs and minimal synthetic reproductions. Use
+[private vulnerability reporting](https://github.com/htroya/equiframe/security/advisories/new)
+for sensitive security reports. Both routes belong to the project's single
+public repository. For each release, the maintainer must enable both routes
+and verify their availability. If private intake cannot be verified, retain
+sensitive details locally until confidential intake can be arranged; do not
+move them to a public issue.
+
+Do not put credentials, real data, personal information or sensitive exploit
+details in a public issue, an ordinary issue with a broader audience, or a
+guessed email address. A repository issue is not automatically a private
+security channel. If a safe route cannot be verified, retain sensitive details
+locally and stop using the affected acceptance path.
+
+Provide only the minimal permitted reproduction:
+
+1. Classify installation, comprehension, semantics, integration, performance
+   and/or evidence; state impact and whether false `equivalent` is suspected
+2. Identify exact package/commit, wheel/sdist and dependency-lock hashes, Python,
+   OS/architecture, engine versions and selected extras. Redact account/path data
+3. Give a small synthetic fixture and trusted code/SQL that someone can inspect
+   before executing. Include the contract, relevant policy, budgets and explicit
+   reproduction commands; do not upload a complete private run or environment
+4. State independently expected versus observed state, completeness, acceptance
+   and exit code. Explain the expected-output provenance. Separate engine
+   agreement from correctness and report integrity from semantic acceptance
+5. Attach only a reviewed minimized report when permitted, with its inventory
+   verification outcome and hash. Mark missing/partial evidence explicitly
+6. Identify the last known-good **artifact**, if known, repeatability and any safe
+   workaround. Preserve earlier failures; do not silently replace the baseline
+
+The [adoption guide](adoption.md) describes consent and minimal observation.
+Permission to participate does not authorize sharing the person's data or posting
+to an issue. Do not request additional private data until its necessity, recipient
+and handling have been agreed. Raw exception causes can reveal more than the
+ordinary report; inspect diagnostics before sending them.
+
+## Triage priorities without response deadlines
+
+The maintainer uses the following best-effort triage order. It does not establish
+staffed coverage, response deadlines or a service guarantee.
+
+| Priority | Examples | Triage goal |
+|---|---|---|
+| P0: critical trust incident | Suspected false `equivalent`, acceptance of incomplete/invalid evidence, or material disclosure/integrity risk | Stop relying on the affected claim, preserve evidence and seek owner-led containment/escalation before restoring acceptance |
+| P1: blocking defect | Reproducible installation/integration failure, documented supported case incorrectly rejected, or an unusable evidence reader | Establish scope and a safe workaround, then reproduce and verify a focused correction |
+| P2: nonblocking friction | Comprehension gaps, minor diagnosis problems, performance outside an unpromised target | Preserve observations, assess impact and prioritize repeated real pain without weakening semantics |
+| P3: capability proposal | New engine, integration or unsupported representation | Require repeated real need, ownership, corpus, budget and an explicit support decision before implementation commitment |
+
+Category and severity are separate. A semantics report is not automatically a
+confirmed defect; an evidence issue may be critical. Safe `not_evaluable` is
+not false equivalence. If the owner is unavailable, leave the issue pending;
+there is no designated backup or automatic escalation promise. Do not promise a
+reply or reopen a potentially unsafe path merely because time has passed.
+
+## Reproduce, correct and reconfirm
+
+Use a local incident/issue record with source evidence, scope, category, proposed
+priority, triage decision, assigned owner when accepted, correction and validation
+references. Keep review, release approval and consumer confirmation separately
+pending. A suggested workflow is: reported, scoped, reproduced or needs evidence,
+correction under review, technically verified, awaiting consumer reconfirmation,
+then resolved. Unsupported, duplicate or withdrawn reports need an explicit
+rationale; do not erase the original observation.
+
+For a reproducible defect:
+
+1. Preserve the failing artifact, permitted evidence and independent expectation.
+   Reduce a copy to a minimal synthetic case while retaining the same failure
+2. Add a regression that fails against the affected version for the stated reason.
+   Include relevant equivalent, different, invalid and incomplete cases; tests
+   derived only from the implementation can confirm the same error
+3. Make a narrow correction with review of API/format/adapter/contract impacts.
+   Do not rename a stable surface experimental to evade compatibility duties
+4. Run affected semantic and historical-reader tests, full candidate checks,
+   outside-checkout installed recipes and affected compatibility matrix cells
+   against new immutable bytes. Record failed, blocked and unexecuted checks
+5. Document scope, behavior changes, migration, exact hashes and residual limits.
+   Follow [release approval](releasing.md); technical verification does not
+   authorize distribution, a public issue, dependency access or a remote CI run
+6. Through the authorized channel, ask the affected consumer to test the original
+   use case and the relevant later real change with the identified correction.
+   Record whether the integration is retained and reporting/updating is understood
+7. Mark consumer reconfirmation only after their actual response and evidence.
+   If they cannot repeat it, keep that gap open rather than treating internal tests
+   as their approval. Reopen the issue if their case still fails
+
+Track actual triage/reproduction/review/documentation effort and unresolved work.
+Sustainable support needs observed capacity and accepted owners, not estimates
+presented as delivered service.
+
+## False `equivalent`: critical trust incident procedure
+
+A plausible false-equivalence report triggers precautionary containment while
+validation proceeds. This means the evaluated contract admitted a difference or
+invalid/incomplete evaluation as acceptance; a deliberate permissive contract or
+two engines sharing the same bug needs separate diagnosis. Do not dismiss the
+report merely because existing tests pass or a manifest has valid hashes.
+
+1. **Contain.** Stop using the suspect result/path as an acceptance gate. Preserve
+   original artifacts and private evidence; suspend distribution/recommendation
+   of affected candidate hashes within the authorized scope. Do not silently
+   weaken a contract, remove the check or convert `not_evaluable` to success
+2. **Escalate safely.** Seek an accepted incident owner and relevant core/adapter,
+   release and security reviewers through verified routes. Keep sensitive details
+   restricted. No staffed response or automatic external notification is implied
+3. **Bound impact.** Identify affected package commits and wheel hashes, exact
+   dependency versions, APIs, adapter stages, data types, contract revisions and
+   policies, output/evidence formats and environments. Distinguish confirmed,
+   possibly affected and untested scopes; inventory downstream decisions that
+   relied on the suspect result without uploading their raw data
+4. **Reproduce independently.** Build the smallest permitted case with an expected
+   result reviewed independently of the failing path. Compare the identified
+   previous and current artifacts; keep counterexamples and original decisions
+5. **Correct and verify.** Add the failing regression, repair the narrow cause and
+   exercise adjacent policies, all affected native adapters, interruption/limits,
+   invalid expected inputs and persisted readers. Re-run full affected source,
+   distribution and compatibility gates. A fail-closed fix may reject formerly
+   accepted input immediately; explain that boundary explicitly
+6. **Prepare safe recovery.** Supply a new approved artifact with exact pins,
+   change notes and validation evidence. Test upgrade in an isolated environment
+   and re-evaluate affected consumer cases. Roll back only to a demonstrated
+   known-safe artifact/environment; if none exists, suspend acceptance. Never
+   rewrite historic evidence or downgrade format markers to force readability
+7. **Notify with approval.** The owner approves the recipient scope, channel and
+   consequential content before an affected-user notice is sent. Explain affected
+   and uncertain versions/contracts/adapters, impact, containment, safe upgrade
+   or rollback and cases requiring re-evaluation. Reach only authorized recipients
+   through verified channels and share no other consumer's private data. Record
+   actual dispatch/acknowledgment separately from a prepared draft
+8. **Reconfirm and close.** Obtain affected-consumer confirmation on their original
+   and later-change cases, record any downstream corrective decision, and document
+   residual exposure. Keep unreached consumers and unverified environments open.
+   Owner review closes containment only with evidence; a green internal suite
+   alone does not close the trust incident
+
+For a future public release, advisory and index actions require the owner's
+separate approval. A yank does not remove installed or exactly pinned copies.
+Published artifacts must not be overwritten. Before a first registry publication
+there is no public release to withdraw; afterwards use the same identified-byte
+withdrawal/recovery process in [releasing](releasing.md).
+
+## Upgrade, dependency and support decisions
+
+Preserve package version, contract revision and evidence format as separate
+identities. Follow the [compatibility policy](compatibility.md), including its
+deprecation window and fail-closed exception, and [upgrade checks](upgrading.md).
+New evidence must not change the meaning of historical records. Unknown formats
+remain rejected; migration needs explicit review and new traceable artifacts.
+
+Support claims must cite exact measured cells. The current maturity plan requires
+Python 3.10/3.11/3.12/3.13 with per-interpreter first-use closures and explicit
+platform receipts. Do not expand support from metadata, configured but unexecuted CI, or past results
+for different candidate hashes. Dependency changes require fresh affected-cell
+validation and updated artifact-bound inventories; timestamps and old advisory
+receipts cannot certify changed dependencies.
+
+The retained STEP9 minimum-profile advisory match for **CVE-2026-25087** remains
+visible. The recorded advisory states the affected Arrow C++ functionality is
+not exposed through Python bindings, which are excluded from vulnerability;
+this does not turn the retained package-version match into a clean scan, prove
+all native dependencies safe or complete the source-security assessment.
+That historical result does not substitute for triage of the dependencies in a
+new release. See [dependency evidence](dependencies.md) and current release gates.
+
+The earlier stopped source-security assessment remains historical and is not
+relabeled as a pass. The owner has now authorized stable-release preparation and
+manual TestPyPI/PyPI publication subject to current security and release gates.
+MIT licensing and the maintainer role are owner decisions. The reporting routes
+must be enabled and their availability verified for each release. Registry
+ownership, final artifact checks and publication remain separate observable
+steps. Do not claim that authorization fixes a vulnerability or completes a
+security assessment. Scientific acceptance and human adoption are independent
+of interface stability and registry publication.
+
+## Admitting a new engine or integration
+
+Do not expand the adapter catalog because a feature is popular or a synthetic
+demo passed. Before accepting an implementation commitment, require:
+
+- Repeated, documented blockers in independent real uses and why existing
+  supported routes cannot meet the need without semantic loss
+- A named willing maintainer with boundaries agreed by component owners; any
+  backup or staffed coverage must be explicit rather than assumed
+- A permitted representative corpus with independent expectations, positive,
+  negative, unsupported, invalid and incomplete cases, including key/multiplicity,
+  NULL/NaN, Decimal and time boundaries relevant to the integration
+- An explicit resource and maintenance budget covering native dependencies,
+  CI/platform cells, performance, evidence readers, security and upgrade costs
+- An owner-approved support decision: supported subset, version/platform matrix,
+  stability, failure/abstention rules, migration/deprecation and exit criteria
+
+Record the decision and its evidence before adding an engine. Preserve genuine
+native execution and explicit registration; do not simulate a new engine by
+converting another engine's already-computed output. Missing demand, ownership,
+corpus, budget or support approval leaves the proposal pending.
+
+## Python 3.10 runtime policy
+
+The supported compatibility range includes Python 3.10 through 3.13, with the
+measured scope in [compatibility](compatibility.md). Application deployment
+owners remain responsible for the interpreter's lifecycle, dependency risks and
+their upgrade path. Passing package tests does not provide upstream/vendor
+security maintenance, a backup maintainer or a response deadline.