SESSION-EMPTY-OBJECT: refuse {} in the JSON preflight so a malformed document cannot abort the host

[tamashi095]

Summary

• crates/session/src/json_preflight.rs: reject an empty JSON object {} anywhere in the document, before the typed walk and before json-syntax's Value tree is built, with a proper source span, DiagnosticCode::JsonSyntax, and message "empty JSON object {} is never a valid V1 schema value". This is option 1 from session aborts the host on untrusted JSON containing an empty object {} (parser CodeMap volume bug, reachable from C API and wasm boot) #387.
• Confirmed {} is never legal V1: docs/SESSION_SCHEMA_V1.md -- "Every object rejects unknown keys and every field is explicit, including empty arrays"; every schema object has required keys, so an object with none can never validate. Empty arrays stay legal and untouched (array() is unmodified).
• Root cause (upstream, not fixed here): json-syntax 0.12.5 never calls parser.end_fragment(i) for an empty object, so the reserved CodeMap entry keeps span = p..p, volume = 0. IterMapped::next then advances 2 + volume instead of 2 + 1, so every object member after an empty object is read one CodeMap slot off. session::parse::Parser::keys (crates/session/src/parse.rs:100) hits Option::unwrap() on the resulting None at json-syntax-0.12.5/src/object/mod.rs:795:67. The workspace's release profile is panic = "abort" (Cargo.toml:132), so this aborts the host process / traps the AudioWorklet rather than returning a diagnostic, for any document reachable through miso_engine_v1_compile_session or miso_engine_web_v1_boot.
• Reused the existing DiagnosticCode::JsonSyntax ("json.syntax") rather than adding a new code: it is exactly the code the preflight's other two refusals (duplicate key, depth-129) already use, and tools/session-validator/src/lib.rs documents (and tests) that json.syntax is produced only by the grammar stage and is always returned alone -- our new refusal preserves that invariant (it also short-circuits the whole document, same as the other two). No conformance fixture or diagnostic-code enumeration needed updating (there is no registry doc or enumerated-code list beyond the DiagnosticCode enum itself and docs/SESSION_SCHEMA_V1.md's prose) -- but docs/SESSION_SCHEMA_V1.md's own prose describing the preflight did need updating, and initially wasn't: see "Documentation and comment corrections" below, added after verifier review.
• Factored the three refusal sites' (duplicate key, depth, now empty-object) identical path-materialization loop into one Scanner::current_path helper in the same file, to avoid a third copy.
• Re-pinned the shipped AudioWorklet artifact (crates/session ships in the wasm build) and regenerated the qualification lineage, exactly as JSON-SYNTAX: replace the jstrict fork with upstream json-syntax in crates/session #385 did, against the latest origin/main (65d83af5, includes TOOLING-DEDUPE: remove the private SHA-256 and the incomplete JSON escaper, fold duplicated helpers into bench-support #386) -- twice (see "Documentation and comment corrections").

Documentation and comment corrections (verifier round 1: REQUEST CHANGES)

The fix itself was verified correct (186 {} placements, 48 scanner attacks, fuzz clean, all CI job commands green locally); the verifier's findings were documentation and PR-truthfulness only, addressed in two follow-up commits:

