Fix RecursionError crashes in JSON/Kconfig parsers, phantom JSONL events, add PyPI publish workflow and README example

[Copilot]

Three bugs that violate the "nothing is silently dropped" contract, plus two adoption improvements.

Bugs fixed

Unbounded recursion in JSON and Kconfig parsers

Both json_parser.py and kconfig.py used recursive inner visit() closures. At ~950 nesting levels, Python raises RecursionError, which session_scope catches, rolls back the entire batch transaction, and re-raises — leaving every file in that batch with no artifact record and no diagnostic. Fixed by converting both to explicit stack-based iterative traversal.

Phantom JSONL events on DB commit failure

append_event wrote to events.jsonl inside the session_scope try block, before session.commit(). A failed commit rolled back SQLite but left the JSONL file with a record of an event that never happened. Fixed by moving the write into a SQLAlchemy after_commit hook — the file is only touched after the transaction durably commits. OSError on the post-commit write is suppressed (event is already safe in SQLite; JSONL is a best-effort mirror).

@event.listens_for(session, "after_commit", once=True)
def _write_jsonl(_session: Session) -> None:
    try:
        with events_path.open("a", encoding="utf-8") as f:
            f.write(line + "\n")
    except OSError:
        pass  # DB commit succeeded; JSONL mirror is best-effort

Regression tests added for both parsers at 1,100-level nesting depth.

Adoption improvements

PyPI publish workflow

.github/workflows/publish.yml — OIDC trusted-publisher; triggers on GitHub Release creation. No stored secrets required; one-time setup documented in the workflow file comments.

README worked example

Added a concrete five-command walkthrough showing CONFIG_WIFI_POWER_SAVE traced across a Kconfig tree, Markdown changelog, and PDF release notes — illustrating the cross-document trace value proposition immediately on landing.

[Copilot]

Pull request overview

This pull request addresses reliability issues in the JSON and Kconfig parsers (avoiding RecursionError on deeply nested inputs) and fixes event-mirroring correctness so JSONL event records are not written when the DB transaction fails. It also improves adoption by adding a PyPI publish workflow and a concrete README walkthrough.

Changes:

• Replace recursive traversal in json_parser.py and kconfig.py with an explicit stack-based traversal to avoid Python recursion limits.
• Prevent “phantom” JSONL events by deferring events.jsonl writes until SQLAlchemy after_commit.
• Add regression tests for 1,100-level nesting, plus a PyPI publish workflow and a README worked example.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/kairos/infrastructure/parsers/json_parser.py	Switch JSON traversal to iterative stack walk to avoid recursion depth crashes; adjusts containment emission to work without recursion.
src/kairos/infrastructure/parsers/kconfig.py	Switch Kconfig menu-tree traversal to iterative stack walk to avoid recursion depth crashes.
src/kairos/services/events.py	Write JSONL event mirror only after a successful DB commit via after_commit hook.
tests/unit/test_parsers_json.py	Add regression test ensuring deeply nested JSON parses without RecursionError.
tests/unit/test_parsers_kconfig.py	Add regression test ensuring deeply nested Kconfig JSON parses without RecursionError.
README.md	Add a concrete “worked example” walkthrough demonstrating cross-document tracing.
.github/workflows/publish.yml	Add GitHub Release-triggered PyPI publish workflow using OIDC trusted publishing.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c6453bf369

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Correct the trace walkthrough's cross-document edge

In the walkthrough as written, once the Kconfig JSON is ingested, kairos trace CONFIG_WIFI_POWER_SAVE --depth 3 will seed from the exact Kconfig entity and return before the FTS fallback (src/kairos/services/trace.py:95-100), while Markdown only creates heading entities/mentions and the paragraph hit shown above is just a span (src/kairos/infrastructure/parsers/text_markdown.py:103-115). That means the changelog/PDF search hits are not in the trace frontier, so the documented heading_contains edge into docs/changelog.md won't appear for users copying these commands unless the example starts from a span/heading shared by the docs or the trace seeding behavior changes.

Useful? React with 👍 / 👎.

[Jacobcdsmith]

@copilot Fix the code for all comments in this review thread.

When a review comment includes a suggested change, apply the suggestion exactly.

Do not make changes beyond what is described in the linked review thread.

[Copilot]

@copilot Fix the code for all comments in this review thread.

When a review comment includes a suggested change, apply th...

All four review items addressed in the latest commit:

1. json_parser.py line 67 — corrected "BFS/DFS" to "DFS".
2. json_parser.py line 119 — replaced reversed(list(value.keys())) with reversed(value) to avoid the intermediate list allocation.
3. publish.yml lines 53-55 — added contents: read alongside id-token: write in the publish job permissions.
4. publish.yml lines 11-15 — replaced hard-coded Jacobcdsmith/kairos with <your-github-owner>/<your-repo-name> placeholders.