## Overview This epic tracks the implementation of switching from **lookup-based to propagation-based state inheritance** for GitLab's namespace hierarchy (Organization > Group > Subgroup > Project), as described in [ADR 003: State Propagation Model](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/group_and_project_operations_and_state_management/decisions/003_state_propagation_model/) and [MR !19153](https://gitlab.com/gitlab-com/content-sites/handbook/-/merge_requests/19153). ### Problem The current lookup-based approach determines effective state by traversing up the ancestor hierarchy at read time. This causes: - Read-time query overhead on every state check - Inconsistent state inference across descendants - No clear propagation rules through the hierarchy - Caching complexity to mitigate read performance ### Solution Propagate states (`active`, `archived`, `deletion_scheduled`) to all descendants when set on a namespace, enabling fast reads via simple column comparisons without ancestor traversal. ### DRI @aakriti.gupta --- ## Implementation Outline ## Key Technical Decisions ## References - [ADR 003: State Propagation Model MR !19153](https://gitlab.com/gitlab-com/content-sites/handbook/-/merge_requests/19153) - [ADR 001: Unified State Management](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/group_and_project_operations_and_state_management/decisions/001_unified_state_management/) - [ADR 006: State Preservation](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/group_and_project_operations_and_state_management/decisions/006_state_preservation/) - [Tree Iterator Documentation](https://docs.gitlab.com/development/database/poc_tree_iterator/) - [Transactional Outbox Pattern](https://microservices.io/patterns/data/transactional-outbox.html) <!-- STATUS NOTE START --> ## Status 2026-07-02 :clock1: **total hours spent this week by all contributors**: 35h :tada: **achievements**: - **Phase 2 boundary enforcement completed:** [!237686](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/237686) merged ([#599292](https://gitlab.com/gitlab-org/gitlab/-/work_items/599292)), adding cursor rewind so the iterator detects concurrent state changes mid-traversal and skips/rewinds affected batches. This closes out the correctness guarantees for the state-aware tree iterator and unblocks the Phase 3 workers. - **Phase 4 read-path and constants landed:** Shane merged [!242843](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/242843) to make StateQuerying#effective_state read the propagated column directly instead of traversing ancestors ([#599306](https://gitlab.com/gitlab-org/gitlab/-/work_items/599306)), and [!242842](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/242842) defining the propagated/non-propagated state classification constants ([#599304](https://gitlab.com/gitlab-org/gitlab/-/work_items/599304)). Together these deliver the fast column-comparison reads that motivate the whole propagation model. - **Phase 3 propagation workers progressing:** The core [StatePropagationWorker](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/242220) ([#599298](https://gitlab.com/gitlab-org/gitlab/-/work_items/599298)), reconciliation [StatePropagationCronWorker](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/242221) ([#599300](https://gitlab.com/gitlab-org/gitlab/-/work_items/599300)), and [StatePrecedence module](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/241091) ([#599297](https://gitlab.com/gitlab-org/gitlab/-/work_items/599297)) continued to be iterated on and are being readied for review now that the iterator has merged. - **Documentation:** The developer docs MR [!242501](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/242501) ([#604120](https://gitlab.com/gitlab-org/gitlab/-/work_items/604120)) moved out of draft and into review, and the maintenance state is being documented on ADR 003. :issue-blocked: **blockers**: - No hard blockers this week. :arrow_forward: **next**: - Move the Phase 3 worker drafts ([!242220](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/242220), [!242221](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/242221), [!241091](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/241091)) out of draft and get them merged. - Continue Phase 4 with [#599307](https://gitlab.com/gitlab-org/gitlab/-/work_items/599307). _Copied from https://gitlab.com/groups/gitlab-org/-/epics/21607#note_3539097982_ <!-- STATUS NOTE END -->