paradoxdb 0.1.0__tar.gz

paradoxdb-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.hypothesis/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+# Generated Paradox files (always produced by the synthetic factory, never committed)
+*.DB
+*.db
+*.MB
+*.mb
+*.PX
+*.px
+*.X??
+*.Y??

paradoxdb-0.1.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and the project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+
+- GitHub Actions workflow that builds, checks and publishes the package to PyPI
+  through trusted publishing on every published release.
+
+### Changed
+
+- README links are absolute so that they work on the PyPI project page.
+
+## [0.1.0] - 2026-11-15
+
+### Added
+
+- Reader for Paradox `.DB` tables, versions 3.0 to 7 (headers with and
+  without the 4.0+ extension), with per-table code page and per-cell state
+  (`OK` / `NULL` / `INVALID`) plus raw bytes.
+- Decoders and encoders for every field type: alpha, date, short, long,
+  currency, number, logical, memo, formatted memo, BLOB, OLE, graphic,
+  time, timestamp, autoincrement, BCD and bytes.
+- Reader for `.MB` memo files: embedded, single-block and sub-allocated
+  memos.
+- Block-chain walker that returns every record present in the data blocks
+  and reports the mismatch with the declared record count.
+- Writer on top of a template header, producing new `.DB`, `.MB` and `.PX`
+  files, with optional legacy sort order and primary-key uniqueness check.
+- Primary index (`.PX`) builder and verifier.
+- Table profiler (aggregates per table and field, SHA-256 fingerprints) and
+  CSV / JSON export.
+- `paradoxdb` command line: `profile`, `export`, `verify-index`.
+- Synthetic table factory used by the test-suite and the examples.
+- Optional `Decryptor` protocol for encrypted tables (the library never
+  implements the cipher itself).
+
+[Unreleased]: https://github.com/arielgiamportone/paradox-db-py/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/arielgiamportone/paradox-db-py/releases/tag/v0.1.0

paradoxdb-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 arielgiamportone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

