Release Java 1.554 shared LoadState and persistent Dynamic Fields

README.md

@@ -370,7 +370,9 @@ The main entity construction, JSON, and SQL row-mapping paths are designed to
 avoid reflection-heavy bean mutation:
 
 - `teaql-jackson` registers explicit entity serializers and deserializers
-  through `TeaQLModule`.
+  through `TeaQLModule`. For indexed domain-entity reads, bind a mapper to the
+  installed model with `new TeaQLModule(context)`; the legacy singleton retains
+  generic BaseEntity reading and entity serialization compatibility.
 - `teaql-sql-portable` creates entities through
   `EntityDescriptor.createEntity()`.
 - Generated or hand-written metadata registers an `entitySupplier`, such as
@@ -380,6 +382,21 @@ Dynamic and additional values should remain JSON-friendly: scalars, maps,
 lists, or other explicitly serializable values. Arbitrary application objects
 may still trigger Jackson's default bean introspection.
 
+The context-bound reader uses registered entity suppliers and typed internal
+hydration, preserving loaded NULL versus omitted NotLoaded without dirtying a
+Mutation Ledger. Compatible JSON shapes share immutable state; the reader's
+value-free shape cache is bounded to 128 entries. Unknown model types, fields,
+internal state and duplicate aliases reject instead of invoking bean setters.
+Keep one configured mapper/model binding per context metadata snapshot; do not
+switch models on a mapper that has already cached readers.
+
+JSON hydration does not make client data authoritative or authorize a save.
+Load the governed database object before applying business mutations and retain
+whole-object Checker and audited-save requirements. Readonly `_` properties may
+roundtrip as data; persistent `#` fields require a separately trusted definition
+and storage-provenance contract and currently reject in the typed JSON reader.
+See the [generated shared-state example](examples/shared-load-state/README.md).
+
 See the [Native Image Reflection Guide](NATIVE_IMAGE_REFLECTION_GUIDE.md) for
 the baseline and coding rules.
 

examples/business-id-runtime/pom.xml

@@ -6,7 +6,7 @@
     <parent>
         <groupId>io.teaql</groupId>
         <artifactId>teaql-java-parent</artifactId>
-        <version>1.553-RELEASE</version>
+        <version>1.554-RELEASE</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <artifactId>teaql-business-id-example</artifactId>

examples/conformance/lib/pom.xml

@@ -12,7 +12,7 @@
   <properties>
     <java.version>21</java.version>
     <spring-boot.version>4.1.1</spring-boot.version>
-    <teaql.version>1.553-RELEASE</teaql.version>
+    <teaql.version>1.554-RELEASE</teaql.version>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <maven.compiler.parameters>true</maven.compiler.parameters>
   </properties>

examples/conformance/pom.xml

@@ -16,7 +16,7 @@
     <libversion>1.0.0</libversion>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <maven.compiler.parameters>true</maven.compiler.parameters>
-    <teaql.version>1.553-RELEASE</teaql.version>
+    <teaql.version>1.554-RELEASE</teaql.version>
   </properties>
 
   <repositories>

examples/order-management/java-app-console/pom.xml

@@ -11,7 +11,7 @@
   <properties>
     <maven.compiler.release>21</maven.compiler.release>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <teaql.version>1.553-RELEASE</teaql.version>
+    <teaql.version>1.554-RELEASE</teaql.version>
   </properties>
   <dependencies>
     <dependency>

examples/order-management/java-lib-core/lib/pom.xml

@@ -12,7 +12,7 @@
   <properties>
     <java.version>21</java.version>
     <spring-boot.version>4.1.1</spring-boot.version>
-    <teaql.version>1.553-RELEASE</teaql.version>
+    <teaql.version>1.554-RELEASE</teaql.version>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <maven.compiler.parameters>true</maven.compiler.parameters>
   </properties>

examples/round-trip-reference-runtime/pom.xml

@@ -6,7 +6,7 @@
     <parent>
         <groupId>io.teaql</groupId>
         <artifactId>teaql-java-parent</artifactId>
-        <version>1.553-RELEASE</version>
+        <version>1.554-RELEASE</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <artifactId>teaql-round-trip-reference-example</artifactId>

