docs / Perfil mini-domain/1

Perfil de dominio generado: mini-domain/1#

Este documento especifica el perfil JSON generado por la versión 1.1.0 del software. No sustituye la SPEC 1.0 del núcleo. Las familias clásicas y sus pruebas mantienen sintaxis y parsers propios. El perfil generado se procesa con el parser de mini build o con minifmt.domain.

Contrato#

contract.json contiene profile: "mini-domain/1", prefijo, versión 1, esquema recursivo, record_path (lista de claves de objeto o null) y schema_id. La huella son los primeros doce caracteres hexadecimales SHA-256 del JSON compacto UTF-8 con, en este orden, profile, prefix, version, schema, record_path. El orden de campos importa; las cantidades informativas de muestras no cambian la identidad. Usa contratos de una construcción confiable: la huella es un control de compatibilidad, no autenticación criptográfica.

Tipos: object, array, string, integer, number, boolean y json abierto. Los objetos tienen campos ordenados name, optional, schema; las listas, items; nullable permite null. Las claves desconocidas de objetos son errores. Un nodo JSON abierto conserva deliberadamente cualquier JSON, incluidas claves nuevas.

La inferencia combina todos los documentos completos. Los miembros ausentes se vuelven opcionales; null observado permite null. Campos sólo null, elementos de listas vacías y tipos heterogéneos quedan como JSON abierto. Mezclas numéricas amplían integer a number. Valores constantes observados nunca se convierten en valores predeterminados permanentes del dominio.

Documento transmitido#

UTF-8, líneas físicas separadas por LF, con un LF final opcional:

phone|v=1|n=2|h=<schema_id>
<celdas del registro 1>
<celdas del registro 2>

Cabecera: prefijo y v, n, h obligatorios; m, d y e opcionales. Claves desconocidas o duplicadas producen error. n coincide exactamente con los registros. Una huella distinta falla: no se intenta adivinar otro esquema.

Las filas usan celdas separadas por |, sin repetir una etiqueta por registro. Objetos obligatorios no-nullables se aplanan recursivamente en orden del esquema; objetos vacíos obligatorios se reconstruyen desde éste. Objetos opcionales o nullables conservan una celda posicional. Registros escalares, listas, JSON abierto u objetos nullables se representan en una celda completa. Una fila sin columnas transmitidas se escribe -.

Escape de cada celda: \\ representa barra inversa; \|, separador; \n, salto de línea; \r, retorno. Otros escapes son inválidos. Los espacios son datos.

Valores de celda#

? significa miembro opcional ausente; ~, null. No equivalen a cadena vacía, cero o false. Las cadenas normalmente no llevan comillas. Cadena vacía, ? o ~ literales, y cadenas que empiezan por comillas se codifican como cadenas JSON; después se aplica el escape exterior. Se rechazan números no finitos y claves JSON duplicadas. Los valores numéricos no se convierten a otro tipo.

Objetos anidados son listas JSON posicionales en orden del esquema; {} marca un miembro opcional ausente dentro de esas listas. Un nodo JSON abierto envuelve su valor no-null como [valor], evitando confundir un objeto vacío real con ausencia. Las listas transforman sus elementos recursivamente; null sigue siendo null. Primero se codifica JSON y después se escapa la celda exterior.

Si la colección está dentro de un objeto, m transmite todo el envoltorio como JSON posicional con la colección sustituida por []. Los metadatos viajan en el documento, no se recuperan de las muestras. Listas raíz no llevan m; otras raíces tienen exactamente un registro y tampoco llevan m.

Optimización explícita por documento#

d contiene JSON [[indiceColumna, celdaCodificada], ...], índices desde cero. Esas columnas se omiten de todas las filas y se restauran desde la cabecera. Se calculan con el documento actual y se validan contra el mismo esquema.

e contiene JSON [[indiceColumna, [celdaCadenaCodificada, ...]], ...]. Cada columna con diccionario sigue presente en la fila, mediante un índice decimal desde cero. Sólo se permite para columnas string. Los diccionarios completos se transmiten: no hay vocabulario oculto aprendido de las muestras. Una columna no puede estar en d y e a la vez. Índices inválidos o duplicados producen error. El JSON de cabecera recibe el mismo escape exterior.

El codificador aplica estas opciones cuando su estimación de bytes es favorable. encode(valor, contrato, shared=False) desactiva d; encode(valor, contrato, dictionaries=False) desactiva e. Pasa ambos argumentos para desactivar las dos optimizaciones. Ahorrar bytes no garantiza ahorrar tokens con cualquier tokenizador.

Validación y evolución#