paradoxdb-0.1.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.5
+Name: paradoxdb
+Version: 0.1.0
+Summary: Pure-Python reader and writer for Paradox tables (.DB / .MB / .PX) with explicit per-cell state
+Project-URL: Homepage, https://github.com/arielgiamportone/paradox-db-py
+Project-URL: Repository, https://github.com/arielgiamportone/paradox-db-py
+Project-URL: Issues, https://github.com/arielgiamportone/paradox-db-py/issues
+Project-URL: Changelog, https://github.com/arielgiamportone/paradox-db-py/blob/main/CHANGELOG.md
+Author: arielgiamportone
+License-Expression: MIT
+License-File: LICENSE
+Keywords: b-tree,bcd,bde,borland,database,delphi,file-format,legacy,memo,migration,paradox
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# paradox-db-py
+
+[![CI](https://github.com/arielgiamportone/paradox-db-py/actions/workflows/ci.yml/badge.svg)](https://github.com/arielgiamportone/paradox-db-py/actions/workflows/ci.yml)
+![Python 3.11 | 3.12](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue)
+![License MIT](https://img.shields.io/badge/license-MIT-green)
+
+**Pure-Python reader and writer for Paradox tables** (`.DB` data, `.MB` memos
+and BLOBs, `.PX` primary index), versions 3.0 to 7. No native code, no copyleft
+dependencies, no silent conversions: every cell comes back as `OK`, `NULL` or
+`INVALID` together with its raw bytes.
+
+*Versión en español: [README.es.md](https://github.com/arielgiamportone/paradox-db-py/blob/main/README.es.md).*
+
+> Patterns developed during my work at Intervalor Data and published with permission. Independent clean-room implementation with synthetic data; it contains no code or data from the company or its clients.
+
+---
+
+## 1. The problem
+
+A fixed-asset management system written in Delphi on top of the Borland
+Database Engine kept decades of history in Paradox tables. Modernising it meant
+two things at once:
+
+1. **Extract** every record without loss. Not "most records": the legacy
+   engine left records in the data blocks that the header never counted, and
+   whole columns of monetary values stored as BCD that no longer decoded.
+2. **Give tables back** to the legacy application during a long transition,
+   so the old and the new system could coexist for months.
+
+The Python ecosystem offered only bindings over a C library (GPL) that is
+read-only in practice, forces one global text encoding, skips the records the
+header does not declare and corrupts its memory heap after a few dozen write
+operations. For an on-premise product none of that was acceptable.
+
+## 2. Constraints
+
+| Constraint | Consequence in the design |
+|---|---|
+| Distributed on-premise inside a commercial product | Pure Python, MIT licence, zero runtime dependencies |
+| Real tables hold personal and financial data of third parties | Every fixture is generated by `paradoxdb.synthetic`; the repo contains no `.DB` file |
+| The cipher of encrypted tables is only available in GPL code | Decryption is delegated to an optional external `Decryptor`; this library only decodes plain bytes |
+| The legacy engine must still open what we write | The writer copies an existing header (template) and only rewrites counters; new files are produced, nothing is modified in place |
+| Mixed code pages in one dataset (CP437 core, CP1252 later tables) | Code page per table, read from the header, never global |
+| Monetary amounts and 32-digit BCD | `Decimal` everywhere; `float` only as the on-disk representation |
+
+## 3. Architecture
+
+```
+paradoxdb/
+├── fields.py     FieldType, FieldDef, code pages, physical sizes
+├── numeric.py    order-preserving codecs: Paradox int, Paradox double, BCD
+├── values.py     CellValue(state, value, raw_bytes, reason); decode_value; encode_*
+├── header.py     TableHeader, parse_header, patch_counters (0x06, 0x0A-0x10, 0x49)
+├── blocks.py     block-chain walker (every record, anomalies) and block packer
+├── memo.py       MemoPointer, MemoFile (types 2 and 3), MemoWriter (type 2)
+├── table.py      open_table, ParadoxTable, Record, Decryptor protocol
+├── writer.py     write_table on a template, WriteRecord, legacy_sort_key
+├── index.py      DataBlock, read_data_blocks, build_index, verify_index
+├── profile.py    profile_table, export_csv, export_json
+├── cli.py        paradoxdb profile | export | verify-index
+└── synthetic.py  table factory used by tests and examples
+```
+
+Reading pipeline:
+
+```
+.DB bytes ──► parse_header ──► iter_blocks ──► decode_value per field ──► Record
+                 │                                   ▲
+                 └── code page, descriptors          └── MemoFile (.MB sibling, any case)
+```
+
+Writing pipeline:
+
+```
+template .DB header ──copy──► patch counters ──► pack_blocks(records) ──► new .DB
+template .MB first block ──► MemoWriter (one single-block entry per memo) ──► new .MB
+template .PX header ──► build_index(read_data_blocks(new .DB)) ──► new .PX
+```
+
+### Quick start
+
+```python
+from paradoxdb import open_table
+
+table = open_table("ASSETS.DB")  # finds assets.mb / ASSETS.MB too
+print(table.header.version_label, table.header.codec)
+
+for record in table.records():  # every record in every block
+    amount = record["Amount"]  # case-insensitive field lookup
+    if amount.is_ok:
+        total = amount.value  # Decimal, date, int, bool, str, bytes
+    else:
+        print(amount.state, amount.reason, amount.raw_bytes.hex())
+
+print(table.block_record_count(), table.declared_record_count, table.header_mismatch)
+```
+
+```python
+from paradoxdb import WriteRecord, write_table, verify_index, read_data_blocks
+
+records = [
+    WriteRecord(r.raw_bytes, {3: r["Note"].value.encode(table.codec)}) for r in table.records()
+]
+result = write_table("ASSETS.DB", "out/ASSETS.DB", records, sort=False)
+assert verify_index(result.px_path, read_data_blocks(result.db_path)) == []
+```
+
+```bash
+paradoxdb profile ./tables --output profile.json   # aggregates, SHA-256, mismatches
+paradoxdb export ./tables/ASSETS.DB --format csv   # value, state and reason per cell
+paradoxdb verify-index ./tables/ASSETS.DB          # exit 1 when the .PX is inconsistent
+```
+
+## 4. Decisions and the alternatives they replaced
+
+| Decision | Rejected alternative | Why |
+|---|---|---|
+| Own reader in pure Python | Bindings over the C library | GPL licence, one global encoding, skips undeclared records, no 64-bit guarantee on Linux |
+| Decryption delegated to an optional component | Re-implement the cipher | The only public implementation is GPL; encrypted tables are a small minority |
+| Explicit state per cell plus raw bytes | `None` / `0` when in doubt | The earlier approach turned garbage currency values and sentinel dates into `None`: silent loss at scale |
+| `Decimal` for doubles and BCD | `float` | Accounting amounts and 32-digit BCD; arithmetic parity with the legacy engine is the consumer's job |
+| Code page per table | Global `latin1` or `cp1252` | `latin1` accepts every byte but misreads `ñ` / `º` from CP437 tables; datasets mix code pages |
+| Header copied from a template | Build headers from scratch | Keeps version, descriptors, key and code page, including in empty tables, without modelling obscure header fields |
+| Always new files | Modify in place | The C library corrupted memory after ~50 in-place writes |
+| One single-block entry per memo | Sub-allocated blocks | Correctness first; the size cost is measured below and planned for v2 |
+| Source order by default, legacy order on request | Always re-sort | The legacy engine accepts the original order; the reproduced collation matched the real one in most but not all tables |
+| Whole file in memory | Block-by-block streaming | Tables of tens of MB; revisit if hundreds appear |
+
+Decisions that the specification left open (error-message language, how the
+`.PX` entry count is defined, how the leak guard matches words, and so on) are
+listed with their rationale in [docs/DECISIONES.md](https://github.com/arielgiamportone/paradox-db-py/blob/main/docs/DECISIONES.md).
+
+## 5. What was measured and how to reproduce it
+
+Everything below runs on synthetic data produced by the repository itself.
+
+```bash
+pip install -e ".[dev]"
+pytest                          # 100+ tests, including Hypothesis round-trip properties
+python examples/benchmark.py    # timings and .MB growth on a 50 000-row table
+```
+
+Results on a laptop-class container (Python 3.12):
+
+| Measurement | Value |
+|---|---|
+| Open and decode 50 000 mixed-type records | 1.3 s |
+| Write `.DB` + `.PX` for those records on a template | 0.09 s |
+| Verify the resulting two-level `.PX` | < 0.01 s |
+| `.MB` written for 5 000 memos of ~150 bytes each | 20 MiB for 0.7 MiB of payload (×27) |
+
+The test-suite covers every case of the original specification: headers with
+and without the 4.0+ extension, CP437 and CP1252 text, every field type with
+sign, null versus zero, unreadable BCD, records beyond the declared count,
+memos in the three storage forms, missing `.MB`, encrypted tables with and
+without a decryptor, incoherent headers, round-trips with memos and index,
+multi-level indexes, legacy collation (`NA, nz, Ñu, Oa, ob`), duplicate keys,
+empty tables, autoincrement, secondary indexes left untouched, the index
+verifier and the profile / CLI output.
+
+In the original project the same design was validated against about 120 real
+tables (roughly 225 000 rows) with zero byte or value differences versus the
+C library, and the verifier accepted 106 of 108 original indexes (the other two
+had counts corrupted by interrupted writes). Those tables cannot be published;
+the figures are given only as context.
+
+## 6. Known limits
+
+- **`.MB` growth.** Every memo gets at least one 4 KiB block. Sub-allocated
+  (type 3) blocks are read but never written. Planned for v2.
+- **Not yet opened in a real BDE.** Round-trips are validated with this
+  library's reader; opening the written files in the legacy engine is pending.
+- **Secondary indexes** (`.Xnn`, `.Ynn`, `.XGn`, `.YGn`) are detected and
+  reported, never regenerated.
+- **Encrypted tables are never written**, and decryption requires an external
+  component.
+- Index entry counts are limited to 32 767 per entry, BCD to 32 digits; text
+  that does not fit a field is an error, not a truncation.
+- Whole files are loaded in memory.
+
+## 7. How it was built
+
+Three-phase clean-room process. Phase 1 produced a specification of the format,
+behaviour and invariants from the original (private) code, without copying
+code, identifiers or data. Phase 2, this repository, was implemented in a
+separate session with access to that specification and to public documentation
+only, using an AI coding assistant as pair programmer; every decision not fixed
+by the specification is documented. Phase 3 is an independent review comparing
+this repository against the original before publication. The CI runs a leak
+guard (`tests/test_no_leaks.py`) over the tree and the git history, plus
+`gitleaks`.
+
+## 8. Attribution and licence
+
+Patterns developed during my work at Intervalor Data and published with permission. Independent clean-room implementation with synthetic data; it contains no code or data from the company or its clients.
+
+MIT licence. See [LICENSE](https://github.com/arielgiamportone/paradox-db-py/blob/main/LICENSE), [CHANGELOG.md](https://github.com/arielgiamportone/paradox-db-py/blob/main/CHANGELOG.md) and
+[CONTRIBUTING.md](https://github.com/arielgiamportone/paradox-db-py/blob/main/CONTRIBUTING.md).

paradoxdb-0.1.0/README.es.md

@@ -0,0 +1,200 @@
+# paradox-db-py
+
+[![CI](https://github.com/arielgiamportone/paradox-db-py/actions/workflows/ci.yml/badge.svg)](https://github.com/arielgiamportone/paradox-db-py/actions/workflows/ci.yml)
+![Python 3.11 | 3.12](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue)
+![Licencia MIT](https://img.shields.io/badge/license-MIT-green)
+
+**Lector y escritor en Python puro de tablas Paradox** (`.DB` datos, `.MB`
+memos y BLOB, `.PX` índice primario), versiones 3.0 a 7. Sin código nativo, sin
+dependencias copyleft, sin conversiones silenciosas: cada celda vuelve como
+`OK`, `NULL` o `INVALID` junto con sus bytes crudos.
+
+*English version: [README.md](https://github.com/arielgiamportone/paradox-db-py/blob/main/README.md).*
+
+> Patrones desarrollados durante mi trabajo en Intervalor Data y publicados con autorización. Implementación independiente (clean-room) con datos sintéticos; no contiene código ni datos de la empresa ni de sus clientes.
+
+---
+
+## 1. El problema
+
+Un sistema de gestión de activos fijos escrito en Delphi sobre el Borland
+Database Engine guardaba décadas de histórico en tablas Paradox. Modernizarlo
+exigía dos cosas a la vez:
+
+1. **Extraer** todos los registros sin pérdida. No «casi todos»: el motor
+   antiguo dejaba registros en los bloques de datos que la cabecera nunca
+   contó, y columnas enteras de importes en BCD que ya no se decodificaban.
+2. **Devolver tablas** a la aplicación antigua durante una transición larga,
+   para que el sistema viejo y el nuevo convivieran meses.
+
+El ecosistema Python solo ofrecía *bindings* sobre una librería en C (GPL) que
+en la práctica es de solo lectura, impone una codificación global de texto,
+se salta los registros que la cabecera no declara y corrompe su *heap* tras
+unas decenas de escrituras. Para un producto *on-premise* nada de eso servía.
+
+## 2. Restricciones
+
+| Restricción | Consecuencia en el diseño |
+|---|---|
+| Se distribuye *on-premise* dentro de un producto comercial | Python puro, licencia MIT, cero dependencias en tiempo de ejecución |
+| Las tablas reales contienen datos personales y patrimoniales de terceros | Todas las *fixtures* las genera `paradoxdb.synthetic`; el repo no contiene ningún `.DB` |
+| El cifrado solo está implementado en código GPL | El descifrado se delega a un `Decryptor` externo opcional; la librería solo decodifica bytes en claro |
+| El motor antiguo debe seguir abriendo lo que escribimos | El escritor copia una cabecera existente (plantilla) y solo reescribe contadores; produce ficheros nuevos, nunca modifica en sitio |
+| Páginas de códigos mezcladas en un mismo conjunto (núcleo CP437, tablas posteriores CP1252) | Codepage por tabla, leída de la cabecera, nunca global |
+| Importes contables y BCD de 32 dígitos | `Decimal` en todas partes; `float` solo como representación en disco |
+
+## 3. Arquitectura
+
+```
+paradoxdb/
+├── fields.py     FieldType, FieldDef, páginas de códigos, tamaños físicos
+├── numeric.py    codificaciones que preservan el orden: entero y doble Paradox, BCD
+├── values.py     CellValue(state, value, raw_bytes, reason); decode_value; encode_*
+├── header.py     TableHeader, parse_header, patch_counters (0x06, 0x0A-0x10, 0x49)
+├── blocks.py     recorrido de la cadena de bloques (todos los registros, anomalías) y empaquetado
+├── memo.py       MemoPointer, MemoFile (bloques de clase 2 y 3), MemoWriter (clase 2)
+├── table.py      open_table, ParadoxTable, Record, protocolo Decryptor
+├── writer.py     write_table sobre plantilla, WriteRecord, legacy_sort_key
+├── index.py      DataBlock, read_data_blocks, build_index, verify_index
+├── profile.py    profile_table, export_csv, export_json
+├── cli.py        paradoxdb profile | export | verify-index
+└── synthetic.py  fábrica de tablas usada por tests y ejemplos
+```
+
+Lectura:
+
+```
+bytes .DB ──► parse_header ──► iter_blocks ──► decode_value por campo ──► Record
+                 │                                   ▲
+                 └── codepage, descriptores          └── MemoFile (.MB hermano, cualquier mayúscula)
+```
+
+Escritura:
+
+```
+cabecera .DB plantilla ──copia──► parchear contadores ──► pack_blocks(registros) ──► .DB nuevo
+primer bloque del .MB plantilla ──► MemoWriter (una entrada de bloque único por memo) ──► .MB nuevo
+cabecera .PX plantilla ──► build_index(read_data_blocks(.DB nuevo)) ──► .PX nuevo
+```
+
+### Inicio rápido
+
+```python
+from paradoxdb import open_table
+
+table = open_table("ACTIVOS.DB")  # encuentra también activos.mb / ACTIVOS.MB
+print(table.header.version_label, table.header.codec)
+
+for record in table.records():  # todos los registros de todos los bloques
+    amount = record["Importe"]  # búsqueda de campo sin distinguir mayúsculas
+    if amount.is_ok:
+        total = amount.value  # Decimal, date, int, bool, str, bytes
+    else:
+        print(amount.state, amount.reason, amount.raw_bytes.hex())
+
+print(table.block_record_count(), table.declared_record_count, table.header_mismatch)
+```
+
+```python
+from paradoxdb import WriteRecord, write_table, verify_index, read_data_blocks
+
+records = [
+    WriteRecord(r.raw_bytes, {3: r["Nota"].value.encode(table.codec)}) for r in table.records()
+]
+result = write_table("ACTIVOS.DB", "salida/ACTIVOS.DB", records, sort=False)
+assert verify_index(result.px_path, read_data_blocks(result.db_path)) == []
+```
+
+```bash
+paradoxdb profile ./tablas --output perfil.json    # agregados, SHA-256, descuadres
+paradoxdb export ./tablas/ACTIVOS.DB --format csv  # valor, estado y motivo por celda
+paradoxdb verify-index ./tablas/ACTIVOS.DB         # salida 1 si el .PX es incoherente
+```
+
+## 4. Decisiones y alternativas descartadas
+
+| Decisión | Alternativa descartada | Motivo |
+|---|---|---|
+| Lector propio en Python puro | *Bindings* de la librería C | Licencia GPL, codificación global, salta registros no declarados, sin garantía de 64 bits en Linux |
+| Descifrado delegado a un componente opcional | Reimplementar el cifrado | La única implementación pública es GPL; las tablas cifradas son una minoría |
+| Estado explícito por celda más bytes crudos | `None` / `0` ante la duda | La versión anterior convertía importes basura y fechas centinela en `None`: pérdida silenciosa a gran escala |
+| `Decimal` para dobles y BCD | `float` | Importes contables y BCD de 32 dígitos; la paridad aritmética con el legado la hace el consumidor |
+| Codepage por tabla | `latin1` o `cp1252` global | `latin1` acepta cualquier byte pero lee mal `ñ` / `º` de tablas CP437; los conjuntos mezclan páginas |
+| Cabecera copiada de una plantilla | Construir cabeceras desde cero | Conserva versión, descriptores, clave y codepage, también en tablas vacías, sin modelar campos oscuros |
+| Siempre ficheros nuevos | Modificar en sitio | La librería C corrompía memoria tras ~50 escrituras en sitio |
+| Una entrada de bloque único por memo | Bloques subasignados | Correctitud primero; el coste en tamaño se mide abajo y se planifica para v2 |
+| Orden de origen por defecto, orden legado bajo demanda | Reordenar siempre | El motor antiguo acepta el orden original; la colación reproducida coincidió con la real en la mayoría de tablas, no en todas |
+| Fichero completo en memoria | Lectura por bloques | Tablas de decenas de MB; revisar si aparecen cientos |
+
+Las decisiones que la especificación dejaba abiertas (idioma de los mensajes,
+definición del recuento de entradas del `.PX`, cómo compara palabras el test de
+fugas, etc.) están en [docs/DECISIONES.md](https://github.com/arielgiamportone/paradox-db-py/blob/main/docs/DECISIONES.md) con su motivo.
+
+## 5. Qué se midió y cómo reproducirlo
+
+Todo lo siguiente se ejecuta sobre datos sintéticos generados por el propio
+repositorio.
+
+```bash
+pip install -e ".[dev]"
+pytest                          # más de 100 tests, con propiedades de ida y vuelta (Hypothesis)
+python examples/benchmark.py    # tiempos y crecimiento del .MB con una tabla de 50 000 filas
+```
+
+Resultados en un contenedor de clase portátil (Python 3.12):
+
+| Medición | Valor |
+|---|---|
+| Abrir y decodificar 50 000 registros de varios campos | 1,3 s |
+| Escribir `.DB` + `.PX` de esos registros sobre plantilla | 0,09 s |
+| Verificar el `.PX` resultante de dos niveles | < 0,01 s |
+| `.MB` escrito para 5 000 memos de ~150 bytes | 20 MiB para 0,7 MiB de contenido (×27) |
+
+La batería de tests cubre todos los casos de la especificación original:
+cabeceras con y sin extensión 4.0+, texto en CP437 y CP1252, cada clase de
+campo con signo, nulo frente a cero, BCD ilegible, registros más allá del
+recuento declarado, memos en sus tres formas, `.MB` ausente, tablas cifradas
+con y sin descifrador, cabeceras incoherentes, ida y vuelta con memos e
+índice, índices de varios niveles, colación legada (`NA, nz, Ñu, Oa, ob`),
+claves repetidas, tablas vacías, autoincremento, índices secundarios sin
+tocar, el verificador de índices y la salida del perfil y la CLI.
+
+En el proyecto original el mismo diseño se validó contra unas 120 tablas
+reales (unas 225 000 filas) con cero diferencias de bytes o de valor frente a
+la librería C, y el verificador aceptó 106 de 108 índices originales (los otros
+dos tenían recuentos corrompidos por escrituras interrumpidas). Esas tablas no
+pueden publicarse; las cifras se dan solo como contexto.
+
+## 6. Límites conocidos
+
+- **Crecimiento del `.MB`.** Cada memo ocupa al menos un bloque de 4 KiB. Los
+  bloques subasignados (clase 3) se leen pero no se escriben. Previsto para v2.
+- **Aún no abierto en un BDE real.** Las idas y vueltas se validan con el
+  propio lector; abrir los ficheros escritos en el motor antiguo está pendiente.
+- **Índices secundarios** (`.Xnn`, `.Ynn`, `.XGn`, `.YGn`): se detectan e
+  informan, nunca se regeneran.
+- **Las tablas cifradas no se escriben**, y descifrarlas exige un componente
+  externo.
+- Recuento de índice ≤ 32 767 por entrada, BCD ≤ 32 dígitos; el texto que no
+  cabe en un campo es un error, no un truncado.
+- Los ficheros se cargan íntegros en memoria.
+
+## 7. Cómo se construyó
+
+Proceso *clean-room* en tres fases. La fase 1 produjo una especificación del
+formato, el comportamiento y los invariantes a partir del código original
+(privado), sin copiar código, identificadores ni datos. La fase 2, este
+repositorio, se implementó en una sesión separada con acceso solo a esa
+especificación y a documentación pública, usando un asistente de programación
+con IA como pareja de programación; cada decisión no fijada por la
+especificación está documentada. La fase 3 es una revisión independiente que
+compara este repositorio con el original antes de publicarlo. La CI ejecuta
+un test de fugas (`tests/test_no_leaks.py`) sobre el árbol y el historial de
+git, además de `gitleaks`.
+
+## 8. Atribución y licencia
+
+Patrones desarrollados durante mi trabajo en Intervalor Data y publicados con autorización. Implementación independiente (clean-room) con datos sintéticos; no contiene código ni datos de la empresa ni de sus clientes.
+
+Licencia MIT. Véanse [LICENSE](https://github.com/arielgiamportone/paradox-db-py/blob/main/LICENSE), [CHANGELOG.md](https://github.com/arielgiamportone/paradox-db-py/blob/main/CHANGELOG.md) y
+[CONTRIBUTING.md](https://github.com/arielgiamportone/paradox-db-py/blob/main/CONTRIBUTING.md).