examples/school-management/lib/pom.xml

@@ -12,7 +12,7 @@
   <properties>
     <java.version>21</java.version>
     <spring-boot.version>4.1.1</spring-boot.version>
-    <teaql.version>1.553-RELEASE</teaql.version>
+    <teaql.version>1.554-RELEASE</teaql.version>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <maven.compiler.parameters>true</maven.compiler.parameters>
   </properties>

examples/school-management/pom.xml

@@ -16,7 +16,7 @@
     <libversion>0.0.1-SNAPSHOT</libversion>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <maven.compiler.parameters>true</maven.compiler.parameters>
-    <teaql.version>1.553-RELEASE</teaql.version>
+    <teaql.version>1.554-RELEASE</teaql.version>
   </properties>
 
   <repositories>

examples/security-foundations/pom.xml

@@ -6,7 +6,7 @@
     <parent>
         <groupId>io.teaql</groupId>
         <artifactId>teaql-java-parent</artifactId>
-        <version>1.553-RELEASE</version>
+        <version>1.554-RELEASE</version>
         <relativePath>../../pom.xml</relativePath>
     </parent>
     <artifactId>teaql-security-foundations-example</artifactId>

examples/security-foundations/src/test/java/io/teaql/examples/security/SqlRelationMaskingTest.java

