007. Specialize recoverable PostgreSQL JSON equality

• Status: Measured
• Date: 2026-10-13

Problem and mechanism

Equality between JSON-backed values can require a recursive runtime walk to recover each node's type and structure. The candidate uses the declared root schema when it makes a comparison path definite: lists compare by ordinal, objects by key set, and nested values use the existing typed recursion. This also applies when children are Any. An Any value compared with one known scalar family uses a category check and that scalar's exact comparison instead of a generic tree walk.

Both operands still pass through the existing representation-recovery path. JSONB metadata requirements, nested-null equality, absent-versus-null object keys, and top-level null/no-value behavior are unchanged. Comparisons with two unconstrained roots, an unconstrained root against a container, or overlapping structural unions retain the generic recursive JSON comparison.

Applicability

Reproduction

The baseline is 258cacd. The candidate source snapshot SHA-256 values were:

The baseline revision was extended with the same comparison harness, fixtures, and testing.TB helper-signature changes used for the candidate. The AnyRootControl schema is unconstrained Any compared with a list literal. Build measurements covered TypedListControl, AnyRootControl, AnyList, AnyMap, and AnyStruct for native JSON and metadata-backed JSONB. Database measurements used the same ten format/shape combinations at 50 and 250 rows. Each execution sample checked SQL result IDs against local HFF matches and the fixture's expected IDs before measuring PostgreSQL planning and execution. Query values included [1, 2, null] and {"price": 1, "empty": null}. Fixtures also covered mixed integer/float values, null roots, short and long lists, and missing versus extra object keys.

The host was Darwin 25.2.0, arm64, Apple M3 Max with 64 GiB RAM. Go was 1.27.1 with default GOMAXPROCS=16. PostgreSQL was 18.6 in the same Debian aarch64 container image used by the surrounding metadata measurements (sha256:5a5a84b19854a9ffaa54082c166ff4ec27473a361e496e5ea167f298f2da9722). The database directory used tmpfs; there were no explicit CPU, memory, or cpuset limits. JIT was off, parallel workers were disabled, plans were forced custom, and statement timeout was 60 seconds. Two serialized baseline/candidate pairs were run; tables report the final three-sample pair. The query-result check precedes each EXPLAIN sample.

Build command:

GOTOOLCHAIN=go1.27.1 go test ./backends/sql -run '^$' \
  -bench '^BenchmarkPostgreSQLComparisonBuild$/(json|jsonb)/(TypedListControl|AnyRootControl|AnyList|AnyMap|AnyStruct)$' -benchmem \
  -benchtime=200ms -count=3

Database execution command (use separate plan directories for baseline and candidate):

HFF_POSTGRES_CONTAINER=<container-name-or-id> \
HFF_POSTGRES_PLAN_DIR=/private/tmp/hff-comparison-plans \
GOTOOLCHAIN=go1.27.1 go test -tags=integration ./backends/sql -run '^$' \
  -bench '^BenchmarkPostgreSQLComparisonExecution$/(json|jsonb)/(50Rows|250Rows)/(TypedListControl|AnyRootControl|AnyList|AnyMap|AnyStruct)$' \
  -benchtime=1x -count=3

Raw logs, SQL, plans, and fixture results are outside Git in /private/tmp/hff-comparison-plan-evidence/ on the measurement host.

Results

Build times are median ns/op with the three-sample min–max. B/op is cumulative allocation, not peak or retained memory.

Database timing tables report median milliseconds and the three-sample min–max. Plan nodes and SQL bytes report baseline to candidate; every case had the same match count in both revisions.

The typed-list and unconstrained-root-versus-list-literal controls retain byte-identical SQL and plan-node counts; their timings vary between samples. For the definite container workloads, generated SQL and plan size are smaller in this fixture. These measurements do not establish a general database latency improvement or an index-use guarantee. Build B/op is cumulative allocation; live or peak memory was not measured.

Correctness and tradeoffs

The tests cover null roots, empty containers, nested nulls, missing versus present-null keys, list length/order, object key sets, numeric subtypes, and metadata-required JSONB representations. Both sides still use comparisonDocumentAgainst, so specialization does not bypass numeric representability checks. The root type controls whether a typed recursive plan is used; a definite container pair can recurse into Any children. Generic runtime-tree equality remains for two unconstrained roots, root-Any versus a container, and ambiguous structural unions. No retained-memory measurement was made.

Candidate validation:

• TMPDIR=/private/tmp HFF_WASM_NODE=<node-path> GOTOOLCHAIN=go1.27.1 sh hack/check.sh passed, including formatting, race tests, vet, generation checks, examples, WASM, and site checks.
• TMPDIR=/private/tmp GOTOOLCHAIN=go1.27.1 go vet -tags integration ./backends/sql passed.
• TMPDIR=/private/tmp GOTOOLCHAIN=go1.27.1 HFF_POSTGRES_CONTAINER=<container-name> go test -tags integration ./backends/sql -count=1 passed the full PostgreSQL integration suite (352.541s).

Decision and limits

Retain the measured specialization for definite same-category containers and Any-to-known-scalar comparisons. The controls show unchanged SQL shape for typed lists and an unconstrained root compared with a list literal. The result applies to these schemas, fixtures, and PostgreSQL profile; it does not imply lower latency for every query or remove JSONB metadata requirements.