fix(runtime): validate compiled JSON request body schemas

[samzong]

Summary

Validate compiled JSON request-body structure in the shared request builder before HTTP execution. Invalid bodies now fail locally with usage exit 2 and a value-free body path across direct commands, file/set/string-set/body-flag inputs, workflows, public operation invocation, and dry-run previews.

Reuse the existing JSON Schema dependency for declared types, nullable values, nested properties/items, required fields, and resolved allOf structure. Template bodies validate the payload at their merge path. Preserve GraphQL nullability/coercion and ProtoJSON nullability, numeric/enum alternatives, and well-known message shapes before making metadata executable. Exclude read-only required fields only on request schemas (including refs/allOf), retain Swagger x-nullable, and project unknown types or absent schema nodes as unconstrained while retaining supported sibling constraints. Document the subset in CLI/contracts/architecture guidance and generated Skills.

Closes #118.

Verification

• make check passed: format, vet, lint, and all package tests.
• go test -race ./pkg/runtime ./internal/codegen/normalize ./internal/codegen/backends/proto ./internal/codegen/backends/openapi3 ./internal/codegen/backends/swagger ./internal/codegen/backends/graphql passed.
• TestGeneratedBodySchemaPreservesGraphQLInputs compares legal values with the installed GraphQL validator before exercising generated operation declarations, including nullable inputs, singleton lists, numeric IDs, and custom scalar objects.
• go test ./pkg/runtime -run TestStaticBodySchema -count=1 passed. The added tests were copied into an exported baseline at d0d60ab; all seven invalid-body entrypoint cases failed on that baseline and passed with this change.
• Generated and built a scratch Rich API CLI from OpenAPI inputs with a resolved nested reference. richapi __lathe verify --json passed; command detail exposed the compiled schema and generated Skills contained the updated guidance. A regenerated GraphQL CLI also passed __lathe verify --json and accepted first=null in a network-free preview. A schema-17 module rebuilt against the new runtime failed startup with the regeneration instruction.
• A loopback HTTP acceptance script confirmed invalid types, nested items, missing required fields, and invalid dry-run bodies failed with zero requests. A valid file reached the wire unchanged, including its large integer; a valid preview sent no request.
• Claude review identified ProtoJSON, request read-only required fields, unsupported metadata, and Swagger nullability regressions. Added tests reproduce each against the pre-fix target and pass after correction. ProtoJSON positives are checked with the installed protojson.Unmarshal implementation; typed numeric body flags remain executable.
• Generated/built a descriptor-backed protobuf CLI; __lathe verify --json passed. A quoted int64 and null body field pass the actual command preview; an invalid string field fails with usage exit 2. Regenerated the Rich API CLI with an allOf read-only required property and repeated the loopback acceptance successfully.
• Live production APIs, real protoc/grpc-gateway end-to-end execution, and historical invalid writes were not verified or repaired.

Performance evidence

The benchmark job passes. CodSpeed's non-required comparison remains red and explicitly reports unknown walltime runners and different environments (baseline AMD EPYC 9V45; this head Intel Xeon 6973P-C), including regressions in unchanged formatting/catalog paths. On the same local machine, five samples show normalization medians of 57.5 to 62.1 microseconds for 16 commands and 795.0 to 835.4 microseconds for 192 commands. This bounds the added code-generation work to roughly 40 microseconds for the larger fixture; it does not establish zero overhead or validate production latency.

Compatibility

Generated SchemaVersion increases from 17 to 18: regenerate modules before linking the new runtime. This prevents old GraphQL or protobuf metadata from rejecting legal inputs; existing mount guards fail explicitly with a regeneration instruction. CatalogSchemaVersion stays 25; the catalog shape is unchanged. JSON bodies with compiled schemas now reject structurally invalid input before transport, including during dry-run. Optional omitted bodies, non-JSON bodies, and commands without compiled schemas retain their existing behavior.

Static validation does not enforce enum, format, anyOf, oneOf, additionalProperties, or unresolved references. Unknown type names and absent schema nodes remain unconstrained; duplicate required names are deduplicated. It does not fetch external references or claim full JSON Schema/OpenAPI/ProtoJSON support. Existing fetched runtime-schema validation remains separate.

Checklist

• Tests or focused verification cover the changed surface.
• User-facing behavior changes are documented.
• Generated output under internal/generated/, .cache/, and ad-hoc skills/<cli-name>/ directories is not committed.
• Commits are signed off when this is ready to merge.

[codspeed]

Merging this PR will degrade performance by 17.79%

⚠️ Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

❌ 20 regressed benchmarks
✅ 1 untouched benchmark

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
❌	yaml	2.6 ms	3.5 ms	-25.51%
❌	large	1.2 ms	1.6 ms	-24.67%
❌	BenchmarkParseNormalize	3.7 ms	4.9 ms	-23.41%
❌	large	837.4 µs	1,078.9 µs	-22.38%
❌	small	60.6 µs	76.7 µs	-21.04%
❌	miss	2 ms	2.5 ms	-20.9%
❌	hit	2 ms	2.5 ms	-19.57%
❌	json	736.5 µs	894.1 µs	-17.63%
❌	yaml-large	8.2 ms	9.9 ms	-17.23%
❌	small	81.3 µs	97.5 µs	-16.64%
❌	BenchmarkFindCatalogCommand	4.6 µs	5.5 µs	-16.48%
❌	large	911.8 µs	1,083 µs	-15.81%
❌	BenchmarkBuildFlat	1.3 ms	1.5 ms	-15.69%
❌	BenchmarkFormatTableInferredColumns	635.3 µs	752.3 µs	-15.55%
❌	small	107.8 µs	125.7 µs	-14.22%
❌	BenchmarkCatalogJSON	1.7 ms	2 ms	-14.19%
❌	large	1.4 ms	1.6 ms	-13.89%
❌	json-large	2 ms	2.3 ms	-13.41%
❌	table	435.1 µs	499.6 µs	-12.92%
❌	json-small	145.5 µs	166.7 µs	-12.69%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing fix/request-body-schema (5346c31) with main (d0d60ab)}