1. Preparación del Entorno e Instalación

El ecosistema PON-DB se distribuye en forma de binarios nativos precompilados altamente optimizados que no requieren de un motor de ejecución ni de dependencias externas pesadas.

1. Dar permisos de ejecución a los binarios descargados:
   Abra su terminal en la carpeta donde descargó los archivos y ejecute el siguiente comando para autorizar su ejecución en el sistema:

   chmod +x pon-db-engine pon-reader pon-gateway

2. Verificar la arquitectura (Opcional):
   Asegúrese de que se encuentra en un entorno compatible ejecutando:

   uname -m

   (Debe retornar x86_64)
3. Listo, es todo ya puede comenzar a usar PON-DB Engine.

2. Ingesta de Datos (Creación del archivo .pon , position object notation)

El proceso de ingesta toma un archivo estructurado en JSON o JSONL plano y lo convierte en un binario cifrado indexado y portable de manera síncrona, emitiendo una llave criptográfica única por cada base de datos.

Para generar su archivo .pon, utilice pon-db-engine especificando el archivo de origen y el único campo que desea indexar para búsquedas instantáneas:

./pon-db-engine datos.json --index=device_id

Resultados de la operación:

• datos.pon: Su base de datos empaquetada, cifrada con AES-256-GCM y optimizada físicamente.
• masterkey_????????_date.bin: La llave maestra requerida para descifrar la información en memoria. Consérvela en un lugar seguro.
• Reporte de Eficiencia (datos.log): Un archivo de registro que documenta el tamaño inicial, final y el rate de aumento o reducción de acuerdo a la entropía del dataset.
• En la actual versión el software no guarda en el .log que campo a indexado, se estudia la opción de incluirlo en el .log en la próxima version por lo que debe documentar esto con su wrapper favorito.

3. Consultas Básicas y Avanzadas (pon-db-engine)

Una vez que dispone de su archivo .pon y su llave maestra .bin, puede explorar la información directamente desde la consola utilizando expresiones estructuradas.

A. Consulta Simple

Búsqueda directa sobre el campo indexado. Devuelve de manera instantánea todos los registros asociados al valor clave buscado:

./pon-db-engine datos.json.pon query "device_id=esp32-1000" --key=masterkey_XYZ123.bin

B. Consulta Múltiple Directa (IN)

Permite buscar múltiples valores específicos sobre el campo indexado en una sola lectura optimizada:

./pon-db-engine datos.json.pon query "device_id IN [esp32-1000,esp32-4912]" --key=masterkey_XYZ123.bin

C. Consulta Mixta con Filtrado Secuencial (AND)

Filtra los resultados del campo indexado validando además condiciones secundarias sobre campos no indexados en un único paso de flujo continuo en RAM:

./pon-db-engine datos.json.pon query "device_id=esp32-1000 AND event=battery_status" --key=masterkey_XYZ123.bin

D. Consulta de Exclusión Criptográfica (NOT)

Extrae los datos que corresponden al índice principal, excluyendo explícitamente aquellos que cumplan la regla secundaria:

./pon-db-engine datos.json.pon query "device_id=esp32-1000 AND NOT event=error_report" --key=masterkey_XYZ123.bin

4. Uso de Lector Ligero Offline (pon-reader)

pon-reader es una utilidad de consulta independiente que cumple estrictamente la filosofía "el usuario sea el dueño legítimo de sus datos perpetuamente" (No-Vendor Lock). Sirve exclusivamente para leer archivos .pon de forma local usando la llave de descifrado, mostrando los registros en un formato estructurado o crudo según se requiera, usted puede crear archivos .pon y usarlos como formato seguro de intercambio de información, enviarlos a sus clientes con la clave respectiva y una copia de PON-Reader mediante un canal seguro o desplegar bases de datos en infraestructura de terceros para consultas seguras de alta velocidad.

Para ejecutar una consulta rápida sobre el campo indexado en modo estructurado legible:

./pon-reader datos.json.pon query "device_id=esp32-1000" --key=masterkey_XYZ123.bin --nomsg

(Si indexa el json en modo pretty lo entregará igual en la salida, si desea compactarlo a modo jsonl en la salida use --nomsg)

5. Uso de la Puerta de Enlace Criptográfica (pon-gateway)

pon-gateway actúa como una interfaz de red segura perimetral para exponer los datos en entornos de red bajo una arquitectura de "Cero Confianza" (Zero-Trust).

• Operación de solo lectura (read-only): Por diseño rígido de aislamiento de hardware, el gateway tiene estrictamente prohibido realizar cualquier tipo de escritura o alteración en los archivos físicos.

Para iniciar el servicio del gateway en su servidor o terminal, configure previamente los accesos en su gateway_config.json y ejecute:

./pon-gateway

1. Arquitectura de Ejecución

Por diseño estricto de aislamiento y seguridad, el binario se ejecuta exclusivamente desde la interfaz de línea de comandos (CLI) sin argumentos ni parámetros dinámicos . Todos los parámetros operativos se leen de forma hermética desde el archivo de configuración en caliente .

Para iniciar el servicio en su servidor o terminal, ejecute:

./pon-gateway

Al arrancar, el motor busca obligatoriamente el archivo estructurado bajo el nombre estándar gateway_config.json en su directorio raíz de ejecución para mapear las instancias binarias criptográficas .