1. docs/SESSION_SCHEMA_V1.md did not mention the empty-object refusal at all, even though its opening paragraph already documents the sibling duplicate-key and depth-129 preflight refusals. Added two sentences there naming the code (json.syntax), the path/span shape (over the value's {...} bytes), the json-syntax 0.12.5 CodeMap defect it works around, and that empty arrays are unaffected.
2. crates/session/src/json_preflight.rs:31-32's comment said this pass "only returns the two refusals for which the value parser does not expose the required contract information" -- stale from before the empty-object refusal existed, and actually wrong for it: the value parser would diagnose an empty object correctly on its own (missing schema fields etc.); the refusal exists to keep the corrupted CodeMap state from ever being reached, not because of a contract-information gap. Rewritten to name all three refusals accurately.
3. The issue asked to add {} to the session_parse fuzz corpus seeds; the original PR did not wire this into CI. Added fixtures/session/v1/fuzz-seeds/empty-object.json (canonical.json with render_profile set to {}) and appended it to .github/workflows/fuzz.yml's session_parse job -seed_inputs= list (libFuzzer accepts a comma-separated list). Verified directly: running the compiled session_parse fuzz binary once against this exact seed on this branch executes cleanly with no crash; the identical byte content already reproduced the pre-fix panic in this PR's own session-level repro (captured before implementing the fix) and is how the JSON-SYNTAX: replace the jstrict fork with upstream json-syntax in crates/session #385 verifier found session aborts the host on untrusted JSON containing an empty object {} (parser CodeMap volume bug, reachable from C API and wasm boot) #387 in the first place -- so this seed would crash main's session_parse target on its first execution, and CI will now catch a regression here going forward.
4. Option 3 was misquoted in the PR's original "Seen, not done": session aborts the host on untrusted JSON containing an empty object {} (parser CodeMap volume bug, reachable from C API and wasm boot) #387 says upstreaming the json-syntax fix is "in addition to 1, not instead" -- i.e. still owed, not forbidden. My original PR body incorrectly framed it as if the issue itself excluded it; that exclusion was actually my own task scope for this PR, not the issue's position. Corrected below; the coordinator will open the follow-up issue for the upstream PR + [patch].
5. Unplanned re-pin: editing json_preflight.rs's comment (item 2) shifts every subsequent line number in that real, shipped source file, including its one slicing panic site (self.source[start..self.cursor] in Scanner::string). Rust embeds a core::panic::Location (file/line/column) constant at that call site regardless of the release profile's -C strip=debuginfo (that strip level removes DWARF sections, not these compiled-in panic-location strings), so a comment-only edit to a shipped file still moves the wasm artifact's bytes. Confirmed by rebuilding: digest changed 439ba6b5... -> f1f27d8d... at the identical byte count (2,635,719) -- a debug-metadata-only delta, not a behavior change -- so the artifact was re-pinned and the qualification lineage regenerated a second time, against this branch's actual final commits.
6. Per the coordinator's explicit instruction, crates/capi/tests/resource_lifecycle.rs is untouched. exported_c_candidates_replay_render_and_both_destroy_orders_balance_exactly (left 2613, right 2610) already fails on main itself since JSON-SYNTAX: replace the jstrict fork with upstream json-syntax in crates/session #385 and is being diagnosed separately; it is unrelated to this PR and out of scope here.

Rows closed (#387)

• The fuzz artifact and every {} placement now produce a diagnostic, not a panic, through parse_session_json, miso_engine_v1_compile_session, and miso_engine_web_v1_boot. See Before/after.
• cargo test --locked --workspace count matches main plus the new regression tests (see Gate output / workspace counts below).
• Fuzz session_parse ran 15 minutes with {} seeded: no crashes (17,652,390 executions), and {} is now a permanent CI seed (fuzz.yml's -seed_inputs=), not just a one-off local run.
• The wasm artifact re-pin and browser lineage are refreshed, against this branch's final head.

Gate output

Original round, rerun fresh on 816957af (rebased onto origin/main 65d83af5):

$ cargo test --locked -p session
running 13 tests (json_grammar.rs) ... 13 passed; 0 failed  (was 9; +4 new: empty_object_refuses_at_every_placement_instead_of_corrupting_the_code_map,
    canonical_minimal_empty_render_profile_reports_syntax_not_a_bogus_numeric_range,
    fuzz_crash_52d9c906_empty_render_profile_diagnoses_instead_of_aborting,
    minimal_two_member_object_with_an_empty_first_value_diagnoses_instead_of_aborting)
... every other session test file unchanged and green (allocation_budget, canonical_schema,
    diagnostic_parity, invalid_matrix, json_contract_artifacts, json_unicode, render_mode_tiers,
    sample_rate_tiers, scale_transaction, strict_unknowns, token_tables, visit_model)

$ cargo test --locked -p capi
running 30 tests (ffi::tests, was 29; +1 new: empty_object_document_is_diagnosed_not_aborted) ... ok
running 3 tests (resource_lifecycle.rs) ... ok

$ cargo test --locked -p host-web
running 62 tests (tests::*, was 61; +1 new: empty_object_document_boots_to_a_diagnostic_not_a_trap) ... ok
running 1 test (boot_transient_budget.rs) ... ok

$ bash scripts/check-session-policy.sh
session policy: ok

$ bash scripts/check-realtime-policy.sh
realtime policy: ok (7 marked regions)

$ bash scripts/check-workspace-policy.sh
workspace policy: ok

$ cargo clippy --locked -p session -p capi -p host-web --all-targets -- -D warnings
Finished `dev` profile [unoptimized + debuginfo] target(s) -- clean, zero warnings

$ cargo fmt --all -- --check
(no output, exit 0)

$ git diff --check
(no output, exit 0)

Verifier-requested round, rerun fresh on the final head (a52bdae0):

$ cargo test --locked -p session
[same 13/13 in json_grammar.rs, all session test files green; unaffected by comment/doc/fixture changes]

$ bash scripts/check-session-policy.sh
session policy: ok

$ RUSTDOCFLAGS="-D warnings" cargo doc --locked -p session -p capi -p host-web --no-deps
Documenting session v0.1.0
Documenting host-web v0.1.0
Documenting capi v0.1.0
Finished `dev` profile [unoptimized + debuginfo] target(s) -- clean, zero warnings
(no scripts/check-*docs*.sh exists in this repo; grepped scripts/ for "doc" -- none found)

$ cargo fmt --all -- --check
(no output, exit 0)

$ git diff --check
(no output, exit 0)

$ cargo clippy --locked -p session -p capi -p host-web --all-targets -- -D warnings
Finished `dev` profile [unoptimized + debuginfo] target(s) -- clean, zero warnings

$ cargo test --locked -p capi
[unchanged, 30+3 passed]

$ cargo test --locked -p host-web
[unchanged, 62+1 passed]

Wasm/qualification, both rounds (<dir> rebuilt fresh each time):

$ bash scripts/build-web-audioworklet.sh <dir>
[round 1: builds clean against 439ba6b5...; round 2: builds clean against f1f27d8d..., same 2,635,719 bytes]

$ bash scripts/check-web-audioworklet.sh <dir>
... web boot budget high-water gate passed; mismatches: 0
web AudioWorklet static/object checks passed

$ python3 scripts/check-browser-expected-resources.py
browser-correctness expected.json resource rows and digests agree with the built simd128 module,
  and the native witness agrees where the rows are target-independent
browser expected-resources self-test passed (26 red mutations)

$ npm run qualify -- --artifacts <dir> --browser all --record-matrix \
    --candidate-commit 12973933896823e30f5ad2c447d3f52455916b79 --self-test-mutations
session identities: 3 qualification documents declare their fed PCM
artifact set: the exact 6-file shipped set is pinned
chromium: all qualification gates passed (151.0.7922.34)
firefox: all qualification gates passed (153.0)
webkit: all qualification gates passed (26.5)
recorded results.json and ../BROWSER_DEPLOYMENT_MATRIX.md

$ npm run qualify -- --artifacts <dir> --browser all --check-matrix --self-test-mutations
chromium: all qualification gates passed (151.0.7922.34)
firefox: all qualification gates passed (153.0)
webkit: all qualification gates passed (26.5)

Fuzz (cargo-fuzz 0.13.2 installed; +nightly-2026-08-20 toolchain present):

$ export RUSTFLAGS='-C target-feature=+avx2,+fma'
$ cargo +nightly-2026-08-20 fuzz run session_parse target/ci/session-fuzz/parse -- \
    -max_total_time=900 -seed=1387387 fuzz/corpus/session_parse
[fuzz/corpus/session_parse seeded with 5 files: the canonical.json fixture, the three sed
 variants (render_profile/output_profile/a track's builtins each replaced by {}), and the
 minimal {"a":{},"b":1}]
Done 17652390 runs in 901 second(s)

$ ./target/x86_64-unknown-linux-gnu/release/session_parse fixtures/session/v1/fuzz-seeds/empty-object.json
Running: fixtures/session/v1/fuzz-seeds/empty-object.json
Executed fixtures/session/v1/fuzz-seeds/empty-object.json in 0 ms
[single-input smoke test of the now-committed CI seed: no crash]

17,652,390 executions, 0 crashes, 0 new artifacts (fuzz/artifacts/session_parse/ empty). ~19,600 exec/s sustained. The general mutation corpus directory (fuzz/corpus/session_parse/, 2,150 files after the run) is not committed, matching this workspace's existing convention for this target (only the curated protocol golden seeds under fuzz/corpus/protocol_* are checked in). What is now committed and wired into CI is the one deliberate {} seed (fixtures/session/v1/fuzz-seeds/empty-object.json), appended to fuzz.yml's -seed_inputs= for session_parse.

Workspace-wide counts (unchanged by the verifier-requested round -- no test-affecting files touched, only comments/docs/a fixture/a workflow/the pin):

cargo test --locked --workspace (branch, 816957af, on origin/main 65d83af5):
  1551 passed; 0 failed; 24 ignored; 273 result summaries

cargo test --locked --workspace (fresh origin/main worktree, 65d83af5):
  1545 passed; 0 failed; 24 ignored; 273 result summaries

Delta: +6 passed, 0 failed, 0 ignored -- exactly the 4 (session) + 1 (capi) + 1 (host-web) new
tests named above.

Before/after

Session-level ({"render_profile": {}} substituted into fixtures/session/v1/canonical.json, unmodified pre-fix tree):

thread 'main' panicked at .../json-syntax-0.12.5/src/object/mod.rs:795:67:
called `Option::unwrap()` on a `None` value
stack backtrace:
   ...
   8: <session::parse::Parser>::keys
             at ./crates/session/src/parse.rs:100:22
   9: session::parse::parse_track
  10: session::parse::parse_list::<session::model::Track>
  11: session::parse::parse_root
  12: session::parse::parse_session_json

After:

diagnostics (1):
  json.syntax at $.render_profile: empty JSON object {} is never a valid V1 schema value

canonical-minimal.json (before, unmodified tree -- the bogus diagnostics the issue named):

diagnostics (3):
  numeric.out_of_schema_range at $.output_profile.channels: expected an unsigned integer JSON number (span 199..209)
  schema.missing_field at $.render_profile.id: required key is absent (span 151..151)
  schema.missing_field at $.render_profile.mode: required key is absent (span 151..151)

After:

diagnostics (1):
  json.syntax at $.render_profile: empty JSON object {} is never a valid V1 schema value

(one clear diagnostic at the real fault, not a bogus range error plus two degenerate zero-width spans)

C API (miso_engine_v1_compile_session, nine-track fixture, render_profile emptied):

• Before: process abort (same panic as above, reached through compile_children -> parse_host_session -> parse_session_json; catch_result's catch_unwind cannot contain an abort under panic = "abort").
• After: RESULT_COMPILE_REJECTED, diagnostics bytes json.syntax\t$.render_profile\n. Verified in ffi::tests::empty_object_document_is_diagnosed_not_aborted.

Wasm boot path (AudioWorkletEngineHost::boot / miso_engine_web_v1_boot, one-track fixture, render_profile emptied):

• Before: the same panic, which traps the AudioWorklet module under the shipped --release (panic = "abort") build.
• After: RESULT_REFUSED_DOCUMENT, diagnostic json.syntax\t$.render_profile\n, through both the safe AudioWorkletEngineHost::boot call and the raw C ABI miso_engine_web_v1_boot entry point. Verified in tests::empty_object_document_boots_to_a_diagnostic_not_a_trap.

Wasm artifact digest and size (scripts/build-web-audioworklet.sh, miso-engine-v1-audio-worklet.simd128.wasm):

point	digest	bytes
before (origin/main 65d83af5, pre-#387)	22e4c25cba7f97b66db720ad8ac8cf653de0afcabe84101693f4fa166b90d4e6	2,636,176
after round 1 (816957af)	439ba6b513c5b1c9c2d1ff462d5cdd43136b0d70df540d4a21c238886d165958	2,635,719
after round 2, final (a52bdae0)	f1f27d8daa4c9f0828c9a3b2ca939bfdb507d041db6d7bc2a63ec6c826c1f74d	2,635,719

Round 1: -457 bytes from the new preflight branch (a handful of straight-line instructions, smaller than whatever code-size noise the change otherwise perturbed in the fat-LTO build). Round 2: 0 byte-count change, digest-only -- see "Documentation and comment corrections" item 5 for why a comment edit still moves a compiled panic-location constant.

Seen, not done

• Upstream json-syntax still has the bug (src/parse/object.rs:26-29 never calls end_fragment for the empty-object branch; the empty-array branch does). No upstream release exists to bump to. Per session aborts the host on untrusted JSON containing an empty object {} (parser CodeMap volume bug, reachable from C API and wasm boot) #387 itself, the upstream PR + a [patch] (option 3) is "in addition to 1, not instead" -- i.e. still owed, not excluded by the issue. It is not done in this PR because the coordinator scoped this PR to option 1 only and will open the follow-up issue for it. The bug is fully neutralized for this workspace by the preflight refusal in the meantime, since {} can never reach the parser's Value tree from parse_session_json any more, but a future direct consumer of json_syntax::Value::parse_str outside session's preflight boundary would still hit it.
• Option 2 (trusting volume == 0 as 1 in the typed walk) not implemented, per this PR's scope (not touching parse.rs's typed walk).
• The literal fuzz artifact crash-52d9c906ce5ad7f1d1e67dad91b13ec69e2caab5 named in the issue was not present on disk in this worktree (checked fuzz/artifacts/, the scratch directories named in the task, and did a filesystem-wide search). A content-equivalent input was found at the JSON-SYNTAX: replace the jstrict fork with upstream json-syntax in crates/session #385 verifier's own scratch path (render_profile reduced to whitespace-only content, still an empty object under the JSON grammar) and is used verbatim as the fuzz_crash_52d9c906_empty_render_profile_diagnoses_instead_of_aborting regression test and as the committed CI fuzz seed; it reproduces the identical pre-fix panic (verified on the unmodified tree before implementing the fix).
• Render-path/bit-identity/benchmark gates: not applicable. session, capi, and host-web are control-plane-only, and this PR touches no render arithmetic (docs/REALTIME_DEPENDENCY_POLICY.md's "Issue 004 control-plane parser dependencies" section already establishes session is not render-reachable).
• crates/capi/tests/resource_lifecycle.rs's exported_c_candidates_replay_render_and_both_destroy_orders_balance_exactly failure (left 2613, right 2610) predates this PR (present on main since JSON-SYNTAX: replace the jstrict fork with upstream json-syntax in crates/session #385) and is out of scope here per the coordinator's explicit instruction; it is being diagnosed separately.

Skipped

• Nothing else was skipped; every "Done when" item and every requested gate ran, across both review rounds.

Closes #387

🤖 Generated with Claude Code

https://claude.ai/code/session_01EwL1uTcxsmopHtamG6bMko

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}