fuzz: 增加 cursor/token replay semantic fuzz

[membphis]

背景

父任务：#132

Go encoding/json/jsontext.FuzzCoder 会随机读取 token/value，再写回，并验证重放后的 JSON 与原输入语义一致。qjson 没有流式 token API，但 Phase 2 有 root getter、cursor、object entry、array index、path getter 和 skip-cache，这些读取路径同样需要语义级 fuzz 覆盖。

当前仓库已有 fuzz_parse_lazy：它以 serde_json::Value 为语义 oracle，通过 qjson public cursor FFI 重建完整 JSON model，并覆盖部分 varied-order sibling lookup。本 issue 收敛为增强现有 fuzz_parse_lazy，不新增独立 fuzz target。

目标

将 fuzz_parse_lazy 明确定义为 qjson Phase 2 semantic replay fuzz target，覆盖遍历、访问顺序、root/cursor getter 一致性和 skip-cache cold/warm 路径，验证不同 Phase 2 读取方式得到一致语义。

重点覆盖：

• root cursor 全量遍历并重建 JSON semantic model。
• qjson_cursor_object_entry_at 顺序遍历对象，覆盖所有 entry，包括 duplicate key。
• qjson_cursor_field 按 varied order 访问对象字段，覆盖同一 container 的 cold path / warm skip-cache path。
• qjson_cursor_index 按 varied order 访问数组元素，覆盖同一 container 的 cold path / warm skip-cache path。
• root getter 与 cursor getter 对同一路径结果一致。
• duplicate key、escaped key、path-like key、wide object、wide array、nested object/array、root scalar。

语义边界

• 语义 oracle 仍使用 serde_json::Value。
• 数字比较按 qjson getter 语义归一化为 f64，不把 serde 的 arbitrary precision number model 当作 qjson 承诺。
• object 的整体 semantic model 按 serde/qjson getter 可观察语义使用 last-wins。
• qjson_cursor_object_entry_at replay 必须保留并检查所有 object entries，包括 duplicate key。
• qjson_cursor_field / path getter 不对 duplicate key 断言等于 last-wins；duplicate key 通过顺序 entry replay 覆盖。
• root getter vs cursor getter 一致性只覆盖 qjson path 能无歧义表达的路径：路径上对象 key 在对应 parent 内唯一，且 key 不包含 ., [, ]。
• Lua mutation/materialize/encode 的 duplicate-key 行为不属于本 issue：未修改对象保留原有 key/value；一旦修改则 last-wins，这由 Lua lazy table / materialize 相关测试覆盖。

建议实现

• 继续增强 fuzz/fuzz_targets/fuzz_parse_lazy.rs，不新增独立 target。
• 保留当前 serde oracle + qjson cursor replay 主流程。
• replay object 时通过 qjson_cursor_object_entry_at 顺序读取全部 entries，并用 last-wins model 与 serde 比较。
• replay array 时通过 qjson_cursor_index 顺序重建，并额外用 varied order 重读元素。
• 对 unique key object，用 varied order 重复调用 qjson_cursor_field，并与 entry replay 得到的 value 比较，以明确覆盖 skip-cache cold/warm path。
• 在 replay 过程中收集 path-safe leaves/container paths；对这些路径分别调用 root getter 和从 root cursor 出发的 cursor getter，断言 type/value/错误行为一致。
• string 使用 *_get_str，number 使用 *_get_f64，bool 使用 *_get_bool，container/null 使用 *_typeof / *_len 等不解码 value 的 API。
• 对触发过 bug 的随机访问顺序，最小化后提交为 fuzz/corpus/fuzz_parse_lazy/ regression corpus。

CI 与文档

• PR CI 继续通过 cargo +nightly fuzz run fuzz_parse_lazy -- -runs=0 replay corpus。
• scheduled timed fuzz 继续运行 fuzz_parse_lazy。
• corpus seed 至少覆盖 escaped key、duplicate key、path-like key、wide object、wide array、nested object/array 和 root scalar。
• CONTRIBUTING.md 的 fuzzing 段落说明：fuzz_parse_lazy 是 Phase 2 semantic replay target，验证读取语义一致性；fuzz_parse_eager 验证 eager parse accept/reject；fuzz_ffi_ops 验证任意 FFI 操作序列的 panic-barrier 和 pointer-safety。

