feat(context): introduce GroupRequest and ContextGroupId types for group management

[rtb-12]

[core] Implement hierarchical context group management

Description

Implements the full Context Groups feature across core/crates/, enabling administrators to organize contexts into groups with shared application targets, coordinated upgrades, and membership management. Built across 6 phases on top of the context-config contract types (ContextGroupId, GroupRequest, AppKey).

Phase 1 — Storage Foundation

• 5 new key structs in store/src/key/group.rs: GroupMeta (0x20), GroupMember (0x21), GroupContextIndex (0x22), ContextGroupRef (0x23), GroupUpgradeKey (0x24) — all with AsKeyParts/FromKeyParts impls and roundtrip tests
• Value types: GroupMetaValue, GroupUpgradeValue, GroupUpgradeStatus with Borsh serialization
• Primitive types in primitives/src/context.rs: UpgradePolicy (Automatic / LazyOnAccess / Coordinated), GroupMemberRole (Admin / Member), GroupInvitationPayload

Phase 2 — Group CRUD + Membership

• group_store.rs (~390 LOC): Complete storage helper layer — CRUD for group metadata, members, context indices, and upgrade records with efficient key-only iteration for counting
• 6 actor handlers: create_group, delete_group, add_group_members, remove_group_members, get_group_info, list_group_members
• 6 admin API routes with corresponding server handlers

Phase 3 — Context-Group Integration

• create_context.rs: Pre-validates group membership + app override; post-creation registers context in group index
• delete_context.rs: Unregisters context from group on deletion
• list_group_contexts: New paginated endpoint for listing a group's contexts

Phase 4 — Upgrade Propagation

• Canary-first upgrade strategy: Upgrades the first context as a canary; on success, spawns an async propagator for the remaining contexts
• propagate_upgrade(): Async fn that iterates group contexts, calls update_application() per context, persists progress after each step
• Status tracking: GroupUpgradeStatus::InProgress { total, completed, failed } → Completed { completed_at }
• 3 API endpoints: POST /upgrade, GET /upgrade/status, POST /upgrade/retry

Phase 5 — Advanced Policies + Crash Recovery

• Lazy-on-access upgrade: execute.rs transparently upgrades stale contexts before method execution when UpgradePolicy::LazyOnAccess is set
• Crash recovery: ContextManager::started() scans for InProgress upgrades and re-spawns propagators
• Auto-retry: Failed context upgrades are retried up to 3× with exponential backoff (5s, 10s, 20s)

Phase 6 — Group Invitations + Join Flow

• GroupInvitationPayload: Borsh-serialized + base58-encoded invitation token (mirrors ContextInvitationPayload pattern)
• Targeted (invitee_identity: Some) and open (invitee_identity: None) invitation modes
• Join validation: Verifies inviter is still admin, checks invitee identity match, validates expiration
• 2 API endpoints: POST /groups/:id/invite, POST /groups/join

Post-implementation fixes (PR review)

• Phase 1: Fixed off-by-one in propagate_upgrade completed counter on retry/recovery paths
• Phase 2: Fixed swallowed store errors, stale GroupContextIndex on re-registration, orphaned upgrade records on group deletion, Duration::new panic on malformed Borsh, switched to ValidatedJson for upgrade input
• Phase 3: Rewrote count_group_admins/count_group_contexts without Vec allocation, added offset/limit to enumerate_group_contexts, batched member cleanup in delete_group
• Phase 4: Decoupled GroupUpgradeValue/GroupUpgradeStatus store types from calimero-context-primitives API boundary — introduced GroupUpgradeInfo and primitives-local GroupUpgradeStatus with From conversion impls
• Phase 5: Added count_group_members() for efficient member counting, inlined value read in enumerate_in_progress_upgrades to reuse store handle

New API routes

POST /admin-api/groups → CreateGroup GET /admin-api/groups/:group_id → GetGroupInfo DELETE /admin-api/groups/:group_id → DeleteGroup POST /admin-api/groups/:group_id/members → AddGroupMembers POST /admin-api/groups/:group_id/members/remove → RemoveGroupMembers GET /admin-api/groups/:group_id/members → ListGroupMembers GET /admin-api/groups/:group_id/contexts → ListGroupContexts POST /admin-api/groups/:group_id/upgrade → UpgradeGroup GET /admin-api/groups/:group_id/upgrade/status → GetGroupUpgradeStatus POST /admin-api/groups/:group_id/upgrade/retry → RetryGroupUpgrade POST /admin-api/groups/:group_id/invite → CreateGroupInvitation POST /admin-api/groups/join → JoinGroup 

