feat(lua): reuse origin slices for materialized encode

[membphis]

Summary

• add opt-in qjson.materialize(value, { keep_origin = true }) provenance metadata
• teach qjson.encode to reuse safe original string/container slices for provenance-backed materialized tables
• preserve duplicate-key collapse, numeric normalization in changed parents, cycle/depth errors, and default materialize behavior

Closes #128

Test Plan

• make build && DYLD_LIBRARY_PATH="$PWD/target/release" LUA_PATH='./lua/?.lua;/usr/local/openresty/lualib/?.lua;/usr/local/openresty/lualib/?/init.lua;;' LUA_CPATH='./vendor/lua-cjson/?.so;./target/release/lib?.dylib;./target/release/lib?.so;./?.so;/usr/local/openresty/lualib/?.so;/usr/local/lib/lua/5.1/?.so;/usr/local/openresty/luajit/lib/lua/5.1/?.so' PATH="$HOME/.luarocks/bin:$PATH" busted --lua=$(command -v luajit) tests/lua/origin_materialize_spec.lua --lpath='./lua/?.lua'
• PATH="$HOME/.luarocks/bin:$PATH" make test
• make lint
• eval "$(luarocks --lua-version=5.1 --tree /tmp/lua-qjson-luacheck-5.1 path)" && luacheck lua tests/lua
• cargo test --release --no-default-features

Summary by CodeRabbit

• New Features

  • Added optional source origin tracking for materialized JSON data, enabling efficient reuse of original bytes when encoding unchanged table contents.

• Tests

  • Added test suite validating origin preservation behavior and encoding fallback logic.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d484ba7f-ac1d-4fc3-ad4e-e21556f48993

📥 Commits

Reviewing files that changed from the base of the PR and between c842041 and 5a5e3e0.

📒 Files selected for processing (2)

• lua/qjson/table.lua
• tests/lua/origin_materialize_spec.lua

---

📝 Walkthrough

Walkthrough

This PR extends lua-qjson's table materialization and encoding with optional provenance tracking and origin-aware byte reuse. A new keep_origin option captures source metadata during materialization, enabling the encoder to reuse original JSON bytes for unchanged content while safely detecting mutations, cycles, and depth violations.

Changes

Origin-aware materialization and encoding

Layer / File(s)	Summary
Foundation: TABLE_ORIGIN side-table and materialization refactoring lua/qjson/table.lua	A weak side-table TABLE_ORIGIN is introduced to register provenance metadata for materialized tables. The existing materialization logic is refactored into materialize_plain to support recursive reuse, and test infrastructure validates the default behavior and option-parsing.
Origin-preserving materialization with provenance capture lua/qjson/table.lua, tests/lua/origin_materialize_spec.lua	When keep_origin=true, materialization records byte offsets, per-element origin records, ordered keys, and duplicate-key counts in TABLE_ORIGIN. Comprehensive tests verify string/container reuse, duplicate-key prevention, numeric token handling, and preservation of prior lazy mutations applied before materialization.
Origin-aware encoding with byte-slice reuse and safety checks lua/qjson/table.lua, tests/lua/origin_materialize_spec.lua	The JSON encoder detects TABLE_ORIGIN provenance and attempts to reuse raw token bytes for scalars and source slices for fully matching containers. Circular-reference, max-depth, and mutation-visibility rules are enforced. Tests verify fallback behavior when provenance mismatches, enforcement of safety constraints, and source buffer lifetime.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• api7/lua-qjson#54: Both modify lua/qjson/table.lua's table-encoding path, especially encode_plain_table/encoder dispatch logic for JSON generation.
• api7/lua-qjson#71: Both modify encode_plain_table and the JSON encoding path with depth-aware and provenance-aware encoder changes.
• api7/lua-qjson#60: Both extend materialization and encoding logic in lua/qjson/table.lua, introducing provenance reuse (TABLE_ORIGIN) and ordered-key handling (ORDER_KEYS/ORDER_VALUES).

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main feature: enabling reuse of origin slices when encoding materialized JSON.
Linked Issues check	✅ Passed	The pull request implements the core requirements from issue #128: opt-in provenance API, metadata attachment, reuse safety rules, and deterministic ordering with comprehensive test coverage.
Out of Scope Changes check	✅ Passed	All changes are scoped to the materialization and encoding logic with accompanying tests, directly addressing issue #128 requirements without unrelated modifications.
E2e Test Quality Review	✅ Passed	14 E2E tests cover decode→materialize→encode flow with real services, error handling tested, assertions clear, tests independent, no mocking, solves issue #128.
Security Check	✅ Passed	TABLE_ORIGIN weak table is private and unexposed. Input validation enforces type checks. No sensitive data logs, auth flaws, TLS issues, or resource isolation concerns.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/issue-128-origin-reuse

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}