Record pause point for PR 132 review

Author: gregorgorjanc

PR132_REVIEW_PLAN.md

@@ -1,5 +1,43 @@
 # PR #132 API Review Plan
 
+## Pause handoff (2026-08-21)
+
+The review is deliberately paused at the start of variant iteration while
+Gregor is away and until the intended user-facing design has been discussed
+with Jinyang. This is a clean review boundary, not an indication that the
+variant implementation has been approved.
+
+Completed review slices are node and remaining table-row access, table-row
+appenders, tree-sequence sample access, table-collection sorting, and table-
+collection/tree-sequence simplification. Their detailed notes are retained in
+the companion review-plan files.
+
+The next work is **section 7, low-level variant iteration**. Resume with
+iterator state, initialization, ownership, and cleanup in
+`PR132_REVIEW_PLAN_variants.md`; then review decoding and exhaustion; only then
+review the user-facing `TreeSequence$variants()` API. Do not restart the review
+from the beginning of the PR.
+
+Before continuing, ask Jinyang for:
+
+- concise user-facing documentation for the intended variants workflow;
+- one or two executable examples, including expected returned content and the
+  AlphaSimR use case;
+- the intended public API and compatibility requirements, particularly which
+  iterator methods and arguments downstream code needs.
+
+The local review branch was clean at commit `ac89284` before this handoff note
+was added. At that point it contained ten review commits beyond PR #132's head
+commit `24509d1`, and the latest commit had not yet been pushed to Gregor's
+`origin/lynx-clean-work`. PR #132 is open from
+`LynxJinyangii:add-multiple-functions-on-pr-131` into
+`HighlanderLab:main`; pushing this review branch to Gregor's fork does not by
+itself update the PR.
+
+After variants are agreed and reviewed, complete section 9 cross-cutting
+cleanup and all final quality gates. No final full-package quality-gate result
+is claimed by this pause handoff.
+
 ## Goal
 
 Review and polish PR #132 function by function before it is merged into

PR132_REVIEW_PLAN_variants.md

@@ -2,9 +2,44 @@
 
 ## Status
 
-In progress. The low-level iterator-state documentation and ownership model are
-under review. Continue with the finalizer and initializer, then review decoding
-and exhaustion, and only then review `TreeSequence$variants()`.
+Paused on 2026-08-21 pending discussion with Jinyang. The low-level iterator-
+state documentation and ownership model have been mapped, but the variant
+implementation and user-facing API have not been approved. There are not yet
+sufficient user-facing docs or examples to resolve the API by review alone.
+
+When work resumes, continue with the finalizer and initializer, then review
+decoding and exhaustion, and only then review `TreeSequence$variants()`. Do not
+restart from earlier PR slices, which are recorded as complete in
+`PR132_REVIEW_PLAN.md`.
+
+### Questions for Jinyang before resuming
+
+- What concrete workflow should `TreeSequence$variants()` support, especially
+  in AlphaSimR?
+- Can he provide one or two small executable examples with expected site,
+  allele, genotype, sample-order, and missing-data results?
+- What returned R object and iteration protocol does he intend? Are both
+  `next()` and `next_variant()` required?
+- Are the `copy` and deprecated `impute_missing_data` compatibility arguments
+  required by downstream code, or should this new R API omit unsupported or
+  deprecated compatibility surface?
+- Are the low-level iterator functions intended to be public installed C++ API
+  or internal implementation details?
+- What behavior is intended for `NULL` versus empty `samples` and `alleles`,
+  interval bounds, fixed allele mappings, and isolated/missing samples?
+
+### Exact restart point
+
+1. Resolve the questions above and record intentional deviations from Python.
+2. Resume at **C++ iterator state and initialization** below.
+3. Confirm finalizer and partial-initialization cleanup semantics from the
+   upstream C API before changing ownership code.
+4. Remove the redundant `ts_sexp` preservation only together with regression
+   tests covering garbage collection, iterator lifetime, early abandonment,
+   and absence of double-free behavior.
+5. Complete decoding/exhaustion and exact-content tests before reviewing the R
+   iterator API, documentation, and examples.
+6. Run the focused and full completion gates in section 5.
 
 This review covers:
 

RcppTskit/notes_pkg_dev.Rmd

@@ -2,6 +2,8 @@
 
 ## Next TODOs
 
+### Review and polish variants work
+
 struct rtsk_variant_iterator_state_t
 
 static void rtsk_variant_iterator_free
@@ -41,7 +43,7 @@ One important issue surfaced while documenting this: variant_initialized is set
 
 rtsk_variant_iterator_init mention copy is not implemented (a note from my postit)!?
 
-// TODO: This will go into AlphaSimR
+### This type of code will go into AlphaSimR
 
 Tskit examples of building tree sequence in C
 extern/tskit/c/tests/testlib.c has lots of examples of constructing a tree sequence using C