2. Estructura de Configuración (gateway_config.json)

El Gateway consume un mapeo declarativo que empareja alias de servicio, rutas físicas del volumen indexado, llaves maestras e infraestructura básica de tokens estáticos con cuotas de consumo :

{
  "instances": {
    "test_1": {
      "path": "./nombredeldataset1.json.pon",
      "key_path": "./masterkey_HASH_YYYY-MM-DD.bin"
    },
    "test_2": {
      "path": "./nombredeldataset2.json.pon",
      "key_path": "./masterkey_HASH_YYYY-MM-DD.bin"
    }
  },
  "auth": {
    "keys": {
      "token123": {
        "status": 1,
        "start_date": "2026-04-20T00:00:00Z",
        "end_date": "2027-04-20T00:00:00Z",
        "quota_total": 100000000,
        "current_usage": 0
      }
    }
  }
}

3. Especificación de Campos Técnicos

Bloque instances

Define las bases de datos montadas e identificadas unívocamente por el gateway . Cada nodo mapea:

• path: Ubicación exacta del archivo binario .pon en el volumen .
• key_path: Ruta al archivo binario que contiene la llave AES-256-GCM maestra respectiva .

Bloque auth

Capa de contención y autorización estática offline sin llamadas ni dependencias externas :

• status: Control de acceso directo ( 1 : Activo / Autorizado, 0 : Revocado) .
• start_date / end_date: Ventana temporal estricta en formato ISO-8601 conectada al contador offline del motor para evitar la manipulación del reloj del sistema .
• quota_total / current_usage: Techo del volumen de lecturas acumuladas o peticiones permitidas antes del bloqueo automático del token .

4. Endpoints y Consumo del API

El gateway es de solo lectura (read-only) y expone exclusivamente rutas de resolución atómica en base a las instancias activas configuradas . Por defecto, utiliza el puerto 50005 para evitar colisiones con otros servicios del sistema .

A. Consulta de Registros

Devuelve el payload descifrado resolviendo el offset físico de manera instantánea .

GET /api/v1/<instance_name>/query?key=<valor_buscado>

Authorization: Bearer token123

Ejemplo de Consulta Real usando cURL:

curl -H "Authorization: Bearer token123" "http://localhost:50005/api/v1/test_1/query?key=999999"

6. Recomendaciones Generales y Buenas Prácticas

Para asegurar que opere el ecosistema PON-DB con la máxima eficiencia, estabilidad y garantizando la seguridad criptográfica Zero-Trust, siga estas recomendaciones del autor:

A. Gestión de Llaves Maestras (.bin)

• Almacenamiento Aislado: La llave maestra masterkey_????_date.bin es el único medio para descifrar los datos de su respectivo archivo .pon. Si se pierde, los datos serán permanentemente inaccesibles, el proveedor del software no podrá ayudarlo a recuperar una clave si la pierde. No la almacene nunca en el mismo directorio público o servidor donde expone el archivo binario.
• Políticas de Transmisión: No envíe llaves de descifrado y/o archivos .pon a través de los mismos canales de comunicación.

B. Estrategia de Indexación Eficiente

• Selección del Campo Único: Dado que la versión para lectores permite indexar un solo campo por archivo, elija siempre la variable con mayor entropía o el identificador que use con más frecuencia en sus criterios de búsqueda iniciales (por ejemplo, device_id o id), esto que podría considerarse una limitación en la práctica si usted sigue el contenido del libro lo convertirá rápidamente en una ventaja.
• Consultas con operadores: Recuerde que las consultas que utilicen operadores combinados (AND, NOT, IN) obtendrán un rendimiento óptimo de velocidad microsegundo (O(1)) siempre y cuando la primera condición apunte directamente al campo que fue indexado durante la ingesta, en próximas actualizaciones se incluirá OR, XOR y NAND, además de indexación multiple.

C. Operación en Entornos de Producción

• Seguridad Perimetral con PON-Gateway: Para aplicaciones expuestas a la red, delegue siempre las consultas en pon-gateway. Este componente trabaja estrictamente en modo de solo lectura y bloquea cualquier intento de inyección en la línea de comandos, blindando el almacenamiento local contra modificaciones no autorizadas.
• Sobre los archivos .pon y la indexación:
  • Los archivos .pon se genera realizando una copia del archivo json o jsonl indexado, usted puede procesar por ejemplo .csv hacia .jsonl para indexarlo luego a .pon.
  • La versión otorgada con el libro solo puede procesar archivos json o jsonl de hasta 1 millón de registros sin importa el tamaño inicial del archivo.
  • El motor solo puede indexar un campo de primer nivel que puede elegir, se sugiere que sea de alta entropía.
• Licencia Permanente y Autonomía: Recuerde que la lectura y consulta a través de pon-reader y el motor es ilimitada y perpetua para la versión que recibe al comprar el libro. Una vez generado su archivo .pon, podrá consultarlo para siempre que lo desee, sus datos son suyos.

Es importante destacar que el software proveído para la reproducción de las pruebas mencionadas en el libro podría contener errores y/o limitaciones que el usuario puede reportar a info@pon-db.com, de manera tal que se consideren corregir en las actualizaciones.