验收标准

• fuzz_parse_lazy 覆盖 cursor replay、object_entry_at 顺序遍历、varied-order field/index lookup、root/cursor getter 一致性。
• path getter 一致性仅覆盖 path-safe unique-key 路径；duplicate key 和 path-like key 通过 entry replay 覆盖。
• skip-cache warm path 有明确覆盖机制，并在文档中说明。
• PR CI 能 replay fuzz_parse_lazy corpus。
• scheduled timed fuzz 能运行 fuzz_parse_lazy。
• 文档说明 fuzz_parse_lazy 与 fuzz_parse_eager / fuzz_ffi_ops 的边界。
• 不把 Lua mutation/materialize/encode 的 duplicate-key 语义纳入本 issue。

[coderabbitai]

⚠️ Possible Duplicate Issue(s)

• test(fuzz): v2 lazy value-equality differential + Phase 2 walker #72

🔗 Related PRs

#54 - perf: Lua encode + cache + scanner + validation stack optimizations [merged]
#78 - test(fuzz): add nesting-depth stack-safety target [merged]
#93 - perf: add stateful object iterator [merged]
#105 - test: add lazy mutation property coverage [merged]
#141 - test: add FFI grammar corpus [closed]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[membphis]

规格已收敛：本 issue 改为增强现有 fuzz_parse_lazy，补 root/cursor getter 一致性，并明确 duplicate key、path-safe 路径、skip-cache 覆盖和与 fuzz_ffi_ops 的边界。

[membphis]

Phase 2 Semantic Replay Fuzz Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans. The recommended flow is: implement tasks with fresh subagents, run cheap local smoke checks, open a draft PR so CI starts, run consolidated reviews while CI runs, fix findings and CI failures, then mark the PR ready. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Strengthen the existing fuzz_parse_lazy target so it is the Phase 2 semantic replay fuzz target described in this issue.

Architecture: Keep one fuzz target: fuzz/fuzz_targets/fuzz_parse_lazy.rs. The target will still parse serde-accepted JSON, replay qjson through public cursor FFI, and compare the reconstructed semantic model to serde; it will additionally collect path-safe locations during replay and compare root getter APIs with cursor getter APIs for those locations. Duplicate keys remain covered by ordered object_entry_at replay, while path getter consistency only applies to unique-key paths that qjson path syntax can express unambiguously.

Tech Stack: Rust, cargo-fuzz/libFuzzer, serde_json::Value with float_roundtrip, qjson public FFI APIs, GitHub Actions corpus replay and scheduled timed fuzz.

---

File Structure

• Modify fuzz/fuzz_targets/fuzz_parse_lazy.rs: add path-safe path collection, expected value summaries, root-vs-cursor getter consistency assertions, and local helper tests.
• Create fuzz/corpus/fuzz_parse_lazy/path_safe_getters.json: targeted seed for string/number/bool/null/container getter consistency through path-safe keys and array indices.
• Modify CONTRIBUTING.md: document that fuzz_parse_lazy is the Phase 2 semantic replay target and clarify its boundary with fuzz_ffi_ops.
• Do not add a new fuzz target, do not change qjson FFI behavior, and do not cover Lua mutation/materialize duplicate-key behavior in this issue.

Cargo Note

Direct cargo test --manifest-path fuzz/Cargo.toml ... creates an untracked fuzz/Cargo.lock in this repository. Use it for fast helper tests, then remove that generated lockfile before staging:

rm -f fuzz/Cargo.lock

---

Task 1: Add Failing Helper Tests

Files:

• Modify: fuzz/fuzz_targets/fuzz_parse_lazy.rs

• Step 1: Add helper tests at the end of fuzz_parse_lazy.rs

