feat(reflect): generic value tree + Reflect.serialize/apply + JSON bridge (#44)

A self-describing Value node (null/int/fixed/bool/str/list/object) with
constructors, builders (Value.add/put) and accessors (get/at/count/kind/
as_int/as_str/…). Reflect.serialize(entity) walks an entity's whole component
set into a value tree — one member per component, each a sub-object of its
fields — and Reflect.apply(entity, value) writes one back; a fixed field
becomes a fixed node, everything else an int node, so the round-trip is
bit-exact, with the model id under "@kind". Json.encode/parse bridge the tree
to and from compact, stable, diffable text, with fixed written as an exact
terminating decimal that parses back bit-for-bit (verified across the raw
Q16.16 range). Together: a one-call, bit-exact save/load for entities.

Written in Ludic and spliced on demand (runtime/native/value.ludic +
reflect_io.ludic, like Query/Light), so a program that doesn't touch
Value.*/Json.*/Reflect.serialize compiles byte-identically and the C-free
bootstrap fixpoint holds (verified). The general tagged-union/any language type
stays tracked in #1; this ships the concrete value tree the serializer needs.

Adds 21 namespace-method docs pages + Value/Json sections,
examples/library/serialize.ludic, and a regression case. Whole CI set green:
x test 72/72, x test-tools 30/30, check-impl/vocabulary/docs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/language/json/_section.md

@@ -0,0 +1,7 @@
+---
+id: json
+title: Json
+order: 36
+---
+
+The text bridge over the <a href="value"><code>Value</code></a> tree: <a href="json-encode"><code>Json.encode</code></a> turns a value tree into compact, stable JSON text and <a href="json-parse"><code>Json.parse</code></a> reads it back. Together with <a href="reflect-serialize"><code>Reflect.serialize</code></a>/<a href="reflect-apply"><code>Reflect.apply</code></a> this is a one-call, bit-exact save/load for entities, and a diffable on-disk format for tooling. Determinism holds: the same tree always encodes to the same bytes.

docs/language/json/json-encode.md

@@ -0,0 +1,14 @@
+---
+id: json-encode
+name: Json.encode
+category: json
+kind: namespace-method
+tokens: Json.encode
+sig: Json.encode(value) -> string
+tip: Serialize a value tree to compact JSON text.
+order: 1
+ns: Json
+member: encode
+---
+
+Walks a value tree and returns compact JSON text. <code>int</code> nodes become integers, <code>fixed</code> nodes an exact decimal, <code>bool</code> <code>true</code>/<code>false</code>, <code>str</code> a quoted (escaped) string, and lists/objects the usual <code>[…]</code>/<code>{…}</code> — object members keep insertion order, so the output is stable and diffable. The inverse is <a href="json-parse"><code>Json.parse</code></a>; together with <a href="reflect-serialize"><code>Reflect.serialize</code></a> this is a one-call save.

docs/language/json/json-parse.md

@@ -0,0 +1,14 @@
+---
+id: json-parse
+name: Json.parse
+category: json
+kind: namespace-method
+tokens: Json.parse
+sig: Json.parse(text: string) -> value
+tip: Parse JSON text into a value tree.
+order: 2
+ns: Json
+member: parse
+---
+
+Parses JSON <code>text</code> into a value tree — the inverse of <a href="json-encode"><code>Json.encode</code></a>. Numbers with a decimal point become <code>fixed</code> nodes (recovered bit-for-bit from a value written by <code>Json.encode</code>), whole numbers <code>int</code> nodes. It is a lean, best-effort reader for trusted saves, not a validating parser; feed a parsed object to <a href="reflect-apply"><code>Reflect.apply</code></a> to load it into an entity.

docs/language/reflect/reflect-apply.md

@@ -0,0 +1,14 @@
+---
+id: reflect-apply
+name: Reflect.apply
+category: reflect
+kind: namespace-method
+tokens: Reflect.apply
+sig: Reflect.apply(entity, value) -> int
+tip: Write a value tree's fields back into an entity.
+order: 14
+ns: Reflect
+member: apply
+---
+
+The inverse of <a href="reflect-serialize"><code>Reflect.serialize</code></a>: writes the fields of a value-tree <code>value</code> back into a live <code>entity</code>, and returns how many were set. Only components the entity already has and fields the schema knows are applied; reserved <code>"@"</code>-keys (like <code>"@kind"</code>) and unknown names are skipped, so a partial or older save loads cleanly. Feed it the output of <a href="json-parse"><code>Json.parse</code></a> to load a save.

docs/language/reflect/reflect-serialize.md

@@ -0,0 +1,14 @@
+---
+id: reflect-serialize
+name: Reflect.serialize
+category: reflect
+kind: namespace-method
+tokens: Reflect.serialize
+sig: Reflect.serialize(entity) -> value
+tip: Walk an entity's components into a value tree.
+order: 13
+ns: Reflect
+member: serialize
+---
+
+Walks every component the <code>entity</code> carries and every field of each into a generic <a href="value-object"><code>object</code></a> value tree: one member per component, each a sub-object of its fields. A <code>fixed</code> field becomes a <a href="value-fixed"><code>fixed</code></a> node, everything else an <a href="value-int"><code>int</code></a> node, so a <code>serialize</code> → <a href="reflect-apply"><code>apply</code></a> round-trip is bit-exact; the model id rides along under the reserved <code>"@kind"</code> key. Pair it with <a href="json-encode"><code>Json.encode</code></a> for a one-call save. It names no component or field, so it works over any schema — the pattern auto-save and debug inspectors use.

docs/language/value/_section.md

@@ -0,0 +1,7 @@
+---
+id: value
+title: Value
+order: 35
+---
+
+A generic, self-describing value tree — the node type reflection serializes into and JSON round-trips through. A node is one of null, <code>int</code>, <code>fixed</code>, <code>bool</code>, <code>str</code>, <code>list</code>, or <code>object</code> (see <a href="value-kind"><code>Value.kind</code></a>). Build one with the constructors (<a href="value-int"><code>Value.int</code></a>, <a href="value-object"><code>Value.object</code></a>, …) and the builders <a href="value-add"><code>Value.add</code></a>/<a href="value-put"><code>Value.put</code></a>; read it with <a href="value-get"><code>Value.get</code></a>/<a href="value-at"><code>Value.at</code></a>/<a href="value-count"><code>Value.count</code></a> and the <code>as_*</code> accessors. Related: <a href="json"><code>Json</code></a>, <a href="reflect"><code>Reflect</code></a>.

docs/language/value/value-add.md

@@ -0,0 +1,14 @@
+---
+id: value-add
+name: Value.add
+category: value
+kind: namespace-method
+tokens: Value.add
+sig: Value.add(list, item) -> value
+tip: Append an item to a list; returns the list.
+order: 8
+ns: Value
+member: add
+---
+
+Appends <code>item</code> to the <code>list</code> node and returns the list, so calls chain. Order is preserved.

docs/language/value/value-as_int.md

@@ -0,0 +1,14 @@
+---
+id: value-as_int
+name: Value.as_int
+category: value
+kind: namespace-method
+tokens: Value.as_int
+sig: Value.as_int(value) -> int
+tip: Read a scalar node as an int.
+order: 16
+ns: Value
+member: as_int
+---
+
+Returns the raw scalar an int/fixed/bool node carries (a <code>fixed</code> comes back as its Q16.16 bits). Non-scalar nodes return <code>0</code>.

docs/language/value/value-as_str.md

@@ -0,0 +1,14 @@
+---
+id: value-as_str
+name: Value.as_str
+category: value
+kind: namespace-method
+tokens: Value.as_str
+sig: Value.as_str(value) -> string
+tip: Read a str node's text.
+order: 17
+ns: Value
+member: as_str
+---
+
+Returns the text a <code>str</code> node holds, or an empty string for any other kind.

docs/language/value/value-at.md

@@ -0,0 +1,14 @@
+---
+id: value-at
+name: Value.at
+category: value
+kind: namespace-method
+tokens: Value.at
+sig: Value.at(list, index: int) -> value
+tip: Read a list item by index.
+order: 12
+ns: Value
+member: at
+---
+
+Returns the item at <code>index</code> in a <code>list</code> (or object) node, or a <a href="value-null"><code>null</code></a> node if the index is out of range.

docs/language/value/value-bool.md

@@ -0,0 +1,14 @@
+---
+id: value-bool
+name: Value.bool
+category: value
+kind: namespace-method
+tokens: Value.bool
+sig: Value.bool(b: bool) -> value
+tip: Wrap a bool in a value node.
+order: 4
+ns: Value
+member: bool
+---
+
+Builds a <code>bool</code> node (kind <code>3</code>). It encodes to JSON <code>true</code>/<code>false</code>. Read it with <a href="value-as_int"><code>Value.as_int</code></a> (0 or 1).

docs/language/value/value-count.md

@@ -0,0 +1,14 @@
+---
+id: value-count
+name: Value.count
+category: value
+kind: namespace-method
+tokens: Value.count
+sig: Value.count(value) -> int
+tip: Number of items/members in a list or object.
+order: 14
+ns: Value
+member: count
+---
+
+Returns how many items a <code>list</code> holds, or how many members an <code>object</code> holds. Zero for a scalar node.

docs/language/value/value-fixed.md

@@ -0,0 +1,14 @@
+---
+id: value-fixed
+name: Value.fixed
+category: value
+kind: namespace-method
+tokens: Value.fixed
+sig: Value.fixed(f: fixed) -> value
+tip: Wrap a fixed in a value node.
+order: 3
+ns: Value
+member: fixed
+---
+
+Builds a <code>fixed</code> node (kind <code>2</code>) carrying the raw Q16.16 value <code>f</code>. <a href="json-encode"><code>Json.encode</code></a> writes it as an exact decimal (e.g. <code>0.5</code>) that <a href="json-parse"><code>Json.parse</code></a> reads back bit-for-bit.

docs/language/value/value-get.md

@@ -0,0 +1,14 @@
+---
+id: value-get
+name: Value.get
+category: value
+kind: namespace-method
+tokens: Value.get
+sig: Value.get(obj, key: string) -> value
+tip: Read a member of an object by key.
+order: 10
+ns: Value
+member: get
+---
+
+Returns the value stored under <code>key</code> in the <code>obj</code> node, or a <a href="value-null"><code>null</code></a> node if there is no such member.

docs/language/value/value-has.md

@@ -0,0 +1,14 @@
+---
+id: value-has
+name: Value.has
+category: value
+kind: namespace-method
+tokens: Value.has
+sig: Value.has(obj, key: string) -> bool
+tip: Whether an object has a member.
+order: 11
+ns: Value
+member: has
+---
+
+Returns whether the <code>obj</code> node has a member named <code>key</code> — the way to tell an explicit <a href="value-null"><code>null</code></a> from an absent key.

docs/language/value/value-int.md

@@ -0,0 +1,14 @@
+---
+id: value-int
+name: Value.int
+category: value
+kind: namespace-method
+tokens: Value.int
+sig: Value.int(n: int) -> value
+tip: Wrap an int in a value node.
+order: 2
+ns: Value
+member: int
+---
+
+Builds an <code>int</code> node (kind <code>1</code>) carrying <code>n</code>. Read it back with <a href="value-as_int"><code>Value.as_int</code></a>. This is the node <a href="reflect-serialize"><code>Reflect.serialize</code></a> uses for every non-<code>fixed</code> field.

docs/language/value/value-key_at.md

@@ -0,0 +1,14 @@
+---
+id: value-key_at
+name: Value.key_at
+category: value
+kind: namespace-method
+tokens: Value.key_at
+sig: Value.key_at(obj, index: int) -> string
+tip: The key of an object member by position.
+order: 13
+ns: Value
+member: key_at
+---
+
+Returns the key of the member at position <code>index</code> in an <code>object</code> node — pair it with <a href="value-at"><code>Value.at</code></a> and <a href="value-count"><code>Value.count</code></a> to walk every member in order.

docs/language/value/value-kind.md

@@ -0,0 +1,14 @@
+---
+id: value-kind
+name: Value.kind
+category: value
+kind: namespace-method
+tokens: Value.kind
+sig: Value.kind(value) -> int
+tip: The node's kind tag.
+order: 15
+ns: Value
+member: kind
+---
+
+Returns the node's kind: <code>0</code> null, <code>1</code> int, <code>2</code> fixed, <code>3</code> bool, <code>4</code> str, <code>5</code> list, <code>6</code> object — so a generic reader can branch before unwrapping.

docs/language/value/value-list.md

@@ -0,0 +1,14 @@
+---
+id: value-list
+name: Value.list
+category: value
+kind: namespace-method
+tokens: Value.list
+sig: Value.list() -> value
+tip: An empty list node.
+order: 6
+ns: Value
+member: list
+---
+
+Builds an empty <code>list</code> node (kind <code>5</code>). Append items with <a href="value-add"><code>Value.add</code></a>, read them with <a href="value-at"><code>Value.at</code></a> and <a href="value-count"><code>Value.count</code></a>.

docs/language/value/value-null.md

@@ -0,0 +1,14 @@
+---
+id: value-null
+name: Value.null
+category: value
+kind: namespace-method
+tokens: Value.null
+sig: Value.null() -> value
+tip: An empty null node.
+order: 1
+ns: Value
+member: null
+---
+
+Builds a <code>null</code> node — the absent value. <a href="value-get"><code>Value.get</code></a> and <a href="value-at"><code>Value.at</code></a> return one for a missing key or out-of-range index, so a reader never faults on absent data. Its <a href="value-kind"><code>Value.kind</code></a> is <code>0</code>.

docs/language/value/value-object.md

@@ -0,0 +1,14 @@
+---
+id: value-object
+name: Value.object
+category: value
+kind: namespace-method
+tokens: Value.object
+sig: Value.object() -> value
+tip: An empty object node.
+order: 7
+ns: Value
+member: object
+---
+
+Builds an empty <code>object</code> node (kind <code>6</code>) — an ordered set of key/value members. Set members with <a href="value-put"><code>Value.put</code></a>; read them with <a href="value-get"><code>Value.get</code></a>, <a href="value-key_at"><code>Value.key_at</code></a>, and <a href="value-count"><code>Value.count</code></a>. This is the shape <a href="reflect-serialize"><code>Reflect.serialize</code></a> produces.

docs/language/value/value-put.md

@@ -0,0 +1,14 @@
+---
+id: value-put
+name: Value.put
+category: value
+kind: namespace-method
+tokens: Value.put
+sig: Value.put(obj, key: string, item) -> value
+tip: Set a key on an object; returns the object.
+order: 9
+ns: Value
+member: put
+---
+
+Sets member <code>key</code> of the <code>obj</code> node to <code>item</code> (replacing an existing member with the same key) and returns the object. Insertion order is preserved for a stable <a href="json-encode"><code>Json.encode</code></a>.

docs/language/value/value-str.md

@@ -0,0 +1,14 @@
+---
+id: value-str
+name: Value.str
+category: value
+kind: namespace-method
+tokens: Value.str
+sig: Value.str(s: string) -> value
+tip: Wrap a string in a value node.
+order: 5
+ns: Value
+member: str
+---
+
+Builds a <code>str</code> node (kind <code>4</code>) holding <code>s</code>. <a href="json-encode"><code>Json.encode</code></a> quotes and escapes it; read it back with <a href="value-as_str"><code>Value.as_str</code></a>.