Make ToC channel lazy to avoid file creation at log_level 0

[lukstafi]

Summary

• Gate ToC file creation on log_level > 0 in shared_config (covers Flushing backend)
• Add lazy get_toc_ch() in PrintBox functor that creates the ToC file on first access using config.with_toc_listing/toc_flame_graph and debug_ch_name(), supporting runtime log_level changes
• Add for_append field to printbox_config so the lazy path respects the caller's open mode
• Add test verifying no files created at log_level 0 with with_toc_listing=true
• Shared_config public API unchanged (table_of_contents_ch : out_channel option)

Fixes #60

Test plan

• dune build @runtest-toc-no-file-at-level0 passes
• dune runtest passes (all existing tests, no regressions)
• Rebased onto latest main (includes PR Fix toc file truncation during snapshot_every_sec #104 snapshot_toc changes)

🤖 Generated with Claude Code

[lukstafi]

@codex review Focus on bugs, correctness issues, and edge cases. Do not check adherence to a spec or plan.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 81682f2f19

ℹ️ 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]

Keep ToC available after log level starts at 0

The new && log_level > 0 guard makes shared_config.table_of_contents_ch permanently None for file-backed debug_flushing runtimes created with ~log_level:0 ~with_table_of_contents:true. That runtime still allows logging later via Debug_runtime.log_level := ... (and can log level-0 entries immediately), but Flushing.close_log only emits ToC rows when table_of_contents_ch is Some, so ToC output is silently lost for the whole run in these cases.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Rewind lazy ToC channel during snapshots

Switching ToC writes to get_toc_ch () means snapshot code can now write to a lazily-created ToC file, but snapshot rewind still operates on Log_to.table_of_contents_ch from shared_config. When that field is None (e.g. runtime initialized with log_level=0), snapshot_ch/reset_to_snapshot never track the new channel, so periodic snapshots (snapshot_every_sec) can leave duplicate/stale ToC entries instead of rolling them back.

Useful? React with 👍 / 👎.

[lukstafi]

Retrospective: What I'd do differently

1. Clarify API-stability constraints upfront

This PR took 5 review rounds largely because I didn't ask early whether changing Shared_config was acceptable. Round 1 changed the type; round 2 reverted it; round 3 re-introduced it; round 4 finally found an approach that kept the API stable. Next time: before touching a public module type, check whether breaking changes are permitted and, if not, design the solution around that constraint from the start.

2. Consider the functor-internal lazy pattern first

The final approach — keeping Shared_config unchanged and adding lazy creation inside the PrintBox functor using its mutable config record — was available from round 1. The mutable config fields (with_toc_listing, toc_flame_graph) are set after functor creation but before any logging, making them ideal for deferred decisions inside a lazy block. This pattern (functor-internal lazy gated on mutable config) is reusable for similar problems in this codebase.

3. Don't forget snapshot interactions

The Codex review caught that snapshot_ch/reset_to_snapshot in shared_config didn't know about the lazily-created ToC channel. When adding a new channel-creation path, always audit all functions that flush/seek/rewind channels. A grep for the channel name across all backends would have caught this earlier.

4. Squash iterative commits before review

The 5-commit chain of back-and-forth changes made rebasing painful and the review history hard to follow. Next time: squash into a clean commit before requesting review, or at least before rebasing onto upstream.

5. Potential future cleanup

• The for_append field on printbox_config is only used by the lazy ToC path. If Shared_config is ever updated in a breaking release, for_append could move there instead, and the lazy ToC logic could move back to shared_config for both backends.
• The Flushing backend still uses the init-time log_level > 0 gate. If Flushing is kept beyond 3.0, it would need the same lazy treatment (likely via a similar functor-internal approach, though Flushing lacks a mutable config record today).