Append this module after exceeds_container_depth:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn path_key_safety_rejects_qjson_path_delimiters() {
        assert!(path_key_can_be_in_qjson_path("plain"));
        assert!(path_key_can_be_in_qjson_path("emoji"));
        assert!(!path_key_can_be_in_qjson_path("a.b"));
        assert!(!path_key_can_be_in_qjson_path("arr[0]"));
        assert!(!path_key_can_be_in_qjson_path("bad]key"));
    }

    #[test]
    fn path_segment_builders_match_qjson_path_syntax() {
        let mut path = String::new();

        let root_len = path.len();
        append_key_segment(&mut path, "body");
        assert_eq!(path, "body");

        let body_len = path.len();
        append_key_segment(&mut path, "messages");
        assert_eq!(path, "body.messages");

        let messages_len = path.len();
        append_index_segment(&mut path, 12);
        assert_eq!(path, "body.messages[12]");

        path.truncate(messages_len);
        assert_eq!(path, "body.messages");
        path.truncate(body_len);
        assert_eq!(path, "body");
        path.truncate(root_len);
        assert_eq!(path, "");
    }

    #[test]
    fn expected_summary_records_getter_observable_values() {
        assert_eq!(PathExpected::from_value(&Value::Null), PathExpected::Null);
        assert_eq!(PathExpected::from_value(&Value::Bool(true)), PathExpected::Bool(true));
        assert_eq!(PathExpected::from_value(&serde_json::json!(1.5)), PathExpected::Number(1.5));
        assert_eq!(PathExpected::from_value(&serde_json::json!("x")), PathExpected::String("x".to_string()));
        assert_eq!(PathExpected::from_value(&serde_json::json!([1, 2, 3])), PathExpected::ArrayLen(3));
        assert_eq!(PathExpected::from_value(&serde_json::json!({"a": 1, "b": 2})), PathExpected::ObjectLen(2));
    }

    #[test]
    fn deterministic_replay_cases_cover_path_safe_and_ambiguous_keys() {
        fuzz_one(br#"{"body":{"model":"gpt","temperature":0.5,"ok":true,"none":null,"items":[{"id":1},{"id":2}]}}"#);
        fuzz_one(br#"{"dup":1,"dup":2,"a.b":3,"arr[0]":4,"nested":{"x":true}}"#);
        fuzz_one(br#"[{"name":"first"},{"name":"second","values":[1,2,3]}]"#);
    }
}

• Step 2: Run the first helper test and confirm it fails before implementation

Run:

cargo test --manifest-path fuzz/Cargo.toml --target-dir fuzz/target --bin fuzz_parse_lazy path_key_safety_rejects_qjson_path_delimiters -- --nocapture
rm -f fuzz/Cargo.lock

Expected: compilation fails with errors like cannot find function path_key_can_be_in_qjson_path in this scope.

• Step 3: Commit only after a later task makes the test pass

No commit in this task. The failing test is the red step for Task 2.

---

Task 2: Add Path-Safe Path and Expected Summary Helpers

Files:

• Modify: fuzz/fuzz_targets/fuzz_parse_lazy.rs

• Step 1: Add imports and constants near the top of fuzz_parse_lazy.rs

Change the imports/constants to include these lines:

use std::fmt::Write as _;

const FUZZ_MAX_DEPTH: u32 = 128;
const DEPTH_SKIP_LIMIT: u32 = 64;
const MAX_PATH_CHECKS: usize = 256;

const T_NULL: c_int = 0;
const T_BOOL: c_int = 1;
const T_NUM: c_int = 2;
const T_STR: c_int = 3;
const T_ARR: c_int = 4;
const T_OBJ: c_int = 5;

Remove the old duplicate FUZZ_MAX_DEPTH and DEPTH_SKIP_LIMIT definitions if they remain after editing.

• Step 2: Add path-check data structures and helpers after normalize_numbers

Insert this code after normalize_numbers:

#[derive(Clone, Debug, PartialEq)]
struct PathCheck {
    path: Vec<u8>,
    expected: PathExpected,
}

#[derive(Clone, Debug, PartialEq)]
enum PathExpected {
    Null,
    Bool(bool),
    Number(f64),
    String(String),
    ArrayLen(usize),
    ObjectLen(usize),
}

impl PathExpected {
    fn from_value(value: &Value) -> Self {
        match value {
            Value::Null => Self::Null,
            Value::Bool(value) => Self::Bool(*value),
            Value::Number(number) => {
                Self::Number(number.as_f64().expect("normalized qjson number must fit f64"))
            }
            Value::String(value) => Self::String(value.clone()),
            Value::Array(items) => Self::ArrayLen(items.len()),
            Value::Object(map) => Self::ObjectLen(map.len()),
        }
    }

    fn type_tag(&self) -> c_int {
        match self {
            Self::Null => T_NULL,
            Self::Bool(_) => T_BOOL,
            Self::Number(_) => T_NUM,
            Self::String(_) => T_STR,
            Self::ArrayLen(_) => T_ARR,
            Self::ObjectLen(_) => T_OBJ,
        }
    }
}

fn path_key_can_be_in_qjson_path(key: &str) -> bool {
    !key.as_bytes().iter().any(|&byte| matches!(byte, b'.' | b'[' | b']'))
}

fn append_key_segment(path: &mut String, key: &str) -> usize {
    let old_len = path.len();
    if old_len != 0 {
        path.push('.');
    }
    path.push_str(key);
    old_len
}

fn append_index_segment(path: &mut String, index: usize) -> usize {
    let old_len = path.len();
    write!(path, "[{index}]").expect("writing to String cannot fail");
    old_len
}

fn record_path_check(path_checks: &mut Vec<PathCheck>, path: &str, value: &Value) {
    if path_checks.len() >= MAX_PATH_CHECKS {
        return;
    }
    path_checks.push(PathCheck {
        path: path.as_bytes().to_vec(),
        expected: PathExpected::from_value(value),
    });
}

• Step 3: Run helper tests and confirm they pass

Run:

cargo test --manifest-path fuzz/Cargo.toml --target-dir fuzz/target --bin fuzz_parse_lazy path_key_safety_rejects_qjson_path_delimiters -- --nocapture
cargo test --manifest-path fuzz/Cargo.toml --target-dir fuzz/target --bin fuzz_parse_lazy path_segment_builders_match_qjson_path_syntax -- --nocapture
cargo test --manifest-path fuzz/Cargo.toml --target-dir fuzz/target --bin fuzz_parse_lazy expected_summary_records_getter_observable_values -- --nocapture
rm -f fuzz/Cargo.lock

Expected: all three tests pass.

• Step 4: Commit the helper layer

git add fuzz/fuzz_targets/fuzz_parse_lazy.rs
git commit -m "test: add lazy fuzz path helper coverage"

---

Task 3: Collect Path-Safe Locations During Cursor Replay

Files:

• Modify: fuzz/fuzz_targets/fuzz_parse_lazy.rs

• Step 1: Change fuzz_one to collect path checks while the doc is alive

Replace the let actual = unsafe { ... }; block in fuzz_one with:

    let (actual, path_checks) = unsafe {
        let mut root: qjson_cursor = std::mem::zeroed();
        let rc = qjson_open(doc, ptr::null(), 0, &mut root);
        assert_eq!(rc, 0, "qjson_open root failed with rc={rc}: {data:?}");

        let mut path = String::new();
        let mut path_checks = Vec::new();
        let actual = cursor_to_value(&root, 0, &mut path, true, &mut path_checks);
        assert!(
            !path_checks.is_empty(),
            "semantic replay must record at least the root path for input={data:?}",
        );
        qjson_free(doc);
        (actual, path_checks)
    };

This temporarily collects checks without consuming them. Task 4 will verify them before qjson_free, so this block will be edited again there.

• Step 2: Replace cursor_to_value with a path-aware version

Replace the existing cursor_to_value function with:

unsafe fn cursor_to_value(
    cur: &qjson_cursor,
    depth: u32,
    path: &mut String,
    path_safe: bool,
    path_checks: &mut Vec<PathCheck>,
) -> Value {
    assert!(depth <= FUZZ_MAX_DEPTH, "walker exceeded depth limit");
    let value = match cursor_type(cur) {
        T_NULL => Value::Null,
        T_BOOL => Value::Bool(cursor_bool(cur)),
        T_NUM => Value::Number(cursor_number(cur)),
        T_STR => Value::String(cursor_string(cur)),
        T_ARR => Value::Array(cursor_array(cur, depth + 1, path, path_safe, path_checks)),
        T_OBJ => Value::Object(cursor_object(cur, depth + 1, path, path_safe, path_checks)),
        other => panic!("unknown qjson type {other}"),
    };

    if path_safe {
        record_path_check(path_checks, path, &value);
    }

    value
}

• Step 3: Replace array replay helpers with path-aware versions

Replace cursor_array and cursor_index_value with:

unsafe fn cursor_array(
    cur: &qjson_cursor,
    depth: u32,
    path: &mut String,
    path_safe: bool,
    path_checks: &mut Vec<PathCheck>,
) -> Vec<Value> {
    let len = cursor_len(cur);
    let mut values = Vec::with_capacity(len);
    for i in 0..len {
        values.push(cursor_index_value(cur, i, depth, path, path_safe, path_checks));
    }

    for i in varied_order(len) {
        let mut scratch_path = String::new();
        let _ = cursor_index_value(cur, i, depth, &mut scratch_path, false, path_checks);
    }

    values
}

unsafe fn cursor_index_value(
    cur: &qjson_cursor,
    index: usize,
    depth: u32,
    path: &mut String,
    path_safe: bool,
    path_checks: &mut Vec<PathCheck>,
) -> Value {
    let mut child: qjson_cursor = std::mem::zeroed();
    let rc = qjson_cursor_index(cur, index, &mut child);
    assert_eq!(rc, 0, "qjson_cursor_index({index}) failed with rc={rc}");

    let old_len = if path_safe {
        append_index_segment(path, index)
    } else {
        path.len()
    };
    let value = cursor_to_value(&child, depth, path, path_safe, path_checks);
    path.truncate(old_len);
    value
}

• Step 4: Replace object replay with two-pass entry collection

Replace cursor_object with:

unsafe fn cursor_object(
    cur: &qjson_cursor,
    depth: u32,
    path: &mut String,
    path_safe: bool,
    path_checks: &mut Vec<PathCheck>,
) -> Map<String, Value> {
    let len = cursor_len(cur);
    let mut map = Map::new();
    let mut raw_entries = Vec::with_capacity(len);
    let mut entries = Vec::with_capacity(len);
    let mut counts: HashMap<String, usize> = HashMap::with_capacity(len);

    for i in 0..len {
        let (key, value_cur) = cursor_object_entry_at(cur, i);
        *counts.entry(key.clone()).or_insert(0) += 1;
        raw_entries.push((key, value_cur));
    }

    for (key, value_cur) in raw_entries {
        let child_path_safe = path_safe
            && counts.get(&key).copied().unwrap_or(0) == 1
            && path_key_can_be_in_qjson_path(&key);
        let old_len = if child_path_safe {
            append_key_segment(path, &key)
        } else {
            path.len()
        };

        let value = cursor_to_value(&value_cur, depth, path, child_path_safe, path_checks);
        path.truncate(old_len);

        map.insert(key.clone(), value.clone());
        entries.push((key, value));
    }

    for i in varied_order(entries.len()) {
        let (key, expected) = &entries[i];
        if counts.get(key).copied().unwrap_or(0) != 1 {
            continue;
        }

        let mut child: qjson_cursor = std::mem::zeroed();
        let rc = qjson_cursor_field(cur, key.as_ptr() as *const c_char, key.len(), &mut child);
        assert_eq!(rc, 0, "qjson_cursor_field({key:?}) failed with rc={rc}");

        let mut scratch_path = String::new();
        let actual = cursor_to_value(&child, depth, &mut scratch_path, false, path_checks);
        assert_eq!(actual, *expected, "qjson_cursor_field warm lookup mismatch for key {key:?}");
    }

    map
}

• Step 5: Run deterministic tests and corpus replay compile

Run:

cargo test --manifest-path fuzz/Cargo.toml --target-dir fuzz/target --bin fuzz_parse_lazy deterministic_replay_cases_cover_path_safe_and_ambiguous_keys -- --nocapture
cargo test --manifest-path fuzz/Cargo.toml --target-dir fuzz/target --bin fuzz_parse_lazy -- --nocapture
rm -f fuzz/Cargo.lock

Expected: all tests pass. path_checks may be unused after collection in this task; if Rust warns, leave it for Task 4 where the checks are consumed.

• Step 6: Commit path collection

git add fuzz/fuzz_targets/fuzz_parse_lazy.rs
git commit -m "test: collect path-safe lazy fuzz locations"

---

Task 4: Compare Root Getter and Cursor Getter Results

Files:

• Modify: fuzz/fuzz_targets/fuzz_parse_lazy.rs

• Step 1: Keep the document alive while verifying path checks

In fuzz_one, replace the Task 3 unsafe block with:

    let actual = unsafe {
        let mut root: qjson_cursor = std::mem::zeroed();
        let rc = qjson_open(doc, ptr::null(), 0, &mut root);
        assert_eq!(rc, 0, "qjson_open root failed with rc={rc}: {data:?}");

        let mut path = String::new();
        let mut path_checks = Vec::new();
        let actual = cursor_to_value(&root, 0, &mut path, true, &mut path_checks);
        assert!(
            !path_checks.is_empty(),
            "semantic replay must record at least the root path for input={data:?}",
        );
        verify_path_getter_consistency(doc, &root, &path_checks);
        qjson_free(doc);
        actual
    };

• Step 2: Replace cursor_type with a wrapper around path-aware type lookup

Replace the existing cursor_type helper with:

unsafe fn cursor_type(cur: &qjson_cursor) -> c_int {
    cursor_type_at(cur, &[])
}

unsafe fn cursor_type_at(cur: &qjson_cursor, path: &[u8]) -> c_int {
    let mut ty: c_int = -1;
    let (path_ptr, path_len) = ffi_path(path);
    let rc = qjson_cursor_typeof(cur, path_ptr, path_len, &mut ty);
    assert_eq!(rc, 0, "qjson_cursor_typeof({:?}) failed with rc={rc}", path_debug(path));
    ty
}

• Step 3: Add root/cursor getter verification helpers after cursor_object_entry_at

Insert this code after cursor_object_entry_at:

unsafe fn verify_path_getter_consistency(
    doc: *mut qjson_doc,
    root: &qjson_cursor,
    path_checks: &[PathCheck],
) {
    for check in path_checks {
        let root_ty = root_type(doc, &check.path);
        let cursor_ty = cursor_type_at(root, &check.path);
        assert_eq!(
            root_ty,
            cursor_ty,
            "root/cursor typeof mismatch at path {:?}",
            path_debug(&check.path),
        );
        assert_eq!(
            root_ty,
            check.expected.type_tag(),
            "getter type mismatch against replay model at path {:?}",
            path_debug(&check.path),
        );

        match &check.expected {
            PathExpected::Null => {}
            PathExpected::Bool(expected) => {
                let root_value = root_bool(doc, &check.path);
                let cursor_value = cursor_bool_at(root, &check.path);
                assert_eq!(root_value, cursor_value, "root/cursor bool mismatch at path {:?}", path_debug(&check.path));
                assert_eq!(root_value, *expected, "bool mismatch against replay model at path {:?}", path_debug(&check.path));
            }
            PathExpected::Number(expected) => {
                let root_value = root_number(doc, &check.path);
                let cursor_value = cursor_number_at(root, &check.path);
                assert_eq!(root_value.to_bits(), cursor_value.to_bits(), "root/cursor number mismatch at path {:?}", path_debug(&check.path));
                assert_eq!(root_value.to_bits(), expected.to_bits(), "number mismatch against replay model at path {:?}", path_debug(&check.path));
            }
            PathExpected::String(expected) => {
                let root_value = root_string(doc, &check.path);
                let cursor_value = cursor_string_at(root, &check.path);
                assert_eq!(root_value, cursor_value, "root/cursor string mismatch at path {:?}", path_debug(&check.path));
                assert_eq!(root_value, *expected, "string mismatch against replay model at path {:?}", path_debug(&check.path));
            }
            PathExpected::ArrayLen(expected) | PathExpected::ObjectLen(expected) => {
                let root_value = root_len(doc, &check.path);
                let cursor_value = cursor_len_at(root, &check.path);
                assert_eq!(root_value, cursor_value, "root/cursor len mismatch at path {:?}", path_debug(&check.path));
                assert_eq!(root_value, *expected, "len mismatch against replay model at path {:?}", path_debug(&check.path));
            }
        }
    }
}

fn ffi_path(path: &[u8]) -> (*const c_char, usize) {
    if path.is_empty() {
        (ptr::null(), 0)
    } else {
        (path.as_ptr() as *const c_char, path.len())
    }
}

fn path_debug(path: &[u8]) -> String {
    String::from_utf8_lossy(path).into_owned()
}

unsafe fn root_type(doc: *mut qjson_doc, path: &[u8]) -> c_int {
    let mut ty: c_int = -1;
    let (path_ptr, path_len) = ffi_path(path);
    let rc = qjson_typeof(doc, path_ptr, path_len, &mut ty);
    assert_eq!(rc, 0, "qjson_typeof({:?}) failed with rc={rc}", path_debug(path));
    ty
}

unsafe fn root_bool(doc: *mut qjson_doc, path: &[u8]) -> bool {
    let mut value: c_int = -1;
    let (path_ptr, path_len) = ffi_path(path);
    let rc = qjson_get_bool(doc, path_ptr, path_len, &mut value);
    assert_eq!(rc, 0, "qjson_get_bool({:?}) failed with rc={rc}", path_debug(path));
    value != 0
}

unsafe fn cursor_bool_at(cur: &qjson_cursor, path: &[u8]) -> bool {
    let mut value: c_int = -1;
    let (path_ptr, path_len) = ffi_path(path);
    let rc = qjson_cursor_get_bool(cur, path_ptr, path_len, &mut value);
    assert_eq!(rc, 0, "qjson_cursor_get_bool({:?}) failed with rc={rc}", path_debug(path));
    value != 0
}

unsafe fn root_number(doc: *mut qjson_doc, path: &[u8]) -> f64 {
    let mut value = 0.0f64;
    let (path_ptr, path_len) = ffi_path(path);
    let rc = qjson_get_f64(doc, path_ptr, path_len, &mut value);
    assert_eq!(rc, 0, "qjson_get_f64({:?}) failed with rc={rc}", path_debug(path));
    value
}

unsafe fn cursor_number_at(cur: &qjson_cursor, path: &[u8]) -> f64 {
    let mut value = 0.0f64;
    let (path_ptr, path_len) = ffi_path(path);
    let rc = qjson_cursor_get_f64(cur, path_ptr, path_len, &mut value);
    assert_eq!(rc, 0, "qjson_cursor_get_f64({:?}) failed with rc={rc}", path_debug(path));
    value
}

unsafe fn root_string(doc: *mut qjson_doc, path: &[u8]) -> String {
    let mut ptr_out: *const u8 = ptr::null();
    let mut len_out: usize = 0;
    let (path_ptr, path_len) = ffi_path(path);
    let rc = qjson_get_str(doc, path_ptr, path_len, &mut ptr_out, &mut len_out);
    assert_eq!(rc, 0, "qjson_get_str({:?}) failed with rc={rc}", path_debug(path));
    let bytes = std::slice::from_raw_parts(ptr_out, len_out).to_vec();
    String::from_utf8(bytes).expect("serde accepted string must decode as UTF-8")
}

unsafe fn cursor_string_at(cur: &qjson_cursor, path: &[u8]) -> String {
    let mut ptr_out: *const u8 = ptr::null();
    let mut len_out: usize = 0;
    let (path_ptr, path_len) = ffi_path(path);
    let rc = qjson_cursor_get_str(cur, path_ptr, path_len, &mut ptr_out, &mut len_out);
    assert_eq!(rc, 0, "qjson_cursor_get_str({:?}) failed with rc={rc}", path_debug(path));
    let bytes = std::slice::from_raw_parts(ptr_out, len_out).to_vec();
    String::from_utf8(bytes).expect("serde accepted string must decode as UTF-8")
}

unsafe fn root_len(doc: *mut qjson_doc, path: &[u8]) -> usize {
    let mut len = 0usize;
    let (path_ptr, path_len) = ffi_path(path);
    let rc = qjson_len(doc, path_ptr, path_len, &mut len);
    assert_eq!(rc, 0, "qjson_len({:?}) failed with rc={rc}", path_debug(path));
    len
}

unsafe fn cursor_len_at(cur: &qjson_cursor, path: &[u8]) -> usize {
    let mut len = 0usize;
    let (path_ptr, path_len) = ffi_path(path);
    let rc = qjson_cursor_len(cur, path_ptr, path_len, &mut len);
    assert_eq!(rc, 0, "qjson_cursor_len({:?}) failed with rc={rc}", path_debug(path));
    len
}

• Step 4: Run helper and corpus replay checks

Run:

cargo test --manifest-path fuzz/Cargo.toml --target-dir fuzz/target --bin fuzz_parse_lazy -- --nocapture
rm -f fuzz/Cargo.lock
cargo +nightly fuzz run fuzz_parse_lazy -- -runs=0

Expected: tests pass and corpus replay exits successfully.

• Step 5: Commit getter consistency

git add fuzz/fuzz_targets/fuzz_parse_lazy.rs
git commit -m "test: compare lazy root and cursor getters"

---

Task 5: Add Targeted Corpus Seed and Documentation

Files:

• Create: fuzz/corpus/fuzz_parse_lazy/path_safe_getters.json

• Modify: CONTRIBUTING.md

• Step 1: Create targeted corpus seed

Create fuzz/corpus/fuzz_parse_lazy/path_safe_getters.json with exactly:

{"body":{"model":"gpt","temperature":0.5,"ok":true,"none":null,"items":[{"id":1,"name":"first"},{"id":2,"name":"second"}],"meta":{"count":2}},"status":"done"}

• Step 2: Update CONTRIBUTING.md fuzz target description

Replace the existing fuzz_parse_lazy paragraph with:

The `fuzz_parse_lazy` target is the Phase 2 semantic replay target. It compares
serde-accepted inputs by reconstructing a whole `serde_json::Value` through
qjson's public cursor FFI APIs, including ordered `object_entry_at` replay,
varied-order `cursor_field` / `cursor_index` lookups, and root getter vs cursor
getter consistency for path-safe unique-key paths. It normalizes numbers through
qjson's `f64` getter semantics, with serde_json's `float_roundtrip` parser
enabled for bit-exact `f64` oracle comparisons. Duplicate keys and path-like
keys are covered by ordered entry replay; they are not used for path getter
consistency because qjson path syntax cannot express those object members
unambiguously. Repeated varied-order sibling lookups exercise both cold and warm
skip-cache paths.

• Step 3: Replay the new seed and all corpus entries

Run:

cargo +nightly fuzz run fuzz_parse_lazy fuzz/corpus/fuzz_parse_lazy/path_safe_getters.json -- -runs=1
cargo +nightly fuzz run fuzz_parse_lazy -- -runs=0

Expected: both commands pass.

• Step 4: Commit corpus and docs

git add fuzz/corpus/fuzz_parse_lazy/path_safe_getters.json CONTRIBUTING.md
git commit -m "docs: clarify lazy fuzz semantic replay"

---

Task 6: Final Verification

Files:

• Verify all modified files from previous tasks.

• Step 1: Run fuzz target tests

cargo test --manifest-path fuzz/Cargo.toml --target-dir fuzz/target --bin fuzz_parse_lazy -- --nocapture
rm -f fuzz/Cargo.lock

Expected: all fuzz_parse_lazy helper tests pass.

• Step 2: Run fuzz corpus replay

cargo +nightly fuzz run fuzz_parse_lazy -- -runs=0

Expected: all committed fuzz_parse_lazy corpus entries replay successfully.

• Step 3: Run a PR-length timed fuzz smoke for the touched target

cargo +nightly fuzz run fuzz_parse_lazy -- -max_total_time=60

Expected: exits without crash.

• Step 4: Run clippy on the fuzz crate

cargo clippy --manifest-path fuzz/Cargo.toml --target-dir fuzz/target --all-targets -- -D warnings
rm -f fuzz/Cargo.lock

Expected: clippy exits with no warnings.

• Step 5: Run the repository lint gate

make lint

Expected: clippy for the main crate exits with no warnings.

• Step 6: Confirm no generated lockfile is staged

git status --short

Expected: staged or unstaged changes only include:

fuzz/fuzz_targets/fuzz_parse_lazy.rs
fuzz/corpus/fuzz_parse_lazy/path_safe_getters.json
CONTRIBUTING.md

fuzz/Cargo.lock must not appear.

---

Plan Self-Review

• Spec coverage: Task 3 covers cursor replay, object_entry_at, varied-order field/index lookup, duplicate-key entry replay, and skip-cache warm paths. Task 4 covers root getter vs cursor getter consistency on path-safe unique-key paths. Task 5 covers corpus and documentation. Task 6 covers CI-equivalent verification.
• No unresolved markers: the plan avoids deferred sections and gives concrete code, paths, commands, and expected outcomes.
• Type consistency: helper names used by tests in Task 1 are defined in Task 2; path-aware replay signatures introduced in Task 3 are the signatures consumed by Task 4; FFI helper names match the exported qjson APIs in src/ffi.rs.