Se comprueban identidad, escapes, columnas, tipos, nullabilidad, campos requeridos, envoltorio y cantidad de registros. Los errores exponen código estable D_*, línea física y ruta JSON. diagnose distingue líneas recuperables e inválidas; repair corrige envoltorios de transporte. apply_replacements incorpora líneas corregidas externamente y valida todo el documento.

No se ignoran campos nuevos silenciosamente. Reconstruye en otra carpeta con ejemplos representativos y distribuye prompt, contrato y parser juntos. Validar estructura no demuestra veracidad del modelo ni cumplimiento de reglas del negocio.

Generated domain profile: mini-domain/1#

Español · Integration guide

This document specifies the generated JSON-domain profile shipped with software release 1.1.0. It does not replace core SPEC 1.0. Core families and their conformance corpus retain their established syntax and parsers. Generated domain documents use the runtime bundled by mini build or minifmt.domain.

Contract#

contract.json contains profile: "mini-domain/1", a prefix, version 1, the recursive schema, selected record_path (array of object keys or null), and schema_id. The fingerprint is the first twelve hexadecimal SHA-256 characters of compact UTF-8 JSON containing, in order, profile, prefix, version, schema, record_path. Field order is significant. Informational sample counts do not change the schema identity. Load contracts from a trusted build: the short fingerprint is a compatibility guard, not cryptographic authentication.

Types are object, array, string, integer, number, boolean and open json. Objects contain ordered fields with name, optional, schema; arrays have items; nullable allows null. Unknown object keys are rejected. An open JSON node intentionally preserves arbitrary JSON, including new keys.

Inference combines every supplied complete document. Missing members become optional; observed nulls allow null. Null-only, empty-list item and heterogeneous types remain open JSON. Numeric mixtures widen integer to number. Observed constant values are never installed as permanent domain defaults.

Wire document#

UTF-8, LF-separated physical lines, with one optional final LF:

phone|v=1|n=2|h=<schema_id>
<record 1 cells>
<record 2 cells>

The header contains the prefix, required v, n, h, optional wrapper m, optional shared-column table d and optional string-dictionary table e. Unknown or duplicate header names are errors. n must match the exact record count. Wrong fingerprints fail instead of attempting another schema.

Rows use |-separated cells, without a repeated record tag. Required non-nullable objects are recursively flattened in schema order; empty required objects are reconstructed from the schema. Optional/nullable objects retain a positional cell. For scalar, array, open-JSON or nullable-object records, one cell represents the complete record. A row with zero transmitted columns is -.

Field escaping applies to every header and row cell: \\ is backslash, \| a pipe, \n a newline and \r a carriage return. Other escapes are invalid. Spaces are data, not optional formatting.

Cell values#

? means an absent optional member; ~ means null. They are distinct from an empty string, zero and false. Strings normally have no quotes. Empty strings, literal ? or ~, and strings beginning with a quote use a JSON string instead. Then field escaping is applied. Non-finite numbers and duplicate JSON object keys are rejected. Integers and numbers retain their JSON values without coercion.

Nested objects are positional JSON arrays in field order. An absent optional member inside such an array is {}. An open JSON node wraps its non-null value in [value], so an actual empty object cannot collide with the absence marker. Nested arrays transform items recursively; null remains null. Apply JSON encoding first, then the outer field escaping.

For a collection nested within a root object, m is the positional JSON encoding of the complete wrapper with the selected collection replaced by []. Metadata is transmitted, not recovered from training samples. Root arrays have no m; other roots contain exactly one record and no m.

Explicit per-document optimization#

d is JSON [[columnIndex, encodedCell], ...], with zero-based column indexes. Those columns are omitted from every row and restored from the header. Values are computed from the current document and validated with the same schema.

e is JSON [[columnIndex, [encodedStringCell, ...]], ...]. A dictionary column stays present in each row but contains a zero-based decimal dictionary index. Only string columns qualify. Dictionaries are transmitted in full; they never reference a hidden training vocabulary. A column cannot appear in both d and e. Invalid/duplicate indexes are errors. Header JSON receives the same field escaping as other cells.

The encoder uses these options only when its byte-cost estimate is favorable. encode(value, contract, shared=False) disables d; encode(value, contract, dictionaries=False) disables e. Pass both flags to disable both optimizations. Token savings still depend on the tokenizer; byte savings are not a universal token guarantee.

Validation and evolution#

Decode checks contract identity, escapes, column counts, field types, nullability, required members, wrapper shape and record count. Errors expose stable D_* codes, physical line and JSON path. diagnose reports recoverable and rejected lines; repair only fixes explicit transport wrappers. apply_replacements merges externally corrected invalid lines and validates the complete document.

New fields are not silently ignored. Rebuild with representative examples in a new directory and distribute its prompt, contract and parser together. Structural validation does not prove a model's factual accuracy or business-rule compliance.