JSON document sources
=====================

JSON document capture is available in the development source. The published
``0.1.0.dev0`` package predates this functionality.

Choose ``object`` framing for one flat JSON object, or ``array`` framing for
an array of flat objects. The choice is explicit and belongs to the schema
identity. An empty array is a valid zero-record dataset. A wrong top-level
shape, blank file, byte-order mark, duplicate or unknown key, nested value or
malformed document fails explicitly. This subset does not support arbitrary
nested JSON documents.

Configure the source, framing, fields and resource limits as shown in
:doc:`../development/format-sources`. Supported fields are text, boolean,
signed or unsigned 64-bit integer and finite decimal. Each has a stable field
ID and explicit presence and null policies. A missing optional field differs
from an explicitly present null. Type mismatches are rejected; values are not
silently coerced.

The complete document is held in memory under the configured document-byte
bound. Source bytes, field sizes, numeric tokens, decimal exponent, record
count and batch sizes also have explicit limits. Supply the full lowercase
SHA-256 of the exact source bytes as the source version. Once verified, a
snapshot can be reopened and compared without the source file. Failed reads
discard provisional records and report an unavailable observation.

Strict typed representation is the default; ``--profile logical-v1`` opts in to
logical equivalence. JSON whitespace, key order and escape spelling are syntax
and are not preserved as raw-byte identity. Captured counts describe records
observed during verification; source lineage is unknown without supporting
evidence. Remote object storage is separate work.