equiframe 0.12.4__py3-none-any.whl

equiframe/docs/arquitecto.md

@@ -0,0 +1,143 @@
+# Recorrido del arquitecto de datos
+
+[Inicio](inicio.md) · [Instalación](installed-private.md) · [Científico](cientifico.md) · [API](api.md)
+
+## Qué resuelve y qué instalar
+
+Compara la salida de tu código Python o una consulta SQL con un esperado revisado,
+guarda el diagnóstico y detén la tarea si difiere o no puede evaluarse. El
+orquestador actual conserva transporte, secretos, reintentos y cuotas. No hace
+falta desplegar otro servicio, usar el benchmark o conocer todos los modelos.
+
+Instala un wheel identificado con `[duckdb]` para este ejemplo; usa
+`[engines]` para las seis direcciones. Los consumidores anteriores conservan
+su pin de candidato y sus propios recibos. Sigue la receta
+normal de pip y el ensayo separado con lock completo de [installed-private](installed-private.md).
+El candidato vigente declara Python 3.10–3.13. Usa el recibo real de tu minor y
+plataforma; el objetivo ARM64 no se acredita con un ensayo Linux x86_64.
+No uses el antiguo wheel 0.11.1 de la receta histórica ni un homónimo público.
+
+Para empezar sin copiar el script, sigue [primer uso por perfil](first-use.md):
+`python -I -m equiframe doctor --extra duckdb` y
+`python -I -m equiframe demo --role architect --output sql-good`.
+La guía completa siguiente sirve para integrar tu propio código y pytest.
+
+## Python y SQL: evidencia antes de rechazar
+
+Guarda lo siguiente como `integracion.py` fuera del checkout. Los datos son
+sintéticos: la consulta buena tiene A=10, B=20; la variante cambia B a 21.
+El esperado es literal y no lo calcula DuckDB. La suma por sí sola no es el gate.
+
+```python
+import argparse
+from pathlib import Path
+
+import equiframe as ef
+import pyarrow as pa
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--output", type=Path, required=True)
+parser.add_argument("--case", choices=("good", "different"), default="good")
+args = parser.parse_args()
+args.output.mkdir(parents=True, exist_ok=False)
+expected = pa.table({"id": ["A", "B"], "quantity": [10, 20]})
+# SQL del propio consumidor, fijo y confiable; valores enlazados, no interpolados.
+snapshot = ef.capture_duckdb(
+    "SELECT 'A' AS id, 10::BIGINT AS quantity UNION ALL SELECT 'B', $quantity::BIGINT",
+    parameters={"quantity": 20 if args.case == "good" else 21},
+    work_dir=args.output / "capture",
+)
+declaration = ef.infer_diff_contract(expected.schema, keys=["id"])
+result = ef.diff(
+    snapshot,
+    ef.ArrowInput(expected),
+    contract=declaration,
+    work_dir=args.output / "private",
+)
+report = ef.write_comparison_report(result, args.output / "report")
+print(report.to_text())
+# Solo este fixture sintético autoriza mostrar nombres, clave y valores.
+detail = ef.write_comparison_report(
+    result,
+    args.output / "synthetic-detail",
+    options=ef.ReportOptions(include_values=True, include_metadata=True),
+)
+print(detail.to_text())
+# No capturar esta excepción para continuar una publicación o hacer verde el CI.
+ef.assert_equivalent(result, report_path=args.output / "report" / "report.html")
+```
+
+Ejecuta `python -I integracion.py --output sql-good` y luego
+`python -I -O integracion.py --case different --output sql-different`.
+La primera termina con 0; la segunda con una excepción `EquivalenceDifferentError`
+y salida no cero, después de guardar ambos reportes. Conserva el retorno real.
+La conexión propia ya está cerrada cuando se compara su snapshot desacoplado.
+Un reporte no tiene `assert_equivalent()` ni `summary()`; usa las funciones de la
+[API](api.md). `ComparisonReport.to_text()`, `.to_html()` y `._repr_html_()` sí
+existen; el objeto ComparisonResult se acepta con `ef.assert_equivalent`.
+
+Para CI local, conserva el script junto con este test `test_integracion.py`:
+
+```python
+from pathlib import Path
+import subprocess
+import sys
+
+
+def test_sql_regression(tmp_path):
+    script = Path(__file__).with_name("integracion.py")
+    subprocess.run(
+        [sys.executable, "-I", str(script), "--output", str(tmp_path / "sql")],
+        check=True,
+    )
+```
+
+`python -m pytest -q test_integracion.py` comprueba la ruta de integración actual.
+Para un proyecto real sustituye la consulta/esperado por versiones autorizadas;
+una regresión real debe hacer fallar el test. Este comando es una prueba local,
+no un job remoto de GitHub Actions. No modifiques el esperado para aprobar el fallo.
+
+## Fijar datos externos y migrar
+
+- Ya tienes DataFrames eager/Arrow: `diff`; inspecciona el contrato inferido y
+  declara unidades, nulabilidad, claves y tolerancias justificadas del dominio
+- Ya tienes artefactos: `compare` con contrato y `reference="expected"`
+- Necesitas SQL confiable: `capture_duckdb`; no acepta cualquier statement ni
+  acredita consistencia entre sistemas diferentes
+- Necesitas un snapshot externo fijo: [G](journeys.md#g-external-snapshot-integration)
+  usa `SnapshotDataSource` y cliente inyectado; [SQLite](sqlite-snapshots.md)
+  añade un productor DB-API transaccional. El transporte/permiso/retención sigue
+  en el consumidor. El mock no acredita el servicio de José
+- Necesitas comparar migración: `check_migration` antes de `migrate`; consulta
+  [IR](migration-ir.md) por motor. Los seis pares ordenados se conservan en el
+  consumidor existente. No traduce Python/SQL arbitrarios ni convierte una
+  única salida para aparentar dos ejecuciones nativas
+- Necesitas cargar localmente: [C](journeys.md#c-retail-csvjson-etl-and-local-parquet)
+  muestra esquema, quarantine y checkpoints. En producción, una exclusión
+  necesita autorización de dominio; el ejemplo no la concede
+
+El consumidor independiente 0.1.9, distribuido aparte con sus datos permitidos,
+provee los programas `reconciliation`, `refactor`, `migration`, `preparation`.
+Su README contiene instalación y CLI exactos. `run --all` verifica 72 casos:
+24 aceptaciones y 48 rechazos esperados si todo coincide. El cero del arnés
+no acepta los casos defectuosos. Los recibos distinguen cada artefacto y repetición.
+
+## Repetición, publicación y recuperación
+
+Una repetición usa nueva carpeta de evidencia; nunca sobreescribe la entrada.
+El destino Parquet local de un solo escritor publica una versión y puntero
+atómico. Misma petición admitida puede ser idempotente; no es una transacción
+remota, concurrencia del DW ni garantía de durabilidad frente a corte eléctrico.
+
+Antes del commit, un fallo de validación/escritura conserva la versión anterior.
+Después de cambiar el puntero, un fallo de escritura del recibo puede dejar los
+datos publicados y la aplicación incompleta: consulta el puntero/recibos,
+conserva el fallo y reconcilia el estado antes de reintentar. No declares rollback
+ni éxito por no haber llegado un recibo. El consumidor 0.1.10 documenta y conserva
+`committed_application_incomplete` cuando puede escribir ese diagnóstico.
+
+El diagnóstico minimizado no borra los datos de `private/`, capturas ni bundles.
+Comparte únicamente vistas revisadas y autorizadas. Para incidencias, aporta
+versión/hashes/lock, entorno, caso sintético, contrato, esperado y observado;
+[maintenance](maintenance.md) distingue las incidencias públicas de los reportes
+privados de seguridad y confirma al mantenedor responsable. No se promete SLA.

equiframe/docs/choosing-api.md

@@ -0,0 +1,84 @@
+# Choose the smallest existing API
+
+[Handbook](index.md) · [Inicio en español](inicio.md) · [API reference](api.md) ·
+[Eight runnable journeys](journeys.md)
+
+The compatibility facade retains its public models and entry points; the current
+name inventory is `ef.__all__`. Most comparison applications start with `diff`,
+`assert_equivalent` and `comparison_report`; none require
+adopting a new framework. Models, extension ports and advanced services stay
+available under their current imports. No facade names are hidden, renamed or
+deprecated by this navigation guide.
+
+## Start with the object you already have
+
+| You have | Use | Inspect or accept |
+|---|---|---|
+| A local JSON, Excel, TXT, XML, CSV, Parquet or GeoJSON file | `load_dataset`, optionally `inspect_dataset` | Original Pandas frame, structure, inferred types and explicit read choices; no semantic approval |
+| A `DatasetResult` currently holding Pandas, Polars or DuckDB data | `convert_dataset(..., target=...)` | Select any of those three destinations, consume the current native frame and preserve the captured source identity; no translated program |
+| Two eager pandas/Polars DataFrames or Arrow tables | `diff` | `read_diff_contract`, then `assert_equivalent` |
+| An explicitly supplied `DuckDBPyRelation` and another admitted native input | `diff` | Authorize bounded consumption of that relation; the caller owns its connection and native plan |
+| Materialized Arrow/Parquet or captured `TableArtifact` | `compare` with explicit `Contract` | `comparison_report`, then `assert_equivalent` |
+| A trusted DuckDB SELECT/WITH and exclusive connection ownership | `capture_duckdb`, then `compare` | Detached capture and explicit contract |
+| A trusted native callback/SQL implementation | `execute` with registry/source | Execution only; compare or Verify separately |
+| A supported relational IR for two engines | `check_migration`, then `migrate` | Separate `.state`, `.verification` and `.complete` |
+| Outputs plus a reviewed expected and provenance | `verify` | Technical agreement, expected, rules and review dimensions |
+| Two admitted eager outputs or explicitly supplied DuckDB relations, with an explicit contract | `review_with_r` | Independent base-R comparison of the captured data; relation submission authorizes bounded native-plan consumption; inspect `.state` and `.complete` |
+| Rules/Isolation Forest decisions and the same observed outputs | `finalize_with_r` | Preserve alerts and comparator disagreement; inspect `.accepted` and component availability |
+| A captured execution, its rules/profile, one-profile IF detection and a comparison including that output | `finalize_execution_with_r` | Verify identities/artifacts and inspect `.execution_binding`, `.accepted` and component availability |
+| CSV/JSON/JSONL with declared source/schema rules | `ingest_file` | Accepted/quarantined records and source/conversion receipts |
+| Several bounded migration checkpoints | `run_workflow` | Stage statuses, failure isolation and expected checks |
+| A pinned external data-client snapshot | `SnapshotDataSource` | Manifest/bytes/schema validation; client owns transport |
+| Finalized migration/Verify/workflow evidence | `export_bundle`, `import_bundle` | Closed-inventory integrity; no ETL reexecution |
+
+`diff` compares captured outputs. Supplying an actual `DuckDBPyRelation`
+explicitly authorizes bounded consumption of its native plan; SQL strings,
+connections, consumable readers and Polars lazy frames are not inferred as data.
+`compare` does not infer an arbitrary file's semantics. Native migration is not arbitrary Python
+translation. Prefer the original engine/orchestrator when it already performs the
+work, then compare its materialized result. [API](api.md) is the authoritative
+signature reference; use `inspect.signature(ef.diff)` in the installed interpreter.
+
+For file loading, [the file guide](lectura-conversion.md) explains conservative
+inference, Excel sheets, nested records, text choices, optional dependencies and
+DuckDB resource ownership. The [R review guide](r_review.md) lists its exact
+admitted policies, input associations and explicit unavailable states. The R
+language is separate from the letter R used for operational rules.
+
+## Four dimensions that must stay separate
+
+1. **Execution:** `completed` says registered code finished and was captured
+2. **Agreement:** `equivalent` says outputs satisfy the evaluated contract
+3. **Expected result:** `correct`/`divergent` concerns a declared reference whose
+   business correctness and independence still need justification
+4. **Evaluability:** every required incomplete/unavailable component stays visible
+
+Do not use a report, successful process exit from an integrity reader, empty
+findings, `bool(result)` or engine agreement as a replacement for the intended
+acceptance gate. Anomalies R/M/B/H and independent verification O remain separate.
+Pandas is never an oracle by virtue of being the first engine.
+
+## Integrate into an existing orchestrator
+
+Call the Python API from a task that owns a new private output directory, then
+persist its result location and apply the explicit gate before its downstream
+publication step. Bind supplied files/snapshots to fixed identities. A retry gets
+a new run directory; it must not overwrite evidence or silently rerun a callback
+with external effects. Let the orchestrator own its process quotas, timeout,
+secrets, concurrency and retry policy. EquiFrame's budgets are cooperative.
+
+For a command task, preserve the CLI command's meaning. Comparison/run commands
+separate 0 accepted/completed scope, 1 differences/alerts, 2 input/preflight errors,
+and 3 failed/partial/unavailable evaluation as documented for that command.
+Integrity readers can return zero for valid evidence describing a failed run;
+apply the stored semantic gate separately. [API CLI reference](api.md) and
+[fast CI](fast-ci.md) show the boundary without requiring a deployed service.
+
+## Discover advanced types without importing engines
+
+`ef.get_stability_register()` classifies every public name and supported surface;
+`ef.get_adapter_capabilities()` separates capture, comparison, native execution
+and migration. These descriptions are not admission checks or platform test
+results. `Model.model_fields` and `Model.model_json_schema()` support typed editing
+and inspection. Use the [tested compatibility scope](compatibility.md) and each
+actual preflight/result, rather than treating export count as capability count.

equiframe/docs/cientifico.md

@@ -0,0 +1,180 @@
+# Recorrido del científico de datos
+
+[Inicio](inicio.md) · [Instalación](installed-private.md) · [Arquitecto](arquitecto.md) · [Semántica](semantics.md)
+
+## Qué comprobar antes de usar un dataset preparado
+
+Una optimización no debe cambiar IDs, cobertura, ausencias, precisión o fechas
+sin un requisito explícito. Compara la preparación candidata con valores
+esperados independientes; guarda diferencias y rechaza los casos no evaluables.
+Equivalencia no demuestra ausencia de sesgo, calidad del modelo o validez científica.
+
+Este script necesita un wheel identificado con el extra `[arrow]`.
+La [instalación vigente](installed-private.md) usa resolución normal y `pip check`;
+no requiere pandas, ML, benchmark ni otro orquestador. Las rutas A–H y el
+consumidores identificados por sus propios pins y recibos amplían el ejercicio
+a motores nativos y datos permitidos.
+
+Puedes empezar sin copiar código: [primer uso por perfil](first-use.md) explica
+`python -I -m equiframe doctor --extra arrow` y
+`python -I -m equiframe demo --role scientist --output prep-good`.
+El script siguiente permite integrar y modificar una preparación propia.
+
+## Preparación pequeña, precisa e inspeccionable
+
+Guarda como `preparacion.py` fuera del checkout. El origen sintético conserva
+IDs textuales, milisegundos decimales y fechas UTC; la transformación expresa
+segundos exactos. El esperado usa literales Decimal e instantes enteros,
+independientes del cálculo y parser de la preparación.
+
+```python
+import argparse
+from datetime import datetime, timedelta
+from decimal import Decimal
+from pathlib import Path
+
+import equiframe as ef
+import pyarrow as pa
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--output", type=Path, required=True)
+parser.add_argument(
+    "--case",
+    default="good",
+    choices=(
+        "good",
+        "different",
+        "dropped_row",
+        "changed_id",
+        "time_shift",
+        "missing_changed",
+        "invalid_expected",
+        "not_evaluable",
+    ),
+)
+args = parser.parse_args()
+args.output.mkdir(parents=True, exist_ok=False)
+source = [
+    ("0001", "1250", "1970-01-01T00:00:00+00:00"),
+    ("0002", None, "1970-01-01T00:00:01+00:00"),
+    ("0003", "1000000001", None),
+]
+prepared = [
+    {
+        "sample_id": identifier,
+        "duration_s": Decimal(ms) / Decimal("1000") if ms is not None else None,
+        "observed_at": datetime.fromisoformat(at) if at is not None else None,
+    }
+    for identifier, ms, at in source
+]
+if args.case == "different":
+    prepared[0]["duration_s"] = Decimal("1.251")
+elif args.case == "dropped_row":
+    prepared = prepared[:2]
+elif args.case == "changed_id":
+    prepared[0]["sample_id"] = "1"
+elif args.case == "time_shift":
+    prepared[0]["observed_at"] += timedelta(hours=1)
+elif args.case == "missing_changed":
+    prepared[1]["duration_s"] = Decimal("0.000")
+expected = pa.table(
+    {
+        "sample_id": ["0001", "0002", "0003"],
+        "duration_s": pa.array(
+            [Decimal("1.250"), None, Decimal("1000000.001")], type=pa.decimal128(16, 3)
+        ),
+        "observed_at": pa.array([0, 1000000, None], type=pa.timestamp("us", tz="UTC")),
+    }
+)
+if args.case == "invalid_expected":
+    expected = expected.take([0, 1, 0])  # Clave duplicada: referencia inválida.
+candidate = pa.Table.from_pylist(prepared, schema=expected.schema)
+duration = ef.ColumnSpec(
+    name="duration_s",
+    logical_type=ef.DecimalType(precision=16, scale=3),
+    nullable=True,
+    null_policy=ef.NullPolicy(representations=("null",)),
+    numeric_policy=ef.NumericPolicy(comparison="exact", unit="seconds"),
+)
+declaration = ef.infer_diff_contract(
+    expected.schema,
+    keys=["sample_id"],
+    column_overrides=(duration,),
+)
+result = ef.diff(
+    candidate,
+    expected,
+    contract=declaration,
+    work_dir=args.output / "private",
+    options=ef.ComparisonOptions(max_rows=1 if args.case == "not_evaluable" else 100),
+)
+report = ef.write_comparison_report(result, args.output / "report")
+# Solo los datos sintéticos de este ejercicio autorizan esta segunda vista.
+detail = ef.write_comparison_report(
+    result,
+    args.output / "synthetic-detail",
+    options=ef.ReportOptions(include_values=True, include_metadata=True),
+)
+print(detail.to_text())
+print(
+    "Estado:", result.state, "completo:", result.complete, "conteos finales:", result.counts.final
+)
+print("Contrato declarado/inferido:", declaration.model_dump_json())
+ef.assert_equivalent(result, report_path=args.output / "report" / "report.html")
+```
+
+Ejecuta `python -I preparacion.py --output prep-good`. Debe aceptar.
+Repite con `--case time_shift --output prep-time`: debe rechazar después de
+conservar el diagnóstico. Cada variante usa una carpeta nueva. También funciona
+con `python -I -O`; el gate no es un `assert` de Python.
+
+| Caso | Qué debe observarse | Consecuencia para el dataset |
+|---|---|---|
+| good | equivalent, completo, conteos finales, salida 0 | Conserva el contrato evaluado |
+| different | different; 1.251 frente a 1.250 | Cambio de precisión/valor |
+| dropped_row | different; falta 0003 | Pérdida de cobertura, incluso si era un valor grande |
+| changed_id | different; 1 no es 0001 | Ruptura de identidad y posibles joins posteriores |
+| time_shift | different; desplazamiento de una hora | Cambia ventana temporal y posibles features |
+| missing_changed | different; NULL no es cero | Cambia significado de ausencia |
+| invalid_expected | not_evaluable; clave duplicada | Reparar/revisar la referencia antes de aceptar |
+| not_evaluable | not_evaluable; presupuesto de una fila | No hay evaluación completa; no usar recuentos parciales como totales |
+
+Las siete variantes negativas terminan con excepción y retorno no cero. No se
+capturan para aprobar datos. Orden de filas ignorado por clave verificada; si tu
+tarea depende del orden usa `sequence_contract` con sus restricciones explícitas.
+La inferencia no sabe qué IDs/unidades/ausencias son válidos en tu dominio:
+inspecciona `.provenance` y sustituye los defaults con ColumnSpec/contrato revisados.
+No relajes precisión, rellenes NULL o elimines duplicados tras ver el fallo.
+
+## Consola, HTML y notebook
+
+`report/` es la vista minimizada por defecto. `synthetic-detail/report.html` y
+el texto mostrado contienen la misma decisión, clave/columna y valores del
+fixture. En un notebook puedes ejecutar el mismo script con argumentos o
+conservar `result` y mostrar `detail` como última expresión: `_repr_html_()`
+renderiza el mismo modelo. No hace falta leer manualmente toda la evidencia JSON.
+
+`difference_records` cuenta registros de diferencia, no siempre filas distintas.
+Los ejemplos mostrados son acotados; las diferencias completas y capturas siguen
+en evidencia privada. Si un conteo es parcial/desconocido no es cero definitivo.
+Una vista minimizada no anonimiza ni elimina los originales. No actives la vista
+detallada con datos reales sin permiso para la audiencia prevista.
+
+## Continuar con evidencia existente
+
+- [F](journeys.md#f-data-science-preparation-without-anomaly-claims): preparación
+  pandas, pérdida de fila/cambio de ID y clipping indebido
+- [E](journeys.md#e-telemetry-zones-missingness-duplicates-and-order): NULL distinto
+  de NaN, multiplicidad, orden e instantes de nanosegundos. Captura/comparación
+  no equivale a admisión de todo plan temporal por todos los motores
+- Consumidor independiente 0.1.9: `run --program preparation --variant good
+  --source pandas --target duckdb --data RUTA_DATOS --output CARPETA_NUEVA`;
+  su variante `defect` desplaza una hora. Usa su README para instalarlo. Incluye
+  datos USGS permitidos, esperado stdlib y seis direcciones, sin modelo entrenado
+
+Perfiles/detectores, si los necesitas, requieren su propia definición de features,
+normalidad/particiones, ajuste/calibración y soporte. Falta de soporte es
+`not_estimable`/`not_evaluable`, nunca ausencia de alerta. R, M, B, H y O siguen
+independientes y las salidas/etiquetas de otros motores no alimentan el detector.
+Estos ejemplos no acreditan utilidad científica ni adopción humana; el
+[protocolo](adoption.md) exige participantes reales y consentimiento.

equiframe/docs/compatibility.md

@@ -0,0 +1,254 @@
+# Compatibility and stability
+
+[Handbook](index.md) · [Upgrading](upgrading.md) · [Dependencies](dependencies.md)
+
+## Admission is not a measured support matrix
+
+The 0.12.4 release contract declares **Python `>=3.10,<3.14`**, meaning 3.10, 3.11, 3.12 and
+3.13. Dependency ranges describe installable admission, not every tested
+combination. A lock captures one resolution; it does not prove every operating
+system, architecture, Python patch or cross-product of package versions works.
+
+The recorded STEP6 matrix tested the then-identified wheel on **Debian 13/Linux
+x86_64, CPython 3.12.14 and 3.13.5**, with base, arrow, pandas, polars, duckdb,
+engines, ml and all profiles at minimum-direct and recent-permitted resolutions.
+Later STEP8 revalidation covered Arrow/all on those two interpreters at both
+resolution ends, plus matching benchmark consumers. These are historical receipts
+for their exact artifact hashes, not a blanket validation of every later wheel
+that retains version `0.11.1`.
+
+The following implementation checks actually ran from installed A14 artifacts
+on 27 October 2026. They establish the listed workloads, rather than every input
+or dependency combination. The final 0.12.4 artifact must still pass its own
+[release gates](releasing.md); a version change does not inherit an artifact hash.
+
+| OS / architecture | CPython actually exercised | Observed functional scope |
+|---|---|---|
+| Windows / x86_64 | 3.10.22 | Files, six native directions, semantic differences, complex ETL, IF/MAD/H and base R |
+| Windows / x86_64 | 3.11.17 | Same functional scope |
+| Windows / x86_64 | 3.12.4 | Same functional scope; the separate elevated symlink checks used 3.12.5 |
+| Windows / x86_64 | 3.13.15 | Same scope, plus final MIT wheel/sdist, clean base/extras consumers and literal README checks |
+| Linux / aarch64 | 3.10.12 | Files, six native directions, semantic differences, complex ETL, IF/MAD/H and base R |
+| Linux / aarch64 | 3.11.17 | Same functional scope |
+| Linux / aarch64 | 3.12.15 | Same functional scope |
+| Linux / aarch64 | 3.13.16 | Same scope, plus final wheel/sdist rebuild and clean installation |
+
+The functional scope used eight invented file formats (CSV, TXT, JSON, JSONL,
+XML, Excel XLSX, Parquet and GeoJSON), three native targets and all six directed
+conversions, with at least 30,000 rows per input. Thirty semantic cases combined
+the six directions with equality, exact Decimal changes, NaN/NULL distinction,
+an extra duplicate and declared-order changes. The complex ETL used two inputs
+of 30,000 rows, six native directions, independent expected values and two
+negative cases. ML/R checks kept eight training origins and four calibration
+origins separate, checked IF against scikit-learn and MAD against NumPy, and
+reviewed twelve native equal/different pairs with real R. These counts do not
+establish statistical accuracy or a minimum useful scientific sample size.
+
+Base R was 4.3.3 on Windows and 4.1.2 on Linux. The Python 3.13 runs used
+Pandas 3.1.0, Polars 1.44.2, DuckDB 1.5.6, Arrow 25.0.1 and scikit-learn 1.9.1;
+NumPy was 2.4.6 on Windows and 2.5.4 on Linux. Those pins are not asserted for
+the other minors: each interpreter used a compatible resolved closure. This
+matrix does not establish every legacy XLS, JSON nesting or XML dialect variant.
+Windows' two symlink cases subsequently passed with real elevated permissions
+on all four minors (eight passes, no skips); POSIX permission cases ran on Linux.
+Platform-specific skips retain their meaning and are not successful checks.
+
+No macOS, PyPy, other architecture, every Python patch or full minimum-to-maximum
+dependency cross-product is established by this table. Earlier STEP6 x86_64
+results above retain their own artifact identities; none is silently relabelled
+as a 0.12.4 final-artifact result.
+
+The first-use builder selects an explicit Python minor and its own hash-pinned
+dependency closure. The legacy `requirements.lock` is the 3.12 closure;
+`requirements-py310.lock`, `requirements-py311.lock` and
+`requirements-py313.lock` identify the other minors. Do not treat one closure as
+universal. A generated kit records its selected Python and still needs testing.
+
+## Declared runtime dependencies
+
+The installed wheel metadata is authoritative. Current direct ranges are:
+
+| Profile | Dependencies |
+|---|---|
+| Base | typing-extensions `>=4.14,<5`; pydantic `>=2.12,<3`; typer `>=0.20,<1`; tzdata `>=2025.2,<2027` |
+| `arrow` | pyarrow `>=23.0.1,<26` |
+| `pandas` | pandas `>=2.2,<4`, excluding `3.0.3`, `3.0.4`, `3.0.5`, `3.0.6`; pyarrow `>=23.0.1,<26` |
+| `polars` | polars `>=1.30,<2`; pyarrow `>=23.0.1,<26` |
+| `duckdb` | duckdb `>=1.5.6,<2`; pyarrow `>=23.0.1,<26` |
+| `engines` | All three engines and the same Arrow range |
+| `files` | The `pandas` and `arrow` dependencies above; openpyxl `>=3.1,<4`; xlrd `>=2,<3`; defusedxml `>=0.7,<1` |
+| `ml` | scikit-learn `>=1.7,<1.10`; numpy `>=2,<3` |
+| `eda` | duckdb `>=1.5.6,<2`; pyarrow `>=23.0.1,<26` |
+| `eda-charts` | The `eda` dependencies plus plotly `>=6.3,<8` |
+
+Pandas 3.0.3–3.0.6 are excluded because their `ZoneInfo.from_file` regression
+can replace the supplied timezone rules with a named-key lookup. This can
+silently change historical ETL timestamps even when the locked `tzdata` bytes
+are correct. Pandas documents the correction in
+[3.1.0 (GH 66828)](https://pandas.pydata.org/pandas-docs/version/3.1.0/whatsnew/v3.1.0.html).
+The controlled ARM312 case preserves its original inputs and SDK: 3.0.6 shifts
+three `EET` results by one hour; 3.1.0 passes the same complete native outputs
+and readbacks. That diagnostic does not certify the complete environment matrix.
+
+Minimum-direct testing means a mutually resolvable minimum direct set with
+available binary wheels and compatible transitive dependencies. It does not mean
+all historical transitive minima. Binary availability may raise a practical
+minimum on a Python/platform. A recent-permitted resolution is time-bound and
+must be identified by its pins and hashes.
+
+Base imports remain light even when extras are installed: importing EquiFrame
+or its compatibility registers does not import Arrow, pandas, Polars, DuckDB,
+NumPy or scikit-learn. The selected operation loads its required dependencies.
+Missing extras fail explicitly with a diagnostic identifying the dependency.
+
+`files` supplies local file readers and the initial Pandas DataFrame. Select the
+`polars` or `duckdb` extra as well when that engine is the conversion target.
+`equiframe doctor --extra files` checks installed dependency metadata without
+loading a dataset. The optional language-R reviewer requires a user-installed
+`Rscript` executable and base R; it has no Python installation extra and does not
+install R packages. Its result records the R version actually used.
+
+File loading and language-R review were introduced on 26 October and exercised
+in the implementation runs above. Their stabilization commits to the admitted
+interfaces and failure semantics; it does not expand the admitted type/policy
+subsets or reinterpret historical results.
+
+Dependency changes require fresh artifact, semantic and environment checks.
+Native engine/Arrow transport and timezone behavior must be rechecked, not just
+`pip check`. ML parity is against the installed scikit-learn version; fitted
+forests, thresholds and decisions are not promised identical across versions.
+See [dependency/SBOM policy](dependencies.md) before upgrading transitives.
+
+## Public-surface classification
+
+`get_stability_register()` is exhaustive **for the core**. It separately
+classifies API, CLI, format, evidence, presentation and namespace surfaces.
+`get_adapter_capabilities()` distinguishes capture, comparison, native execution
+and migration; each entry gives conditions, known losses and implementation/test
+references. This descriptive register does not execute a probe or admit a case.
+The four returned capability records name Hernán Troya (`htroya`) as maintainer
+of the internal EquiFrame adapter implementations, with best-effort support as
+described in [maintenance](maintenance.md). This does not assign him maintenance
+of Arrow, Pandas, Polars or DuckDB themselves. Unassigned defaults remain available
+when callers construct their own capability records.
+
+| Status | Main surfaces |
+|---|---|
+| Stable | Existing contracts/comparison/native execution/rules/assertions/Verify/bundles; local file reading and conversion; explicit DuckDB capture; closed IR and native pairwise migration, including admitted windows; profiles/preprocessing/IF/MAD/H; optional language-R review and finalization; their explicitly inventoried models/formats |
+| Experimental | Standalone pipeline orchestration, ingestion/destinations/workflows, snapshot providers, pipeline reporting/reduction, first-use demo/doctor and the `equiframe.eda` namespace |
+| Unsupported | Quarantined historical `equiframe.benchmark` helper |
+| Outside this inventory | Private `_...` internals, dependency APIs and the separate benchmark package's experimental API |
+
+Stable protects the documented signature and semantic/error contract within
+admitted capabilities. It is not a certification, maturity claim for every
+workflow, service-level guarantee or promise of speed. Experimental code still
+must reject unsafe/unsupported input, preserve historical meaning and report
+failures honestly. Adding an export requires an explicit reviewed classification.
+
+Stable CLI includes contract validation, comparison, operational Verify, bundles,
+`dataset load`, `dataset inspect` and migration validate/run/verify. Workflows,
+ingestion, standalone pipeline execution/reporting, evidence inspection,
+reduction and first-use commands retain their experimental classification. Inspect
+the registry for exact command/parameter classifications and exit-code contracts.
+Do not parse help formatting, diagnostic prose, HTML or console colors as a
+machine interface.
+
+The stable commitments are deliberately bounded:
+
+- File conversion validates complete values, columns/order and admitted types;
+  ambiguous sheets, records and delimiters require a choice. Source bytes and
+  effective options identify the load; changing a captured frame requires a new
+  capture. GeoJSON structures can be transported without making nested geometry
+  a supported semantic-comparison type. Local loading is not a path sandbox.
+- IR validation and both native compiler checks define the supported plan.
+  Each built-in engine executes independently; no arbitrary program translation, fallback
+  engine, implicit rounding or pruning of a failed guard is promised. Successful
+  compilation is not equivalence or proof of an expected result's independence.
+- ML interface stability protects fit/calibration/inference separation, feature
+  admission and explicit unavailable states. Callers remain responsible for the
+  meaning of selected features and normal-training/calibration origins; validating
+  a vector is not automatic detection of every possible label encoding or leak.
+  Stability does not promise detection power,
+  identical trained forests across dependency versions or a throughput target.
+  Operational rules R and the external language R remain different components.
+- The R reviewer admits its documented exact policy/type subset and external
+  Rscript. The bound finalizer verifies execution/profile/IF/artifact association;
+  the low-level finalizer requires the caller to associate component decisions.
+  A missing reviewer, unsupported contract or disagreement cannot produce an
+  accepted result. Its process timeout excludes earlier Python capture time.
+
+`PipelineInput`, `EvidenceFile`, `StageRecord`, `PipelineSpec` and `PipelineResult`, and the
+versioned spec/result formats, are protected shared models because migration
+embeds them. This does not stabilize `run_pipeline`, its standalone request,
+workflow APIs or the private local directory layout. Persisted semantic formats
+and producer layout are separate commitments. The per-name register is decisive.
+
+## Deprecation and persisted-format commitments
+
+This prospective policy began with the private STEP6 candidate. It does not
+invent prior public releases or assert a deprecation has already happened.
+
+1. Incompatible stable changes require a changelog notice naming affected
+   surfaces, reason, replacement, migration example and earliest removal date/version
+2. Callable Python entry points emit `DeprecationWarning`; CLI invocations warn
+   on stderr without changing exit status merely because of the warning
+3. Removal waits for **both at least two subsequent minor releases and 90 days**.
+   A notice in 0.12 cannot be removed before 0.14 or day 90; time alone is insufficient
+4. During 0.x, a stable removal occurs in an announced minor; from 1.x it requires
+   a major, with the same notice window. Patch releases normally preserve it
+5. Experimental changes can occur in a minor with changelog and migration in that
+   release. Downgrading a stable label cannot evade the stable notice window
+6. Withdrawing a persisted-format reader follows the stable window even if its
+   producer is experimental. Historical evidence is not rewritten or reinterpreted
+
+**Fail-closed exception:** security flaws, corrupted evidence, semantic loss or
+false equivalence may be rejected immediately, including in a patch. Record
+scope, reason, safe recovery/migration and a regression. Compatibility never
+requires preserving a false success. An unrelated capability expansion is not
+permission to change a valid old meaning silently.
+
+Package version, format version and contract revision remain independent.
+Incompatible writes need a new format and explicit migration; unknown versions
+are rejected. Historical fixtures identify private commits and formats rather
+than invented public releases. Their readers verify those admitted artifacts;
+they do not promise arbitrary old data will be accepted.
+
+HTML/text/notebook presentation may evolve while JSON semantic contracts remain.
+Historical report verification uses the admitted frozen format behavior, not the
+current renderer's bytes. Rehashing modified/corrupt evidence does not make it
+valid. Preserve originals and create new, traceable migrated artifacts when an
+explicit conversion exists. No automatic universal converter is promised.
+
+## Filesystems, concurrency and external integrations
+
+Local evidence publication uses exclusive creation and, where specified, atomic
+hard links. Verify your filesystem and permissions; network/object stores are not
+implicitly supported. Do not make independent processes write a shared DuckDB
+file. A production service owns snapshot publication, writer coordination,
+security, concurrency and aggregate resource limits.
+
+The core has no requirement for OCI, SERCOP, a data warehouse or the benchmark
+package. Explicit DataSource/adapter integrations can provide external services;
+that integration's authentication, network policy, snapshot consistency and
+acceptance must be verified separately. A local synthetic test does not certify
+a real service or another team's implementation.
+
+## Python 3.10 legacy-runtime boundary
+
+EquiFrame compatibility with Python 3.10 does not provide upstream security
+maintenance or vendor extended maintenance. Deployment owners must check their
+runtime's [current lifecycle](https://devguide.python.org/versions/) and their
+own maintenance policy; this does not remove 3.10 from the compatibility matrix.
+
+The a8 compatibility changes preserve named type aliases through
+`typing_extensions.TypeAliasType`, retain strict typing, use local Decimal
+contexts without 3.11-only keyword arguments, and validate supported timestamp
+literals consistently while retaining their original nanoseconds/text.
+Windows junction checks use lstat reparse tags available since 3.8; simulated
+branch tests alone are not actual Windows execution. The measured platform
+scope is the table above; preserved roadmap cells do not add unexecuted support.
+
+The benchmark declares `tomli` only below Python 3.11. Source-development tools
+use the same fallback from the explicitly declared development dependency.
+Normal pip resolution chooses compatible branches within unchanged native
+dependency ranges; the recorded locks identify those branches per Python.