feat(examples): demonstrate prmi_collect_smems in the C driver

[nh13]

Sibling PR 2 of 2 (#41 adds the Rust collect_gate profiling harness). Adds the C usage example for the fused per-read SMEM collector.

What

Extend the cpp_caller FFI smoke with a prmi_collect_smems block that does double duty:

• Shape coverage — prmi_collect_smems / prmi_collect_opts_t / prmi_smem_t had no C-side exercise; this catches FFI shape regressions in CI (the examples/cpp_caller job builds against the cbindgen-generated prmi.h and runs run_smoke.sh).
• Usage demonstration — the idiomatic C calling pattern a consumer adopting the fused entrypoint must implement:
  • prmi_collect_opts_t setup (max_mem_intv > 0 enables pass 3);
  • the out_cap = 0 size-probe (rc -4 with *out_n = required count);
  • the grow-on--4 retry loop (resize(*out_n), retry) — the buffer-sizing contract;
  • iterating the returned prmi_smem_t[] and validating each (rid / span / occ).

Verification

run_smoke.sh passes: size-probe rc=-4 needed=1, then one well-formed SMEM spanning the reference-derived 60-base read (rid=7 m=0 n=59 …), all 1 SMEMs well-formed — OK, cpp_caller exited 0 — smoke PASSED. Compiled -Wall -Wextra clean; every error path closes the index (no handle leak). Example only — no production code. Pre-PR /coderabbitai-review: 0 findings.

Summary by CodeRabbit

• Documentation
  • Enhanced C ABI usage examples with clearer documentation of the idiomatic calling pattern
  • Added comprehensive usage example demonstrating proper initialization, size probing, buffer allocation, and result validation for SMEM collection functionality

[coderabbitai]

Walkthrough

examples/cpp_caller.cc updates its top-of-file comments and adds an 87-line prmi_collect_smems demonstration block that builds a packed-PAC-derived read, initializes prmi_collect_opts_t, performs a size-probe call, executes the grow-on--4 retry loop, and validates each returned prmi_smem_t.

Changes

prmi_collect_smems example driver

Layer / File(s)	Summary
Header comments and prmi_collect_smems demo block examples/cpp_caller.cc	File-level comments clarified; new block appended to the spectrum smoke section covering opts init, nullptr/0 size probe, -4 grow/retry loop with dynamic vector resize, result printing, and per-SMEM validation of rid, m/n/s relationships, and span values.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• fg-labs/prmi#32: Introduced prmi_collect_smems and prmi_collect_opts_t that this example directly exercises, including the -4/needed-count retry contract being demonstrated here.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly describes the main change: adding a demonstration of the prmi_collect_smems function in the C driver example file.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ 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/v0.3-collect-c-example

---

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.}

[nh13]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@examples/cpp_caller.cc`:
- Line 383: The span validation condition currently uses `s.n < s.m` which only
catches backwards intervals but allows zero-length spans where `s.n == s.m`.
Change the comparison operator in this validation check from `<` to `<=` so that
the condition becomes `s.n <= s.m`, which will properly reject both backwards
and zero-length intervals that are unexpected for a reference-derived read.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: d59af7de-7050-4bb7-857b-b3c7808360f1

📥 Commits

Reviewing files that changed from the base of the PR and between 7da93a5 and 65cc435.

📒 Files selected for processing (1)

• examples/cpp_caller.cc