Expand description
Q2 — the pull orchestration: fetch reviewer comments from the linked Google
Doc and merge them into the org file as structural-anchored TODO headings.
This is the imperative shell (EI-4). It sequences the effects (list comments
over the network, then rewrite the file content) and delegates every decision
to the pure cores — anchor→section mapping (crate::comments), comment
rendering/merge (crate::comments_meta), sync state (crate::syncstate),
region writeback (crate::orgfile).
Guarantees:
- Merge-by-id (A3). Existing comment headings are preserved byte-for-byte and never reordered; only ids not already present are appended. A pull that finds no new comments is a no-op on the file (proven by a test).
- DI-2 — the body is sacrosanct. Pull reuses the verbatim-body writeback;
the only body change is the idempotent, already-present
:CUSTOM_ID:insertion (so every section a comment references has a real drawer for elisp to jump to). - DI-3 — stateless. Everything is read from and written to the file content (plus the live comment list); no sidecar.
- DI-4 — pull never creates or anchors a comment in Google; it only lists.
Pull does not re-project the body: the position map describes the pushed
doc (what the Google anchors point into), so it is preserved from ** Sync State rather than regenerated. Only the collaborator cache and
#+GDOC_LAST_PULL: change.
Structs§
- Pull
Outcome - The result of a pull: what was merged and the new file content to persist.