Test plan

• cargo check --workspace — compiles cleanly
• cargo fmt --check — no formatting issues
• cargo clippy -- -A warnings — no errors
• cargo test -p calimero-context — 16 tests pass
• cargo test -p calimero-context-primitives — 3 tests pass
• cargo test -p calimero-store — key roundtrip + value serialization tests pass
• End-to-end group lifecycle tests via meroctl against a running merod node
• Contract integration tests in contracts/ repo

Documentation update

N/A — these are internal protocol types. Public API documentation should be added once the full group management feature is shipped end-to-end.

---

Note

Medium Risk
Adds a large set of new group-management request/response types and client APIs, plus changes to node identity/config serialization; mistakes could break group operations or config compatibility and affect auth-protected admin endpoints.

Overview
Introduces context group management primitives in calimero-context-config by adding ContextGroupId/AppKey, GroupRequest/GroupRequestKind, group invitation payload types, and new group-related query request/response structs.

Extends the context-config client to build and send group mutate/query operations (and removes UB transmute decodes in favor of safe Repr unwrapping), and adds an on-chain ExternalGroupClient with nonce-retry handling for group contract mutations.

Expands the HTTP client/admin API surface with a new group module exposing admin-api/groups/* methods, adds PATCH/PUT/DELETE-with-body support and better error extraction in ConnectionInfo, and updates delete_context to accept an optional requester body.

Updates node configuration identity to a structured [identity] section that can include an optional group signing identity (GroupIdentityConfig), adds a small auth helper to fetch a stored public key by verified key_id, and updates docs/deps/tests (adds wiremock tests for the new client methods, and updates README.mdx link).

^{Written by Cursor Bugbot for commit b73d448. This will update automatically on new commits. Configure here.}

[meroreviewer]

🤖 AI Code Reviewer

Reviewed by 3 agents | Quality score: 100% | Review time: 167.3s

💡 1 suggestions. See inline comments.

---

_{🤖 Generated by AI Code Reviewer | Review ID: review-3e67acf7}

[meroreviewer]

🤖 AI Code Reviewer

Reviewed by 3 agents | Quality score: 100% | Review time: 227.1s

💡 3 suggestions. See inline comments.

---

_{🤖 Generated by AI Code Reviewer | Review ID: review-078e5b50}

[meroreviewer]

🤖 AI Code Reviewer

Reviewed by 3 agents | Quality score: 100% | Review time: 203.4s

💡 2 suggestions, 📝 1 nitpicks. See inline comments.

---

_{🤖 Generated by AI Code Reviewer | Review ID: review-86d4a70f}

[meroreviewer]

🤖 AI Code Reviewer

Reviewed by 3 agents | Quality score: 100% | Review time: 197.8s

🟡 2 warnings, 💡 2 suggestions. See inline comments.

---

_{🤖 Generated by AI Code Reviewer | Review ID: review-04819256}

[meroreviewer]

🤖 AI Code Reviewer

Reviewed by 3 agents | Quality score: 89% | Review time: 319.2s

🟡 2 warnings, 💡 4 suggestions. See inline comments.

---

_{🤖 Generated by AI Code Reviewer | Review ID: review-f10665bd}

[meroreviewer]

🤖 AI Code Reviewer

Reviewed by 3 agents | Quality score: 93% | Review time: 332.1s

🟡 1 warnings, 💡 4 suggestions. See inline comments.

---

_{🤖 Generated by AI Code Reviewer | Review ID: review-b85d5844}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[meroreviewer]

🤖 AI Code Reviewer

Reviewed by 3 agents | Quality score: 100% | Review time: 541.4s

💡 4 suggestions. See inline comments.

---

_{🤖 Generated by AI Code Reviewer | Review ID: review-2fcad253}

[meroreviewer]

🤖 AI Code Reviewer

Reviewed by 3 agents | Quality score: 100% | Review time: 370.3s

🟡 1 warnings, 💡 2 suggestions. See inline comments.

---

_{🤖 Generated by AI Code Reviewer | Review ID: review-4661abb1}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}