Task: Write counterparty manual chapter

Table of Contents

This page documents a task in the Commission: party, counterparty, and party_status story. It captures the goal, current status, acceptance, and any notes or results.

Goal

Add a Counterparties chapter to the user manual, mirroring the Parties chapter for the entity's Qt UI (General/Identifiers/Contact Information/Hierarchy/Provenance tabs) while documenting the real structural differences between the two entities rather than duplicating shared content.

Status

Field Value
State DONE
Parent story Commission: party, counterparty, and party_status
Now Nothing.
Waiting on Nothing.
Next Nothing.
Last touched 2026-07-16

Acceptance

  • A new chapter_9_counterparties.org exists under doc/manual/user_guide/, wired into user_manual.org's table of contents after the Parties chapter.
  • The chapter documents what a counterparty is by referencing the Parties chapter for everything shared (legal-entity identification, GLEIF/LEI, identifier schemes) rather than duplicating it, and clearly explains the two real differences: no codename, and a hierarchy with no single-root constraint (unlike a party's).
  • The chapter documents the Counterparties window and all five Counterparty Details tabs, following the structure established by chapter_8_parties.org.
  • Parties' Conclusion/See-also updated to link to the new chapter instead of saying it doesn't exist yet.

Plan

Read ores.refdata.counterparty.org's Detail fields table and Flags directly (not inferred from the party model) to confirm the real differences before writing: no codename field, no party_category (System/Operational) distinction, full_name explicitly not unique (has a non-unique search index rather than a uniqueness constraint, since the same external legal name can recur across branches), and critically — parent_counterparty_id has no database-level uniqueness-on-null constraint at all, unlike a party's parties_root_party_uniq_idx. The Qt Create dialog's Parent Counterparty field is still marked required (mirroring the party fix), but this is a UI policy choice, not a reflection of any DB invariant about roots — the chapter is explicit about that distinction so it doesn't read as a duplicated, over-general "single root" claim. Cross-referenced the Parties chapter throughout instead of re-explaining identifiers/GLEIF/contact information, per the dedup lesson learned writing that chapter.

Notes

  • All 7 screenshots captured against the live Barclays Plc (GLEIF) environment, cropped to just the dialog/window (no QA Validation Runner chrome), and committed under assets/images/ (repo root).
  • The Hierarchy tab capture (counterparty_details_hierarchy.png) shows BANCO CREDIBOM S.A. nested three levels deep under CA INDOSUEZ — a real ancestor chain, demonstrating that (unlike a party) a counterparty's tree membership is incidental group structure from GLEIF data, not a single tenant-wide hierarchy.
  • The History dialog capture shows a genuine Full Name spelling correction (v5→v6), consistent with the other entities' history screenshots this sprint.

Test Scenarios

Manual QA scenarios (scaffolded via compass add test_scenario, run through the QA Validation Runner panel) that verify this task. Link new ones here as they're created; the scenario doc itself links back via its "Verifies task" field.

Scenario State Notes
Capture counterparty manual chapter screenshots PASSED All 7 steps passed.
Verify the No Parent combo entry for party and counterparty PASSED All 5 steps passed.

PRs

PR Title
#1605 [qt,docs] Write counterparty manual chapter; add No Parent combo entry

Review

# Comment summary File Decision Notes
1 Latent blank-vs-never-selected ambiguity in populateDynamicCombo DynamicComboSetup.hpp Declined (follow-up) Latent, unreachable via current call sites; filed as dynamic_combo_blank_vs_unselected_ambiguity capture
2 Scenario step "Edit an existing standalone counterparty from GLEIF data" left PENDING under overall PASSED scenario_no-parent-combo-verification.org Fixed Step actually run; status corrected to PASS
3 Screenshot recapture claim in PR description didn't match reality PR #1605 description Fixed PR body corrected; screenshots remain outdated pending recapture, filed as recapture_parent_combo_screenshots capture
4 New verification scenario not linked from task's Test Scenarios table task_write-counterparty-manual-chapter.org Fixed Row added

Result

Added doc/manual/user_guide/chapter_9_counterparties.org, wired into user_manual.org after the Parties chapter. Rather than re-deriving Parties' content, the chapter cross-references it for everything shared (legal-entity identification, GLEIF/LEI, the identifier scheme table) and focuses on the two genuine structural differences: no codename field, and a hierarchy with no database-level single-root constraint — the Parent Counterparty field is still required on Create as a UI policy, but that is explicitly distinguished from a party's DB-enforced house-root rule. Updated Parties' Conclusion/See-also to link to the new chapter instead of saying it doesn't exist yet. All 7 screenshots captured, cropped, and committed; the scenario passed all steps first time.

Emacs 29.3 (Org mode 9.6.15)