@@ -131,7 +131,11 @@ private static SQLEntityDescriptor descriptor(String type, Class<? extends Row>
                     .purpose("inspect Riverside RELATION-PASSWORD-CANARY relations").executeForList(context);
             assertEquals(1, rows.size());
             assertEquals("Riverside", rows.get(0).getProperty("name"));
-            if (shape.equals("aggregate")) assertEquals(1, ((Number) rows.get(0).getProperty("childCount")).intValue());
+            if (shape.equals("aggregate")) {
+                assertEquals(1, ((Number) rows.get(0).getDynamicProperty("childCount")).intValue());
+                assertEquals(1, ((Number) rows.get(0).getProperty("_childCount")).intValue());
+                assertNull("Aggregate results must not overwrite the native namespace", rows.get(0).getProperty("childCount"));
+            }
             else if (shape.equals("facet")) {
                 SmartList<Entity> parents = rows.getFacet("parentFacet");
                 assertEquals(1, parents.size());

examples/shared-load-state/.gitignore

@@ -0,0 +1 @@
+/target/

examples/shared-load-state/README.md

@@ -0,0 +1,176 @@
+# Generated Java shared load state example
+
+This small SQLite acceptance example uses a newly generated School library and
+the Java runtime source from the same Maven reactor. It does not install,
+publish or substitute TeaQL jars from a public repository.
+
+## Run
+
+Requires Java 21 or newer, Maven, Bash, `rg`, `sha256sum`, and a local generator
+checkout. Third-party dependencies may download on the first run.
+
+```bash
+export TEAQL_CODEGEN_DIR=/path/to/teaql-code-gen
+bash examples/shared-load-state/verify.sh --generate
+```
+
+The producer reads the current runtime version from its parent POM, generates
+the library and Query/Create/Expression/Delete Assist into `target/generated`,
+and never edits generated Java source. The `shared-load-state-example` Maven
+profile builds the generated library and application-owned tests with the
+runtime dependencies in one reactor. Omit `--generate` to replay that artifact.
+
+Use `bash examples/shared-load-state/verify.sh --generate --wide` for the overflow
+gate. The producer adds 130 nullable School probes, producing 141 fixed slots,
+and retains `model-under-test.xml` plus `fixture-mode.txt`. Both rounds assert
+generated slots 0/31/32/63/64/65/129, actual NULL payloads, sparse NotLoaded and
+overflow copy-on-write. A requested wide run rejects a narrow artifact; an
+existing wide artifact automatically keeps the wide assertions enabled.
+
+Add `--inheritance` during generation to append one Academy subtype with a
+campus code. The base model has Platform, SchoolType, School and a small
+SchoolCapacitySummary reporting target. The producer
+retains a separate inheritance marker and the verifier selects an additional
+Maven test source only for that generated artifact. A requested inherited run
+rejects a flat artifact; replay preserves the inherited gate automatically.
+The inherited gate checks shared parent indexes and separate type identity,
+Q/E, actual snapshot sharing and governed create/update/delete with a fully
+loaded object. Its qualification is separate from the plain School gate.
+
+Each invocation retains a unique temporary directory containing its SQLite file,
+round logs and generated-source hashes. Both rounds use that same database
+without cleanup. The test checks the actual class-loading locations for core,
+runtime, JDBC, SQLite and the generated School: every one must resolve to local
+reactor `target/classes`, not an installed jar.
+
+## Acceptance
+
+`GeneratedMaterializationAcceptance` calculates a capacity total over two
+bounded School Q results using E. The readonly `_total_capacity` result gets
+no fixed slot and must not persist when the source is saved. Persistence is
+explicit: create a modeled SchoolCapacitySummary with its generated Mutation
+API, attach an audit reason, save, and query it back through Q/E. The expected
+total is 37 and contributor count is 2. The source sibling retains its original
+shared snapshot and clean mutation state. This is application-side calculation
+and modeled storage, not a database aggregate-query performance claim.
+
+`GeneratedNestedGraphAssertions` also verifies a bounded Platform-to-Schools
+view and School-to-Platform-to-Schools graph through generated Q/E and JSON.
+Loaded empty lists serialize as arrays; unselected lists stay absent. A target
+filter cannot erase the source's known FK or invent loaded target detail.
+These cases are required in both retained rounds, not optional smoke output.
+
+The mapper uses `new TeaQLModule(context)` for indexed, strongly typed JSON
+reads through installed suppliers rather than bean reflection. Both rounds
+roundtrip full and minimal School projections, nested forward/reverse graphs,
+and loaded empty versus omitted reverse lists. Missing target details stay
+NotLoaded, actual NULL stays loaded, and compatible decoded rows share state
+without creating mutation intent. This does not certify arbitrary polymorphic
+or persistent `#` JSON input: those require their own contract. Decoded data is
+not a substitute for loading authoritative state before mutation.
+
+- Repeated schema bootstrap preserves Platform 1 and SchoolType 1001/1002.
+- Generated indexes and revision match the installed type layout.
+- Compatible full and sparse lists share exact immutable snapshot references
+  within each shape, without sharing values or merging their load boundaries.
+- Filling an omitted field detaches that row's state; changing an existing value
+  keeps the snapshot reference. Zero/false remain loaded values.
+- Generated Q/E traverse forward relations, and the full-object Checker rejects
+  sparse saves. Audited create, update and soft delete preserve sibling values
+  and optimistic versions.
+- A JDBC Dynamic Field provider uses the same SQL executor as native mutation.
+  Governed save distinguishes stored Value, explicit NULL and Delete.
+- A held dynamic view rejects a changed storage profile before DML, keeps its
+  pending intent, and retries after restoring the original profile. Rebuilding
+  the provider over the same executor is valid; it does not change storage identity.
+- Readonly `_name` coexists with native `name`; a missing dynamic property reads
+  null, and ordinary save does not persist derived properties.
+
+Partial child projections are valid for E reads and do not block saving a
+complete parent when those children are untouched. Every actually modified
+object must itself be fully loaded; modified descendants cannot hide behind an
+untouched parent. The example reloads the full School before deletion rather
+than disabling that validation.
+
+The persistent ID allocator uses its framework database bridge. Application
+business data is created through generated mutation APIs, not handwritten SQL.
+Dynamic-field definitions are registered explicitly as provider metadata; each
+round has its own test definition.
+
+This is a small generated-consumer gate, not an allocation or throughput benchmark.
+The optional wide fixture covers compiled overflow entities. Nested extension
+graphs, broader provider provenance, serialization and immutable internal-artifact
+consumers remain separate gates.
+
+For a new object with no queried extension view, obtain definitions with
+`context.dynamicFields().metadata(ownerType)` and install an empty
+`DynamicFieldValues` using that snapshot before updating extensions. This reads
+definitions, not owner values. Unbound hand-built metadata cannot be silently
+assigned to the current storage during save.
+
+## State allocation probe
+
+```bash
+bash examples/shared-load-state/verify-allocations.sh
+```
+
+The probe lives in the unnamed example module, so the core module gains no JVM
+management dependency. It uses `ThreadMXBean` allocated-byte counters after
+warmup, with 4/64/130 fixed fields and 1/100/10,000 operations. Fixture setup,
+payloads, JDBC and output formatting are outside the counted region. Ordinary
+sets and Map-backed code views are both checked. A value-free private raw-code
+array is memoized in the shared snapshot; it neither assigns dynamic-field
+indexes nor changes the snapshot's availability, equality or hash. Real selection
+changes still detach, and caller-owned sets cannot mutate the saved shape.
+
+The script retains separate state and four-field hydration CSV/logs. After
+generating a wide fixture, add `--wide` to measure actual generated School and
+optional Academy hydration at 3/64/full selected fields and 1/100/10,000 rows.
+Wide mode also requires `GeneratedReadbackAllocationTest`: generated School
+authoritative reads reuse value-free projection geometry. The prepared-map
+probe compares gross thread allocation with a typed incremental-state reference
+at 1/100/10,000 readbacks. It checks every value, shared state and private ledgers;
+it does not measure complete saves, SQL I/O, live heap or old-version latency.
+This checks shared overflow snapshots, COW isolation and lazy ledgers, requires
+unchanged generated-source hashes, and rejects a non-wide artifact. Prepared
+inputs, JDBC and logging remain outside the measured hydration region. These
+are not whole-query latency, retained heap, CPU saturation or ORM comparisons.
+
+The no-op probe preserves every bounded attempt, including JVM transient bytes,
+and requires three consecutive zero-allocation samples within twenty attempts.
+An allocating positive control must remain visible. This is a warmed-window
+claim, not a guarantee of zero allocation for every JVM observation.
+
+## Process cold startup probe
+
+```bash
+bash examples/shared-load-state/benchmark-cold.sh
+bash examples/shared-load-state/benchmark-cold.sh --default-log
+```
+
+Run the local verifier once before this probe to provide a reactor-resolved
+test classpath. The probe requires `xmllint`. It prepares two Schools using
+generated audited mutations in a separate JVM, then launches seven fresh JVMs.
+Each records Context initialization and its first sparse two-row Q query
+separately, with E/name/version, shared snapshot and local class-location checks.
+No schema writes or query warmup occur in measured JVMs. Database and generated
+source hashes must stay unchanged. The external CPU receipt includes JVM startup,
+class loading, validation and output, not Maven compilation or fixture setup.
+OS page caches are not cleared. Byte counters report gross requested thread
+allocations, not retained heap or allocation-call counts.
+
+## Matched driver logging modes
+
+```bash
+bash examples/shared-load-state/benchmark-driver.sh
+bash examples/shared-load-state/benchmark-driver.sh --default-log
+```
+
+Run these sequentially. Both modes retain six sparse/full cases, identical
+native SQL/binds and typed-result/load-state checks over 31 alternating samples.
+Default mode uses the unchanged stderr sink and privacy policy; off mode
+disables query logging. The scripts reject plaintext opt-in. Query samples
+exclude setup and correctness checks; the CPU receipt includes Maven/JIT.
+Native-driver drift between processes prevents treating an absolute latency
+difference as pure logging cost. Different Rust connection and output strategies
+prohibit a language ranking. No publication occurs.

examples/shared-load-state/benchmark-cold.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+set -euo pipefail
+mode=off
+case "${1:-}" in
+  '') ;;
+  --default-log) mode=default ;;
+  *) printf 'Usage: bash benchmark-cold.sh [--default-log]\n' >&2; exit 2 ;;
+esac
+(( $# <= 1 )) || exit 2
+runtime_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+example_dir="$runtime_dir/examples/shared-load-state"
+run_dir="$(mktemp -d -t teaql-java-cold-query.XXXXXXXX)"
+printf 'Cold query evidence: %s\n' "$run_dir"
+cd "$runtime_dir"
+git diff HEAD --exit-code -- examples/shared-load-state teaql-core teaql-runtime teaql-provider-jdbc
+git rev-parse HEAD >"$run_dir/base-commit.txt"
+java -version >"$run_dir/toolchain.txt" 2>&1
+sha256sum examples/shared-load-state/src/test/java/com/example/schoolmanagementservice/GeneratedColdQueryProbe.java >"$run_dir/source.sha256"
+rg --files --hidden --no-ignore "$example_dir/target/generated/lib/src" -0 |
+  sort -z | xargs -0 sha256sum >"$run_dir/generated-source.sha256"
+# Run the local verifier first to provide a reactor-resolved test classpath.
+report="$example_dir/target/surefire-reports/TEST-com.example.schoolmanagementservice.GeneratedSchoolLoadStateTest.xml"
+[[ -f "$report" ]] || { printf 'Run examples/shared-load-state/verify.sh first\n' >&2; exit 1; }
+mvn -q -o -Pshared-load-state-example -pl examples/shared-load-state -am -DskipTests test-compile >"$run_dir/build.log" 2>&1
+classpath="$(xmllint --xpath 'string(/testsuite/properties/property[@name="java.class.path"]/@value)' "$report")"
+[[ -n "$classpath" ]]
+export TEAQL_LOCAL_RUNTIME_ROOT="$runtime_dir"
+TEAQL_COLD_LOG_MODE=off java -cp "$classpath" com.example.schoolmanagementservice.GeneratedColdQueryProbe prepare "$run_dir/school.sqlite" >"$run_dir/prepare.log" 2>&1
+sha256sum "$run_dir/school.sqlite" >"$run_dir/database.sha256"
+for round in 1 2 3 4 5 6 7; do
+  TEAQL_COLD_LOG_MODE="$mode" /usr/bin/time -v -o "$run_dir/cpu-$round.txt" \
+    java -cp "$classpath" com.example.schoolmanagementservice.GeneratedColdQueryProbe query "$run_dir/school.sqlite" >"$run_dir/round-$round.log" 2>&1
+  rg -F 'PASS generated Java process-cold Q/E and shared snapshot' "$run_dir/round-$round.log"
+done
+sha256sum --check --quiet "$run_dir/database.sha256"
+sha256sum --check --quiet "$run_dir/source.sha256"
+sha256sum --check --quiet "$run_dir/generated-source.sha256"

examples/shared-load-state/benchmark-driver.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+runtime_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+case "${1:-}" in
+  "") export TEAQL_DRIVER_BENCHMARK_LOG_MODE=off ;;
+  --default-log) export TEAQL_DRIVER_BENCHMARK_LOG_MODE=default ;;
+  *) printf 'Usage: bash benchmark-driver.sh [--default-log]\n' >&2; exit 2 ;;
+esac
+(( $# <= 1 )) || { printf 'Unexpected arguments\n' >&2; exit 2; }
+if [[ -n "${TEAQL_ALLOW_SENSITIVE_PLAINTEXT_LOGS:-}" ]]; then
+  printf 'Unset TEAQL_ALLOW_SENSITIVE_PLAINTEXT_LOGS for the masked logging benchmark\n' >&2; exit 2
+fi
+run_dir="$(mktemp -d -t teaql-java-driver-evidence.XXXXXXXX)"
+cd "$runtime_dir"
+java -version >"$run_dir/toolchain.txt" 2>&1
+git rev-parse HEAD >"$run_dir/base-commit.txt"
+sha256sum examples/shared-load-state/src/test/java/com/example/schoolmanagementservice/{DriverQueryBenchmarkTest,HydrationAllocationTest}.java >"$run_dir/source.sha256"
+# Requires the example's locally generated fixture, as for verify.sh. This
+# CPU receipt includes Maven compilation/JIT and is not query CPU attribution.
+/usr/bin/time -v -o "$run_dir/maven-cpu.txt" mvn -q -Pshared-load-state-example \
+  -pl examples/shared-load-state -am -Dtest=DriverQueryBenchmarkTest \
+  -Dsurefire.failIfNoSpecifiedTests=false -Dteaql.driverBenchmark=true test \
+  >"$run_dir/results.log" 2>&1
+rg -F 'PASS matched JDBC typed results and shared snapshots' "$run_dir/results.log"
+sha256sum --check --quiet "$run_dir/source.sha256"
+printf 'Driver benchmark evidence: %s\n' "$run_dir"