Confirm whether dependency/connection writes bump a card's resource version — if so, flush card PATCHes before them

[thewrz]

This was written agentically; verify its assertions and edit accordingly:

Follow-up from #105 (PR #106). #105 fixed the recovery (the 409/428 retry could not validate a /description op, so the run aborted). This issue is about the cause of the staleness.

The suspicion

sync.main() snapshots each card version (list_cards, or _created_card_snapshot for a card created this run), then:

• step 3 sync_child_connections -> POST /card/connections
• step 4 sync_dependencies -> POST /card/dependency
• step 5 flush -> ONE versioned PATCH /card/{id} per card, using the pre-POST version

In the live 2026-07-29 failure the dependency POST was the only write that touched the card between its snapshot refetch and the flush, and the server reported actualValue: 2 against a sent 1. If those POSTs bump the card resource version, then every run where a card both gains/loses a dependency (or child connection) and carries queued ops eats a failed PATCH + a refetch + a retry, plus a note ... version bumped by an unrelated change line that is not true — the run bumped it itself.

Not yet measured, so this is a hypothesis: an asynchronous server-side bump shortly after card creation would produce the same evidence.

Work

1. Probe live (fact-finding, throwaway card): read version, POST /card/dependency, read version again; same for POST /card/connections. Record the result in docs/API-VALIDATION.md (the issue Version-conflict retry can never recover a card carrying a /description op — apply run aborts on HTTP 428 #105 section flags this as UNCONFIRMED).
2. If confirmed, prevent rather than recover, the same reasoning as intake._card_for_link_write: move the step-5 flush ahead of steps 3-4 (nothing in those steps reads what the flush writes; poisoned_card_ids/managed_card_ids are already computable right after step 2), or refetch the version for just the affected cards. Verify the poisoned-card hold and the step-6 comment-sync clean gate are unaffected.
3. If not confirmed, record what actually bumps it and close — Version-conflict retry can never recover a card carrying a /description op — apply run aborts on HTTP 428 #105 recovery already keeps such runs correct.

Depends on #107 if the probe should live in smoke.py.

Testing

• Live version probe across a dependency POST and a connections POST, recorded in docs/API-VALIDATION.md
• If reordering: a sync.main() test asserting no card is written between its snapshot and its flush PATCH
• Poisoned-card hold + comment-sync gate unchanged
• Full suite green
• Live --apply run shows no version bumped note where none is warranted

🤖 Co-authored by Claude Opus 5.

[thewrz]

This was written agentically; verify its assertions and edit accordingly:

CONFIRMED by arithmetic from a live smoke run (2026-07-30)

The hypothesis holds, and the alternative explanation (an async server-side bump shortly after create) is ruled out.

A full python -m agilesync.tools.smoke run created its throwaway parent card at version 1 (the create response carries no version — the run reports this) and step 21 read the server at actualValue: 15. Between those two points smoke performs exactly 14 writes to that card:

Writes to the parent card before step 21	Count
PATCHes (steps 3, 4, 5, 6, 13, 14, 19)	7
Connection POSTs (step 9 connect, step 10 disconnect)	2
Dependency POSTs (step 11 create, step 12 delete — the duplicate-create 409 wrote nothing)	2
Comment writes (step 15 create, step 17 update, step 18 delete)	3
Total	14

1 + 14 = 15, exactly. Every write bumped the resource version once — including dependency POSTs, connection POSTs, and comment writes. Any write that did not bump would leave the total short, and any extra async bump would overshoot.

Caveat worth one cheap probe before this is written into docs/API-VALIDATION.md as measured rather than inferred: this is a total, not a per-call measurement. It holds unless one write bumps twice while another does not bump at all. Step 1 of this issue (read version, one POST /card/dependency, read version) still settles it directly and costs two GETs.

What this means for the work

Step 2 is warranted: the run inflicts the conflict on itself. A same-run dry run makes the shape concrete — an epic gains 3 child connections while those same three cards, plus the epic, all carry queued tag + description PATCHes. That is four self-inflicted 428s in one flush, each costing a failed PATCH plus a refetch plus a retry, every one of them reported under a version bumped by an unrelated change note that is not true.

New constraint for the reordering, from the comment-write finding: comment sync must stay after the flush. It bumps the version too, so moving it ahead of the flush would recreate the same staleness it is meant to avoid. sync.main() step 6 already sits after the flush and must stay there.

🤖 Co-authored by Claude Opus 5.