# 1.0.0-beta.21 JSON Document Scalar Parsing Foundation

## Scope

`1.0.0-beta.21` is a standard-library and compiler-gate slice. It adds
source-authored `std.json` helpers for scalar JSON documents while keeping
source-language syntax, runtime C, compiler-known runtime names, and ABI/layout
policy unchanged.

The release adds:

- `parse_string_document_result ((document string)) -> (result string i32)`
- `parse_bool_document_result ((document string)) -> (result bool i32)`
- `parse_i32_document_result ((document string)) -> (result i32 i32)`
- `parse_u32_document_result ((document string)) -> (result u32 i32)`
- `parse_i64_document_result ((document string)) -> (result i64 i32)`
- `parse_u64_document_result ((document string)) -> (result u64 i32)`
- `parse_f64_document_result ((document string)) -> (result f64 i32)`
- `parse_null_document_result ((document string)) -> (result bool i32)`

## Contract

Each helper trims ASCII whitespace around the whole input document with
`std.string.trim_ascii`, then delegates to the already released exact
value-token parser for that scalar family.

Leading and trailing ASCII whitespace around one scalar document is accepted.
Trailing non-whitespace remains an ordinary parse failure and returns `err 1`
through the underlying exact parser.

## Non-Scope

This scope does not add:

- compiler-known `std.json.*_document_result` runtime names
- private `__glagol_json_*document*` runtime symbols
- runtime C helper implementations
- source-language syntax
- object or array parsing
- recursive `JsonValue`
- tokenizer/parser objects
- maps, sets, executable generics, or generic collections
- streaming parsers or encoders
- Unicode escape decoding beyond the existing string-token helper
- embedded NUL policy
- stable JSON APIs
- stable ABI/layout
- stable standard-library compatibility
- performance claims

## Acceptance Criteria

- `lib/std/json.slo` exports all eight document scalar helpers.
- Explicit `std.json` import examples exercise trimmed whitespace success,
  no-whitespace success, and trailing non-whitespace failure.
- Local `std-layout-local-json` examples mirror the public helper surface with
  an explicit local `string` dependency for `trim_ascii`.
- Focused compiler coverage verifies the helpers are source-authored and that
  direct compiler-known runtime calls for the new names remain unsupported.
- `scripts/release-gate.sh` runs the focused beta21 test.
- Generated standard-library API documentation includes the new signatures.

## Gates

```bash
cargo fmt --check
cargo test --test standard_json_document_scalar_parsing_beta21
cargo test --test standard_json_source_facade_alpha
cargo test --test promotion_gate
cargo test
./scripts/release-gate.sh
```
