equiframe 0.12.4__py3-none-any.whl

equiframe/docs/sqlite-snapshots.md

@@ -0,0 +1,262 @@
+# A consistent SQLite snapshot through the existing ports
+
+[Handbook](index.md) · [Extension ports](extending.md) · [Recipes](recipes.md)
+
+**For architects and data engineers:** capture related tables from an existing
+SQLite database once, supply them through `SnapshotClient`, and let the existing
+`SnapshotDataSource` check and record the evidence. No benchmark, new framework,
+remote service, ORM or core dependency is introduced.
+
+The wheel and source distribution carry two complete external application files:
+
+- `examples/integrations/sqlite_snapshot.py`: the small producer and detached client
+- `examples/integrations/sqlite_snapshot_demo.py`: a synthetic runnable integration
+
+They intentionally live outside `equiframe`. The producer is a concrete SQLite
+DB-API example, not a promise that every DB-API database has SQLite's transaction
+semantics. The core snapshot exports remain experimental; existing manifest 1.0,
+fingerprints, imports and benchmark aliases are unchanged.
+
+## Install an identified artifact
+
+The producer needs Python's standard-library `sqlite3`, the identified
+EquiFrame wheel and its `arrow` dependencies. The demo also executes a native
+DuckDB join, so it needs the `duckdb` extra. It does not require pandas, Polars,
+scikit-learn, network access, credentials or any real data to run.
+
+Use the [verified first-use installation](recipes.md#1-obtain-verify-and-install-the-kit)
+in a fresh supported Python environment outside the checkout. Commands below
+show 3.12; use the minor recorded by your interpreter-specific kit. Its hash-pinned
+`requirements.lock` covers this demo as well as the other recipes; pandas/pytest
+in that shared kit are not new dependencies of this producer. Copy **both**
+integration files from the installed wheel's resources (shown below) or the
+corresponding verified source distribution into a new working directory.
+Use a registry artifact only after verifying its project, version and identity;
+the string `0.12.4` alone does not identify bytes. An offline kit is optional,
+not a separate public-release channel promised by this documentation.
+
+For example, after verifying the private kit, use these POSIX commands from
+outside the checkout. `KIT` is the extracted verified first-use kit:
+
+```bash
+python3.12 -m venv sqlite-example-env
+sqlite-example-env/bin/python -m pip install --require-hashes --only-binary=:all: \
+  -r "$KIT/requirements.lock"
+sqlite-example-env/bin/python -m pip install --no-index \
+  "$KIT/wheels/equiframe-0.12.4-py3-none-any.whl"
+sqlite-example-env/bin/python -m pip check
+mkdir sqlite-example-work
+sqlite-example-env/bin/python - <<'PY'
+from importlib.resources import files
+from pathlib import Path
+
+source = files("equiframe").joinpath("examples/integrations")
+for name in ("sqlite_snapshot.py", "sqlite_snapshot_demo.py"):
+    Path("sqlite-example-work", name).write_bytes(source.joinpath(name).read_bytes())
+PY
+cd sqlite-example-work
+../sqlite-example-env/bin/python sqlite_snapshot_demo.py --case good --output good
+```
+
+The first pip command deliberately downloads pinned dependencies from the
+configured index. For offline use, obtain the same reviewed dependency wheels
+and add `--no-index --find-links /absolute/path/wheelhouse`. See the kit guide for
+Windows environment commands; this example does not independently qualify a
+Windows, macOS or ARM64 platform. Run the script normally: unlike single-file
+recipes, these two files require their containing directory on Python's import
+path, which `python -I script.py` deliberately omits.
+
+Focused development checks used Python **3.12.14**, SQLite **3.53.1**, PyArrow
+**25.0.1**, DuckDB **1.5.6**, Pydantic **2.13.5**, Typer **0.27.2** and tzdata
+**2026.4** on Linux. Exact transitive versions/hashes are the unchanged candidate
+lock and shared first-use lock. These are observed versions, not minimum support
+claims. Record the final commit and wheel/sdist hashes alongside a new run.
+
+## Three runnable outcomes
+
+Every case requires a **new** output directory; reuse fails before changing it.
+All data is synthetic: two accounts and three selected ledger entries. A fourth
+entry belongs to another cohort and is excluded by a bound SQL parameter.
+
+```bash
+python sqlite_snapshot_demo.py --case good --output good-new
+# execution=completed; comparison=equivalent; exit=0
+
+python sqlite_snapshot_demo.py --case different --output different-new
+# execution=completed; comparison=different; exit=1
+
+python sqlite_snapshot_demo.py --case corrupt --output corrupt-new
+# execution=invalid_input; comparison=not_evaluable; exit=3
+```
+
+The literal expected output is independently authored in `expected_output()`:
+`A / Café / 1.10 / USD`, `B / Café / NULL / USD`, and
+`C / NULL / -0.01 / EUR`. It is never generated by the SQLite query or DuckDB
+join. The discrepancy changes A to `1.11`; currencies stay separate columns and
+no aggregate total hides the record-level difference. The controlled failure
+changes one downloaded byte while preserving the original manifest. The existing
+consumer rejects the SHA-256 mismatch before exposing the table to DuckDB.
+
+Each output directory contains:
+
+- `synthetic.sqlite`: only the demo's small synthetic source database
+- `execution/<run-id>/`: native execution evidence, pinned manifest, input
+  artifacts and, on success, the joined output
+- `comparison/`: complete captured comparison evidence for successful execution
+- `report/`: default-redacted JSON/text/HTML report, written before the assertion
+- `receipt.json`: case, identity/fingerprint, explicit states and exit code
+
+Failed execution has no successful output/comparison/report. Its receipt states
+`not_evaluable` as the demo's gate status; it does not fabricate an evaluated
+`ComparisonResult`. Inspect the execution's failure diagnostics. A producer
+exception before execution raises normally and yields no published snapshot
+client; incomplete output folders must not be accepted as successful runs.
+
+Acceptance is the process exit code **0** and a successful
+`assert_equivalent(comparison)`, not existence of a report, a completed join or
+truthiness of a result. A matching synthetic expected output establishes this
+fixture's behavior, not independent human review, business correctness in
+production, or scientific evidence.
+
+## Use your own trusted queries
+
+The producer keeps the native boundary explicit:
+
+```python
+from pathlib import Path
+import pyarrow as pa
+import equiframe as ef
+from sqlite_snapshot import SQLiteQuery, capture_sqlite_snapshot
+
+client = capture_sqlite_snapshot(
+    Path("existing.sqlite"),
+    snapshot_id="ledger.2026-10-06.001",
+    queries=(
+        SQLiteQuery(
+            name="entries",
+            sql="SELECT id, amount FROM entries WHERE cohort = ? ORDER BY id",
+            parameters=("reviewed-cohort",),
+            schema=pa.schema(
+                [
+                    pa.field("id", pa.string(), nullable=False),
+                    pa.field("amount", pa.decimal128(10, 2)),
+                ]
+            ),
+        ),
+    ),
+    domain_schema_revision="ledger-schema.1",
+    extraction_revision="reviewed-query.1",
+    provenance=("Authorized ledger capture; exact amounts stored as TEXT",),
+)
+source = ef.SnapshotDataSource(
+    "ledger.2026-10-06.001",
+    client=client,
+    expected_domain_schema_revision="ledger-schema.1",
+)
+# Pass source to the existing execute, migrate or run_workflow API.
+```
+
+All related tables must be included in **one** capture call. Two calls open two
+transactions and do not establish cross-call consistency. The producer owns a
+new read-only connection to the existing main database, explicitly begins one
+native SQLite transaction and reads every query inside it. The first native
+read anchors the snapshot. In WAL mode, another connection can commit while
+this reader continues seeing the original table versions; the functional test
+does exactly this between the two SELECTs. In rollback-journal mode writers can
+wait on readers. The producer does not change journal mode or configure writers.
+
+After every query succeeds, the producer releases the read transaction with
+rollback and closes the connection before returning detached Arrow IPC bytes.
+The same cleanup runs on SQL, schema, conversion and budget failures. Cursors
+are closed explicitly. It does not borrow, commit or close a caller-owned
+connection. Later database changes or removal do not change the captured client.
+There is no implicit recapture, retry or `latest` resolution.
+
+Choose a distinct `snapshot_id` for each publication and meaningful schema/query
+revisions. This process-local example has no global ID registry, persistent
+catalog, lease or restart recovery. Its opaque artifact URIs are identifiers
+under `example.invalid`, never fetched as URLs. Their per-capture namespace keeps
+references distinct, so separate captures can have different fingerprints even
+with identical rows. Fixed identity means the chosen client/manifest stays
+unchanged for a consuming run, not that a human label authenticates a producer.
+
+## Deliberately supported schema
+
+The SQL cursor names/order must exactly match the declared Arrow schema.
+SQLite's dynamic value types are checked before Arrow conversion:
+
+| Declared Arrow type | Required non-NULL SQLite value | Behavior |
+|---|---|---|
+| `int64` | INTEGER / Python `int` | Exact signed 64-bit value; REAL/text casts are refused |
+| `string` | TEXT / Python `str` | Unicode preserved; no normalization or coercion |
+| `decimal128(p, s)` with `0 <= s <= p` | Plain decimal TEXT | Explicit Decimal parse, exact scale/precision check, no float intermediary |
+
+NULL is preserved only for nullable fields. Duplicates, empty tables, column
+order and returned row order are preserved in the capture; the demo comparison
+explicitly uses bag semantics. Declare `ORDER BY` where query order matters.
+Decimal negative zero is refused because Arrow decimal cannot retain its sign.
+Exponents, NaN/Infinity strings, REAL money, overflowing precision and values
+requiring rounding are refused. Do not cast existing REAL money to TEXT and
+assume that this recovers precision already lost in storage.
+
+Dates, timestamps/time zones, BLOBs, floats/NaNs, other integer widths, structured
+types, custom SQLite converters and Arrow field/schema metadata are outside this
+small producer's supported subset. They fail explicitly instead of being
+silently coerced. This does not narrow the core's separate
+[semantic support](semantics.md). Adding a new producer type needs its own exact
+mapping, independent expectations and rejection tests.
+
+`SnapshotDataSource` then independently checks downloaded size/SHA-256, row
+count, names/order, physical/logical type and declared non-nullability. It saves
+the complete manifest and fingerprint, including when selecting fewer tables.
+The producer's declared provenance/revisions are copied into that manifest;
+they are assertions by the trusted application, not verified origin claims.
+
+## Operational limits and privacy
+
+Keep this implementation for small, trusted datasets. Defaults are 10,000 rows
+per table, 256 rows per fetch, 16 MiB total serialized payload and a five-second
+SQLite lock wait. The byte budget is checked **after** Arrow serialization;
+queries, fetches, string/Decimal conversion and Arrow allocation can consume
+resources before checks. Complete detached payloads remain in memory. Lock
+timeout is not query timeout. No hard memory, execution-time, disk, process or
+network quota is provided; no cancellation/streaming service is implemented.
+
+The SQLite database, application SQL, injected client and dependencies must be
+trusted. `mode=ro`, SELECT/WITH admission, bound values and hashes do not make
+this a sandbox, authenticate an author or establish a no-egress guarantee. The
+transaction's consistency claim covers the ordinary persistent main database
+tables in these queries; it does not synchronize remote systems, attached
+databases, volatile functions, external virtual tables or filesystem effects.
+
+SQL text, parameters and the source database pathname are not included in the
+snapshot manifest by this producer. Query/database exceptions may still expose
+application details to a caller; handle them according to your logging policy.
+Provenance is caller-authored and raw SQLite/Arrow/comparison evidence can contain
+private values. Use authorized private directories and keep synthetic examples
+separate from real data. The report's redaction does not redact or delete raw
+artifacts. This example neither implements José's service nor defines Jhair's
+DW, publication rules or acceptance criteria.
+
+## Run the focused checks
+
+From the repository root in the existing locked development environment:
+
+```bash
+uv run --locked --all-extras ruff check examples/integrations tests/test_sqlite_snapshot_example.py
+uv run --locked --all-extras ruff format --check examples/integrations tests/test_sqlite_snapshot_example.py
+uv run --locked --all-extras mypy --python-version 3.12 examples/integrations/sqlite_snapshot.py examples/integrations/sqlite_snapshot_demo.py
+uv run --locked --all-extras pytest -q tests/test_sqlite_snapshot_example.py
+```
+
+The tests cover native concurrent WAL consistency, lifecycle cleanup on success
+and errors, fixed manifest selection/provenance, schema-preserving empty/NULL
+tables, controlled size/hash/schema/row/nullability mismatches, exact conversion
+admission and the copied standalone demo's three exit codes. These are ordinary
+functional checks, not a security assessment, production load test, final
+artifact verification or new platform matrix. Final candidate distribution
+verification remains a separate gate.
+
+Existing orchestrators can call the Python API inside a task or run the demo's
+CLI-shaped gate as a subprocess, retain its private evidence, and propagate
+nonzero exits. No scheduler or new orchestration framework is required.

equiframe/docs/universal-sources.md

@@ -0,0 +1,49 @@
+# Inputs from files, SQL and API responses
+
+`LocalDataSource` accepts existing `FileInput` (CSV/JSON/JSONL), `ArtifactInput`
+(hashed Parquet/Arrow), `ArrowInput` and the new experimental `SQLiteInput` and
+`StreamInput`. Every input exposes `load(context)` and produces a `LoadedTable`.
+Use the same declared columns, null, Decimal and timestamp policies regardless
+of where the data came from. Ingestion retains original bytes and conversion
+receipts; a rejected or quarantined input fails execution.
+
+`SQLiteInput(path, query, spec, parameters=(), batch_rows=4096)` reads one trusted
+parameterized SELECT/WITH in an owned read-only transaction. Its `IngestionSpec`
+uses JSONL with direct record mappings. Decimal fields require SQLite TEXT;
+REAL cannot recover exact monetary values. Textual identifiers, duplicate rows
+and NULLs remain visible. BLOB and ambiguous column names are rejected. It does
+not manage a remote warehouse or claim another database provider's isolation.
+
+`StreamInput(open_stream, spec, expected_sha256=None, batch_rows=4096)` consumes
+an explicitly injected binary response context manager. The caller implements
+API authentication, transport and timeouts. EquiFrame never opens an implicit
+URL. It closes the response on success or failure, checks byte budgets and an
+optional separately supplied digest, then uses the existing typed ingestion.
+Blocking transport calls remain the caller's responsibility. JSON documents
+still materialize; CSV/JSONL parsing is incremental. Final tables and public
+conversion receipts materialize within cooperative budgets, not a hard RSS cap.
+
+`RecordBatchInput(open_batches, schema)` accepts an explicit Arrow batch reader
+context manager. Every batch must match the exact schema, including metadata;
+nonnullable fields cannot contain NULL. Row and Arrow-byte budgets accumulate
+across all batches before constructing the final chunked table. The reader is
+closed after success, schema failure, cancellation or budget exhaustion. The
+final table still materializes; this is not a disk-spilling execution engine.
+
+`CompositeDataSource({"logical_name": (provider, "provider_table")})` binds
+independent `DataSource` implementations to the names of one contract. Bindings
+are copied, tables are checked and failures propagate. No plugin is discovered
+or imported implicitly. Providers own their immutable snapshots, authentication
+and type fidelity. Composition does not create an atomic snapshot across
+databases or APIs. `LocalDataSource` also accepts external objects with
+`load(context) -> LoadedTable`, so a new input need not modify core.
+
+SQLite additionally checks cancellation/timeouts through its native progress
+handler every 1000 VM instructions, including before the first row is produced.
+Its busy lock wait uses a 5-second SQLite timeout; interruption remains
+cooperative. Stream reads and external batch retrieval remain caller-controlled
+blocking operations and require transport timeouts supplied by that caller.
+
+These adapters are library inputs. Untrusted SQL/callbacks are not sandboxed.
+Register external inputs explicitly; document their type, consistency and size
+guarantees before using them as interchangeable sources.

equiframe/docs/universalidad-cinco-pasos.md

@@ -0,0 +1,107 @@
+# EquiFrame más universal en cinco pasos
+
+[Inicio](inicio.md) · [Fuentes](universal-sources.md) · [Extensiones](extending.md)
+
+EquiFrame 0.12.4 permite cambiar la entrada conservando un
+contrato y un plan nativo común. El siguiente recorrido utiliza datos sintéticos
+y un esperado literal independiente. No necesita benchmark, servicios remotos,
+credenciales, GitHub Actions ni recursos de pago.
+
+1. **Entradas y contrato común.** CSV, JSON/JSONL, Parquet y Arrow reutilizan los
+   adaptadores existentes. `SQLiteInput` añade consultas locales parametrizadas
+   de solo lectura. `StreamInput` recibe respuestas binarias de un cliente
+   proporcionado por el consumidor. Las columnas, tipos, claves, ausencias,
+   monedas, fechas y duplicados siguen siendo decisiones explícitas del contrato.
+2. **Operaciones nativas.** Se reutilizan filtros, proyecciones, conversiones
+   exactas admitidas, agregaciones, ordenamientos y seis tipos de join. El nuevo
+   `Window` añade numeración y valores anteriores/siguientes por partición o
+   sobre toda la entrada: `row_number`, `lag` y `lead`, con offset declarado.
+   Pandas, Polars y DuckDB ejecutan cada uno su implementación nativa.
+3. **Significado de los datos.** Las ventanas conservan tipos y unidades, valores
+   extremos, precisión Decimal, NULL/NaN y zonas horarias admitidas. Los empates
+   se rechazan para impedir elecciones arbitrarias. Un tipo incompatible o una
+   capacidad no admitida se explica antes de ejecutar; un fallo nunca aprueba.
+4. **Extensiones y límites.** `CompositeDataSource` vincula proveedores externos
+   a nombres lógicos. `RecordBatchInput` verifica esquemas Arrow explícitos y
+   límites acumulados. SQLite comprueba cancelación y tiempo durante consultas
+   largas. Un nuevo proveedor implementa `table_names` y `resolve`; un nuevo
+   input local implementa `load(context)`. No necesita modificar el núcleo.
+5. **Primer uso completo.** El ejemplo instalado compara seis entradas bajo el
+   mismo contrato y plan en los tres motores: 18 ejecuciones por caso. Guarda
+   capturas, comprobaciones, reportes y un recibo; distingue coincidencia,
+   discrepancia e integridad fallida.
+
+## Instala y ejecuta el ejemplo
+
+Usa un wheel identificado por revisión y SHA-256. El código propio tiene
+licencia MIT; los componentes de terceros conservan sus términos. La publicación
+pública sigue pendiente. Desde una carpeta nueva fuera del checkout:
+
+```powershell
+py -3.12 -m venv .venv
+.\.venv\Scripts\python.exe -m pip install 'C:\ruta\equiframe-0.12.4-py3-none-any.whl[engines]'
+.\.venv\Scripts\python.exe -m pip check
+.\.venv\Scripts\python.exe -m equiframe.examples.integrations.universal_first_use --output caso-correcto
+.\.venv\Scripts\python.exe -m equiframe.examples.integrations.universal_first_use --case different --output caso-distinto
+.\.venv\Scripts\python.exe -m equiframe.examples.integrations.universal_first_use --case corrupt --output caso-danado
+```
+
+En Linux/macOS sustituye el intérprete por `python3.12` y el ejecutable del
+entorno por `.venv/bin/python`. Son instrucciones de uso; cada entorno requiere
+su propia ejecución registrada. No presupongas validación nativa de macOS.
+
+Los directorios de salida deben ser nuevos. El caso correcto termina con código
+0 y 18 comparaciones equivalentes. `different` altera únicamente SQLite de
+12.30 a 12.31: produce discrepancias en los tres motores y termina con código 1.
+`corrupt` declara un digest incorrecto para la respuesta de API: rechaza esa
+entrada en los tres motores, no compara sus resultados y termina con código 3.
+Cada caso conserva un `receipt.json`; los casos evaluados también conservan
+reportes bajo cada combinación de motor y fuente. El cliente API del ejemplo
+es una respuesta en memoria explícitamente sintética.
+
+## Cambia únicamente la configuración de entrada
+
+```python
+source = ef.LocalDataSource({"input": ef.FileInput(csv_path, csv_spec)})
+# La alternativa usa las mismas columnas declaradas con formato JSONL:
+source = ef.LocalDataSource(
+    {
+        "input": ef.SQLiteInput(
+            database,
+            "SELECT id, sequence, amount FROM entries WHERE cohort = ?",
+            jsonl_spec,
+            ("demo",),
+        )
+    }
+)
+```
+
+El contrato y el plan no cambian. La especificación de lectura sí declara el
+formato, los campos y las conversiones. No se infieren monedas ni se convierten
+SQL REAL a Decimal exacto. Para un API real, pasa un context manager de respuesta
+a `StreamInput`; tu cliente controla autenticación y timeouts. Para otro motor
+SQL, implementa el puerto con tipos e identidad explícitos y comprueba su
+consistencia; este candidato no incluye adaptadores PostgreSQL/MySQL.
+
+## Límites comprobables
+
+El IR y las ventanas admitidas forman parte del contrato estable; los proveedores,
+las fuentes extendidas y la orquestación conservan su alcance experimental.
+Las capacidades exactas y las
+restricciones de ventanas están en [migration-ir](migration-ir.md) y en
+`get_adapter_capabilities()`. DuckDB materializa y comprueba la ventana antes de
+filtros o proyecciones posteriores, para que no oculten sus errores. No hay
+frames arbitrarios ni agregaciones de ventana admitidos.
+
+Los lotes reducen y controlan la lectura; las tablas finales y los recibos de
+ingestión todavía se materializan. Los límites son cooperativos, no una cuota
+dura de RAM ni procesamiento distribuido. Los bloqueos de transporte requieren
+timeouts del cliente. Combinar proveedores no crea una transacción común entre
+bases o APIs. Los contratos admiten dominios distintos, pero un ejemplo
+sintético no acredita adopción real en salud, finanzas ni producción.
+
+Los cinco pasos de implementación no son un porcentaje de Universalidad
+UV01–UV12 ni una declaración de compatibilidad universal al 100 %. Windows,
+Linux y macOS, versiones de Python y arquitecturas requieren recibos del mismo
+candidato. La matriz histórica, licencias, revisión humana y publicación no se
+cierran mediante estas mejoras técnicas.