Allocation evolution: immutable regimes and verified assignment queries¶

1. Purpose, authority and delivery boundary¶

This document captures the owner's September 2026 design discussion and proposes a detailed route from the implemented bucket allocator to auditable, history-aware allocation with an optional materialized query path. It is a planning document, not evidence of implementation, environment acceptance or permission to activate features. No migration, runtime behavior, live database or deployment is changed by this document.

Parent delivery tracker: #3264. Read alongside STATUS, the existing acceptance contract, delivery plan and performance evidence. Those documents describe the earlier delivery boundary and contain historical progress statements; this proposal does not silently replace their currently enforced contract.

First MVP: immutable regime identity and review provenance, with the existing allocation algorithm and assignments unchanged. It must be independently reviewable and usable for audit before rebalancing or stamping exists. The shortest critical path is a compatibility contract, persisted regime/current pointer, common evaluator, provenance writes and tests.

Next usable slice: disabling a reviewer must not pause unaffected reviewers' new work. Thereafter introduce explicit revision/correction, and only then optional stamping. Do not make the first PR implement this entire document. Each phase below needs its own acceptance evidence and bounded PRs. Broader dashboards and speculative optimizations are not prerequisites for correctness.

2. Implemented baseline and verified gaps¶

The following is the repository/GitHub checkpoint inspected on 16 September 2026, not a claim that production is using these capabilities.

Area	Current implementation / delivery evidence	Gap relevant to this plan
Initial allocation	#2991 merged; deterministic bucket plan, default-off flag	No immutable history-aware regime model
Direct enforcement	#3211 merged	Preserve permission, saved-session and retry safeguards
Reviewer/admin views	#3213 merged	Keep counts and paging consistent across future query paths
Editor	#3212 merged; #3095 closed	New revision/preview flow is not implemented
Publication isolation	#3267 merged; #3326 generalized uncached reads	Review-start versus configuration-publication fencing remains a separate concern under #3321
Performance	#3228 and #3329 merged	Controlled qualification remains open under #3252
Capacity	#3383 and #3385 merged	Allocation journey passed, but full E2E/release acceptance is not established
Membership	#2271 merged; #3048 superseded/closed	Environment acceptance and membership-first migration programme are not complete merely because this PR merged
Reviewer authority	#3251 open	Shared out-of-request stage-review eligibility contract still required
Release acceptance	#3269 open; preview vehicle #3327 open	No overall feature-completion or production-activation claim

2.1 What is stored and calculated today¶

Each study stores WorkloadShareBucket, in the range 0–9,999. Creation hashes the study ID using the implemented fixed FNV-style calculation; legacy values are normalized on load and backfilled before enabling allocation. The bucket is study-owned, not stage-owned.
Each stage stores WorkloadShares: enabled state, configuration version, reviewer IDs and shares in basis points. Reviews-per-study is a stage setting used by the plan.
StageWorkloadSharePlan derives reviewer bucket lists in memory. It walks the fixed bucket domain, selecting distinct reviewers with the largest remaining bucket-slot targets and a deterministic tie break. It does not use study populations or review history.
Neither the derived reviewer-to-bucket mapping nor per-study advance assignments are currently persisted. Actual sessions and reservations are persisted separately.
New-work queries apply InWorkloadShareBuckets; partial sets become a Mongo membership predicate. A full 10,000-bucket set removes the restriction. An index on project and bucket exists, but that alone does not establish every query's latency.
Saved work has specific existing exemptions, subject to ordinary authorization. A reservation alone is not the direct-endpoint saved-session exemption.
The configuration API rejects changes, including stage-level allocation disable, once review activity exists. Disabling the stage later does not remove that restriction.
A configured inactive reviewer currently invalidates the new-work plan for the stage. This stage-wide behavior is deliberately replaced in a later phase of this proposal.

2.2 Performance evidence: avoid overclaiming¶

Existing equal-share synthetic profiles use two reviews per study: 10k studies/10 reviewers means 2,000 buckets per reviewer; 100k/50 means 400. The latter recorded allocated next-study warm p95 around 92 ms. It does not prove acceptable performance for nearly full fragmented bucket lists, all completion distributions, production contention or every combination of sorting and paging. The separate administrator aggregate recorded p95 3,475.7 ms against the declared 2,000 ms budget. That is shared-host diagnostic evidence, not environment qualification. No regeneration time for a future correction algorithm has been measured.

3. Owner requirements and terminology¶

3.1 Agreed direction from the discussion¶

Use one deterministic planner: initial allocation is the zero-history case; later explicit reallocation uses the same planning contract with prior assignments/history.
A stage has a current immutable allocation regime; previous regimes remain auditable.
Record all reproducibility inputs, algorithm version and the reason/actor for a revision.
Carry the originating regime identity from admission/reservation into the review session, rather than labeling a completed review with whatever regime is current at submission.
Target shares concern allocated review workload, not reviewer speed. A slow reviewer must not lose work, or receive extra work, merely because another finishes sooner.
Ordinary study additions preserve all existing allocations, including unstarted work. They inherit the same bucket mapping and do not create a new regime; the one exception is an optional batch correction, which adds an immutable supplement under the same regime (see section 6).
A correction for an added batch, if implemented, changes only that batch and accounts for total existing allocations, not only completed counts.
Explicit redistribution may move necessary unstarted work; preserve completed history and minimize disruption. Study removal can justify a more expensive recalculation.
Removing one reviewer's permission immediately blocks that reviewer, not everyone else. Reassignment of their outstanding work can follow without freezing unaffected work.
Immediate authoritative queries and background-stamped queries must describe the exact same allocation. Stamping is only an optimization.
Use stamped reads only with verified, current completeness. Invalidate readiness before relevant changes become visible; use the authoritative query while stamping catches up.
All new-work paths, direct access, saving, lists and counts must agree. Overrides must be included in query predicates, not applied only after a study has been retrieved.
A valid plan verifies every assigned reviewer (owner requirement, 22 September 2026): active membership and effective permission/access to the stage, its studies and the allocated activity, by the canonical authority. Validate on save, publication and activation; revalidate after membership, permission and scope changes and repair affected plans explicitly. Never substitute administrator claims or approximate another reviewer's permissions; a missing authoritative resolver is a blocker. Full contract: acceptance, "Assigned-reviewer validity".

3.2 Definitions¶

Term	Meaning
Review slot	One required independent ordinary review of a study in a particular stage
Target share	Intended proportion of review slots attributed to a reviewer; not effort/time or completion speed
Applicable reviewer	A person whose current effective authority permits reviewing the stage
Participating reviewer	An applicable reviewer with a positive allocation share; eligibility alone does not decide shares
Allocation regime	Immutable allocation policy/plan version for a stage, including reproducibility evidence
Bucket	Stable study-derived number; it is not itself an assignment or a session
Assignment	A regime's designation of a reviewer for a stage/study review slot
Correction	Deterministic deviation from the base bucket plan to improve actual slot counts
Supplement	Immutable membership/assignment evidence for a later admitted batch under the same regime
Stamp	Rebuildable persisted projection of effective assignments for a specific stage/regime/coverage
Coverage generation	Version identifying the applicable study set and allocation supplements represented by stamps

For multiple reviews per study, targets are shares of slots, not necessarily percentages of distinct studies. One person cannot supply two independent reviews of the same study. Completed, in-progress and unstarted assignments together form the attributed workload. Do not double-count a completed review and its original assignment as two slots.

4. Proposed domain and persistence contract¶

These are logical records, not finalized collection names or an instruction to embed unbounded arrays in project documents. Decide physical storage after sizing and query tests.

4.1 Immutable regime record¶

Record at least:

Regime ID, project/stage IDs, predecessor, creation actor/time and reason.
Policy kind: legacy-compatible bucket plan, corrected plan, explicit redistribution, or allocation-disabled transition if that capability is approved.
Planner version/artifact identity, input format version, seed if any, canonical ordering, tie-breaking, rounding and correction stopping rules.
Reviewer identities, target shares and immutable evidence of eligibility at planning time. This historical evidence is not continuing authorization.
Stage settings affecting slot requirements and the applicable study-set snapshot/reference.
Prior assignment/history snapshot: completed valid reviews, outstanding slots and protected sessions/reservations; exclude double-counted attempts and identify invalidated reviews.
Base-plan inputs and either the resulting mapping or an immutable mapping artifact/hash.
Correction records or immutable correction-set reference, with effective reviewer sets.
Achieved counts, deviations, infeasible targets and reasons; never silently label an approximation exact.
Input/output content digests and immutable evidence references. A digest of mutable live data alone is not enough to reproduce the plan.

The regime is immutable after publication. Candidate-build status and materialization progress live in separate mutable records. A stage's current pointer is mutable via optimistic concurrency. Keep large input manifests, per-study corrections and historical artifacts outside a size-unbounded whole-project document.

4.2 Regeneration versus persistence¶

Two valid representations remain to be measured:

Persist the full reviewer-to-bucket result, with corrections and input evidence.
Persist base algorithm inputs plus sparse corrections; derive/cache the effective bucket lists using the immutable regime ID.

Neither requires storing a reviewer/study row for every assignment in the authoritative plan. Study-specific corrections do require explicit study identity. Initial MVP should retain the existing algorithm representation and avoid prematurely selecting a heavy format. If reproducing historical plans requires old algorithm versions, preserve executable/versioned implementations or their final outputs; an arbitrary version string alone is insufficient.

4.3 Review provenance¶

Capture the admission regime ID and, where relevant, supplement/correction identity when a review slot is admitted. Propagate it onto the saved session. Both tracked and untracked review modes need an authoritative admission path; do not rely on a client-supplied ID.

When a session survives a later regime change, preserve its origin. If explicitly moved, record a transition event with old/new regime and reason. Current permissions remain live. Do not rewrite historical provenance to the newest regime on save. Legacy sessions with unknown origin remain explicitly unknown/legacy, not retrospectively claimed as allocated.

An allocation record explains why work was assigned. It does not by itself prove why access was authorized at every subsequent request; preserve existing security/audit evidence too.

4.4 Stage control and stamping state¶

Logical control fields include current regime ID, current coverage generation, readiness, verified materialization generation, build attempt/fence token and result manifest. Suggested states: algorithmic, building, verifying, ready, failed, superseded.

Study stamps logically carry project/stage identity, regime ID, coverage/build generation, and allocated reviewer IDs. Multiple stage assignments must remain distinct. If embedded arrays are chosen, query/index design must bind all predicates to the same allocation entry; do not accidentally match a reviewer in one stage and a regime in another.

Retain old regime evidence separately from hot query stamps. Do not accumulate every historic stamp indefinitely on every study. Cleanup may remove unreferenced derived artifacts only after active readers/jobs and audit retention obligations are accounted for.

5. Deterministic planning and correction¶

5.1 Objectives and precedence¶

Recommended lexicographic priorities, to confirm before implementation:

Respect permissions, distinct-reviewer constraints and existing valid completed work.
Preserve protected in-progress work, except that protection never preserves revoked access.
For additions, preserve every pre-existing assignment as a hard constraint.
For explicit redistribution, move the minimum necessary outstanding work to satisfy the requested policy, then minimize remaining target deviation within the agreed tolerance.
Resolve equally good results by stable, documented ordering, not runtime dictionary order, random process state, wall-clock time or live data changing during computation.

The balance-versus-minimal-movement priority and acceptable tolerance are product decisions. Do not claim a greedy heuristic is globally optimal. Record unmet targets and explicit unassigned slots if the constraint set is infeasible.

5.2 Target arithmetic¶

Compute targets from applicable review-slot demand and shares, using a specified deterministic integer rounding rule. Count valid completed reviews toward final attribution, including reviews by formerly eligible reviewers; specify how those unavoidable historical slots affect the denominator and active reviewers' remaining quotas.

Example with one review per study: 100 existing slots allocated 50/50, Alice completes 45 and Bob completes five. Adding 20 should aim for ten extra each, not compensate for speed. If existing allocations instead total 60/40, a batch-only correction may give Bob more new slots to approach equal final allocations, without moving any of Alice's existing work.

When an explicit new share is below someone's already completed total, that target is not achievable by undoing reviews. Preserve history and expose the closest allowed outcome. Deleting/invalidating a review is a separate audited domain action, not a balancing tool.

5.3 Bounded correction options¶

Begin from the current deterministic bucket mapping. Compute real assigned slot counts from the frozen study-set snapshot. Explore a bounded deterministic transfer/swap procedure that strictly improves the selected imbalance objective and has an explicit termination cap.

Bucket overrides are compact but cannot guarantee exact study counts when bucket populations differ. A bucket-level transfer affects all eligible studies in that bucket under its scope.
Study overrides can provide finer corrections. Persist additions/removals or the replacement effective reviewer set for each exception. Check that recipients have not already supplied a review and that enough distinct reviewers remain for each study.
A bucket with mixed completed/in-progress/unstarted work cannot be blindly transferred as a whole. The plan must express protected history and residual eligibility explicitly.
Bound exception counts/bytes, query size and correction cost. If exceptions are too large, stop with a usable diagnostic or use a separately validated representation; do not emit an arbitrarily large query/document.

Choose the minimum representation that satisfies observed balance needs. Benchmark before turning approximate statistical unevenness into a mandatory expensive optimization.

6. Change handling¶

Event	Allocation effect	Query/materialization effect
Ordinary review progress	Consume/complete existing assignments; no new regime	Live session/capacity filters update; assignment stamps need not be invalidated
New studies, unchanged policy	Inherit existing mapping; preserve old assignments	Invalidate coverage before studies become query-visible; algorithmic fallback while stamping additions
Optional correction of additions	Freeze supplement applying only to the new batch	Both paths use that supplement; update coverage, not old assignments
Explicit target-share change	New history-aware regime with preview	Switch authoritative regime safely; old stamps cannot serve it
Reviewer loses permission	Immediate denial to that person; others retain work	Live authorization enforces denial; invalidate affected allocation projection as needed
Membership, permission or scope change affecting an assigned reviewer (disable, removal, group/grant edits, study-scope or mode change)	Revalidate every affected enabled plan; mark it invalid with the failing reviewers and reasons; no silent redistribution	Failing reviewer denied new work; others continue; unfilled slots reported, not complete; repair through an audited save
Redistribute departing reviewer's work	New regime or explicitly scoped successor plan	Preserve other assignments unless the approved redistribution requires a change
Reviewer becomes eligible	Eligibility alone does not invent a positive share	Offer inclusion under an explicit/approved automatic-share policy
Study exclusion/removal	Immediately remove applicable new-work eligibility; preserve audit	Invalidate relevant coverage; allow slower recomputation when necessary
Review deleted/invalidated	May reopen demand; explicit audited repair policy	Reevaluate capacity and whether regime revision is required
Reviews-per-study/mode change	Validate compatibility and create explicit successor if supported	Do not silently unlock existing constraints before this transition is implemented
Reviewer holds a leftover claim on a study no longer allocated to them (owner rule, 24 September 2026; review-eligibility D8)	A bare claim grants no exemption. If their allocation plus existing work leaves no available slot for the study, release the claim with a warning; under reallocation (Phase 3) claims count as protected work and any not accommodated are released with a warning	New annotation, the new-annotation pool and direct access refuse with `AllocationNotAssigned`; saved sessions and reconciliation are unaffected

Batch additions must have a stable admission boundary so identical input produces identical correction decisions. Concurrent imports need serialized or version-checked supplements. The fallback must account for newly visible studies even if a supplement is still preparing: either publish the completed supplement with admission, or initially admit under the stable base policy. Do not claim exact batch correction before its plan is published.

Removal of a reviewer does not require pausing everyone. Remove their access immediately; retain others' assignments and saved work. Safely release/reassign their outstanding capacity without invalidating other reviewers' active reservations. If too few reviewers remain, show the affected unfilled slots rather than calling the stage complete or freezing unrelated work.

7. Query contract: one answer, two execution paths¶

7.1 Authoritative algorithmic path¶

Given a pinned regime and coverage/supplement view, derive base bucket eligibility and apply all corrections in the database predicate. Conceptually:

effective allocation = (base bucket eligibility minus reassigned-away exceptions) union explicitly assigned-to exceptions

Then apply project/stage authorization, visibility, exclusion, completed/saved-work semantics, capacity and in-progress limits. Deduplicate overlapping branches before count/page/sample. Do not post-filter a single sampled study: that loses possible valid results and biases selection. Direct access and submission must use the same effective allocation semantics.

Counts, lists and next-study selection need their own equivalent efficient queries; a fast single-result query does not prove the administrator aggregate is fast. Preserve stable pagination and expose a regime/version so pages can detect a plan change rather than combine incompatible assignments silently. Saved work and reconciliation retain explicit semantics.

7.2 Stamped path¶

Filter by the exact stage and authoritative regime/generation plus assigned reviewer, then apply the same live eligibility/session/capacity conditions. Stamps are not authorization, completion facts or a replacement for atomic capacity admission.

Both paths must support the same reviewer list and ordering capabilities. Stamping does not unlock a new ability to see assigned studies; it should only improve retrieval cost. Compare full study sets, counts, exception handling and allowed next-study candidates, not just one lucky sampled result.

7.3 Readiness and concurrency protocol¶

Every writer that can change allocation-relevant scope participates in invalidation. Invalidate readiness before or atomically with the change becoming visible.
A build job pins regime, coverage and a fenced attempt identity; it evaluates the same immutable plan as fallback and writes idempotent, generation-tagged stamps.
Verify expected coverage, absence of missing/extra assignments, plan identity and errors. Equal document counts alone do not prove equal membership or assignments.
Publish readiness with compare-and-swap against the exact still-current control version. A superseded job, resumed stale worker or changed scope cannot publish readiness.
A reader may use stamps only when the version it reads is certified current. Protect the readiness-check/query race: use a suitable consistent read boundary or recheck generation after reading and retry against authoritative state before returning/admitting work.
In-flight writes/reservations require a corresponding authoritative version check at admission, not only after rendering the list. Preserve atomic capacity safeguards.

The exact transaction/fencing mechanism must be prototyped against the existing Mongo and unit-of-work boundaries; a Boolean plus eventual change-stream notification is insufficient. SignalR may report progress to the UI, but cannot be the correctness mechanism. UI reconnect must obtain persisted current status, not depend on having seen an event.

Importers, deletion/exclusion handlers, membership/permission writers, restores, seeds and administrative jobs must be inventoried. If a path cannot honor the invalidation contract, keep stamped reads disabled for that scope. Live authorization is checked regardless.

7.4 Failure and fallback¶

Job crash, retry, duplicate delivery or partial stamping leaves algorithmic queries available. An optimization failure must not silently drop assigned studies. Old and new stamps may coexist during build, but queries must never mix generations.

If a successor allocation is not ready, unaffected reviewers continue under retained valid assignments with current permission checks. Only genuinely unassignable affected slots remain pending. Do not reintroduce a stage-wide pause as the normal solution to reviewer removal.

7.5 Resuming an earlier regime and its stamping job¶

Owner clarification: an earlier regime may be resumed if it is still compatible with the relevant current state. Merely retaining its immutable record does not make it eligible for reactivation. An incompatible regime remains available for historical audit, but cannot be selected as the current regime; a new regime must be planned instead.

Define an explicit, versioned compatibility predicate and report its reasons. Evaluate at least current effective reviewer authority, applicable stage/review-slot settings, intervening assignment changes and protected sessions, and whether existing corrections/supplements still apply. Compare semantic requirements, not just timestamps or an indiscriminate whole-project hash. Normal review completion and ordinary study additions must not automatically make a regime incompatible: they are expected under a stable allocation. However, work admitted under an intervening regime may create conflicts that require a successor plan. Historical authorization evidence never restores a revoked permission.

A conflict is defined per study and stage review slot, and the predicate reports each one with its study and slot. Work admitted under an intervening regime conflicts with the candidate regime when any of the following holds:

a completed, saved or reserved review attributed to reviewer A occupies a slot that the candidate regime assigns to a different reviewer B, and B would then need another slot of the same study (violating distinct reviewers) or the study would exceed its reviews-per-study capacity;
the candidate regime assigns a slot to a reviewer who already holds a review of that study admitted under the intervening regime (one person cannot supply two independent reviews);
the candidate regime's shares or corrections were computed against slot counts that the intervening work has since changed by more than the regime's recorded tolerance.

Intervening work that the candidate regime would itself have assigned to the same reviewer for the same slot is not a conflict. A regime with any conflict is not resumable; plan a successor that treats the intervening work as history.

Separate two questions:

Is this regime compatible and eligible to become current? If yes, reactivate through an audited, concurrency-checked pointer transition. Recheck compatibility at publication; do not rely only on a prior UI preview. Record the transition without mutating the regime.
Are its existing stamps complete for today's applicable coverage? This may be false even when the regime is resumable. Use its algorithmic path while completing and verifying missing coverage; do not inherit an old readiness Boolean.

Where storage retains multiple versions, uniquely identify a stamp by study, stage and allocation version, including an immutable supplement/output identity when that changes the effective assignment. An idempotent bulk upsert may skip an already verified matching stamp or safely reproduce it. Presence alone is insufficient if identity, content or coverage is wrong. Different regime versions must not overwrite one another's entries.

Stopping a superseded job midway is safe: completed batches remain reusable, partial failures are retried, and another regime's job can proceed. Cancellation is advisory: an already-issued bulk write may finish. Fencing must prevent that old worker from writing another version or publishing current readiness. A resumed job receives a fresh attempt/fence identity, reuses valid persisted progress, scans for missing work, and verifies current coverage before enabling stamped reads. Determinism makes the repeated result stable; idempotent writes make repetition safe. Neither removes the need for concurrency guards or verification.

No deletion of previous regime records or stamps is required merely to switch regimes. Retention of rebuildable stamps is a separate bounded-storage policy; immutable regime and review provenance history must remain available according to audit retention requirements.

Required tests: pause/resume after a partial bulk failure; duplicate batch replay; switch to another regime while an old batch is in flight; compatible return with complete stamps; compatible return after study additions with incomplete coverage; incompatible return after permission/settings changes; intervening reviews that conflict with old assignments; and stale compatibility/readiness checks losing their compare-and-swap race. Assert unaffected reviewers continue and no historical provenance is rewritten.

8. Compatibility, migrations and flags¶

Follow the approved deployment-applied migration direction; do not create permanent runtime storage-schema branches for this design. Use expand/migrate/contract slices:

Introduce compatible optional regime/provenance/stamp fields with explicit legacy behavior.
Inventory existing configurations and sessions using read-only preflight tooling.
Create legacy-compatible regimes preserving current assignments. Test old/new mapping equality across all supported configurations before switching a stage's pointer.
Backfill only facts that can be established. Preserve unknown historical provenance.
Validate target-specific migration receipts, retries, concurrent writers and restore incarnation. Do not confuse local fixture success with permission for live execution.
Retire incompatible writers before depending on new invariants, then remove temporary compatibility code through a separate verified contraction step.

Use explicit flag decisions in each implementation PR. Proposed separation: existing allocation gate, independently guarded regime/reallocation behavior, and a separate stamped- read optimization gate. Names/dependencies must follow the repository's generated catalog. Turning off stamped reads must restore algorithmic reads under the same regime, not revert assignments. Turning off allocation entirely has different semantics and requires an explicit transition/audit policy. Do not conflate those rollback boundaries.

Once new regimes are active, rolling back to a binary that ignores them may be unsafe. Document a compatibility floor and block incompatible restart; a flag is not sufficient to make an old writer understand new data. Live migration and activation remain separately gated.

9. Delivery phases and acceptance¶

Phase 1 — Regime identity and provenance, unchanged allocation¶

Deliver logical regime storage/current pointer, legacy-compatible evaluator and new-session provenance, together with the compatibility floor from section 8: document the minimum binary version that understands regime fields, and make readers and writers that meet an unknown or newer regime schema fail closed (serve no allocated work and refuse writes) instead of ignoring it, with a startup check that blocks an incompatible restart. No correction, reallocation or stamp dependency. Test byte/semantic-equivalent bucket lists, authorization, existing API contracts, legacy saved-work handling, and the fail-closed behavior of a binary below the compatibility floor. Completion: an administrator can inspect which regime admitted new work without changing who receives it.

Phase 2 — Common authority and isolated reviewer lifecycle¶

Coordinate #3251 with the authentication owner; reuse the canonical effective stage-review authority rather than invent a stored-groups approximation. That authoritative out-of-request resolver is a hard dependency: until it exists, assigned-reviewer validity (requirement 13) cannot be met and allocation cannot be activated as valid. Deliver the validity check on save, publication and activation, change-triggered revalidation with invalid-plan reporting, and audited repair, with the acceptance tests in acceptance, row 5. Make all assignment consumers consistent. Remove stage-wide fail-closed behavior for individual reviewer disablement while retaining immediate denial to the disabled reviewer. Test unaffected reviewer continuity, independent live streams, reservation release, stale caches and re-enable semantics. Keep membership deployment migration work linked to #2042, not implicitly completed by this phase.

Phase 3 — Deterministic revisions, correction and additions¶

First specify rounding, feasibility, protected-work and minimal-movement rules with golden fixtures. Add preview/create/commit with expected-current-regime concurrency. Preserve initial allocation as the empty-history case. Introduce bounded correction representation and effective query predicates. Add admission supplements only if batch correction is selected. Deliver explicit regime history and deviation reporting, not a general dashboard.

Acceptance: repeatable outputs for identical immutable inputs; changed shares preserve completed work; additions move zero prior assignments; changes during preview cannot silently publish stale plans; study-level distinct-reviewer and capacity invariants hold under races.

Phase 4 — Materialization in shadow mode¶

Build resumable fenced stamping and persisted progress. Keep all decisions on the algorithmic path. Compare both candidate sets and counts on controlled fixtures, including exceptions, history, imports and membership transitions. Benchmark document stamps versus a separate assignment projection if embedded-array indexes or whole-study write contention are costly. Completion means parity and measured benefit, not merely a job that finishes.

Phase 5 — Verified query switchover and controlled release¶

Enable stamped reads behind their independent flag only after invalidation-writer coverage, read/query race tests, fault injection and performance qualification pass. Verify fallback under repeated imports and failed jobs; UI distinguishes building, ready, failed and superseded. Run two-identity preview and staging acceptance, then request the separate production decision. No requirement to ship phases 3–5 together with the initial auditable-regime MVP.

10. Validation and performance matrix¶

Dimension	Required cases
Determinism	Permuted input enumeration, serialization round-trip, different workers, fixed version/seed; golden historical plans
Shares	Equal/unequal, rounding, tiny cohorts, many reviewers, impossible historical floors, zero-share omitted participants
Review slots	One/two/three reviews per study, existing review by a different former reviewer, duplicate attempts, insufficient distinct reviewers
History	Completed, saved incomplete, reservation-only, expired/released reservation, invalidated/deleted review, legacy unknown provenance
Lifecycle	Disable/re-enable, permission-group grant/revoke, direct grants, unrelated member removal, unaffected reviewers continue
Additions/removals	Sequential/concurrent imports, add during verification, excluded/removed studies, changed stage scope, batch correction leaves old work untouched
Publication	Competing admins, review starts between preview and commit, sibling project save, delayed/failed save, stale cached pointer
Materialization	Partial writes, retries, lost fence, duplicate jobs, stale completion, restore, changed coverage after ready check, optimization flag off
Query parity	Full assigned sets, counts, paging/sorting, next eligible candidates, direct GET/PUT denial, saved-work exemptions, no cross-stage stamp match

Performance profiles must include bucket list sizes from small through 5,000 and near 10,000, the full-set no-filter case, contiguous versus fragmented sets, realistic review counts, skewed shares, sparse/dense exceptions, empty/nearly complete stages and concurrent workloads. Compare current lists, compact ranges where applicable, and stamped projections on identical fixtures. Measure plan-generation/correction separately from database selection and end-to-end latency. Include random sampling, paging, admin aggregation, keys/documents examined, index plans, payload/memory, write amplification and stamping duration.

Retain the existing administrator budget as such; agree next-study and user-list budgets before declaring qualification. Record cold/warm definitions, environment resources, sample counts and immutable versions. No claim that all configurations will always meet a bound can be inferred from one warm fixture. Broad unsupported cases need explicit limits and diagnostics, not invented passing results.

11. Decisions to settle before the corresponding implementation¶

Share adjustment when someone joins/leaves: explicit admin choice, approved normalization policy, or pending unassigned slots? Access revocation is immediate regardless.
Definition of final target denominator when historical completed work belongs to reviewers no longer participating; treatment of excluded/invalidated reviews.
Tolerance, rounding and movement-versus-balance priority; exactness is not automatically achievable, especially with whole buckets and prior completed work.
Protected in-progress definition in both tracking modes; expiry and explicit handover rules.
Decided by the owner (24 September 2026, review-eligibility D8): under reallocation, outstanding claims count as protected in-progress work. Claims the new regime cannot accommodate, and any leftover claim on a study no longer allocated to its holder once their allocation plus existing work leaves no available slot, are released with a warning. A bare claim never grants an allocation exemption.
Bucket versus study corrections and their size limits. Store full map or base-plus-deltas?
Whether ordinary additions need correction at all; if yes, define stable batch boundaries and preserve the same regime with immutable supplements rather than mutate old decisions.
Physical snapshot/exception/stamp storage, indexes, retention and bounded artifact sizing.
Publication/invalidation transaction or fencing mechanism across project and study writers.
Per-stage allocation-off mid-review as a separate capability: preserve history and ordinary authorization, but explicitly specify re-enable behavior. It is not already supported.
Exact performance budgets and approval gates for environment rollout.

These are bounded implementation decisions, not a reason to postpone the unchanged-behavior regime MVP. Do not silently select policies merely to make tests pass.

12. Follow-up ownership and completion reporting¶

Retain #3264 as the umbrella; #3251 owns shared reviewer authority, #3252 performance qualification, #3269 integrated acceptance, #2042 membership/migration prerequisites and

3321 remaining isolation/fencing analysis. Search for existing issues before splitting each¶

implementation slice. Do not close these on documentation or partial component merges.

Implementation ownership remains with the existing allocation executor until explicitly transferred. This planning PR does not take over its worktrees, resume paused local edits, authorize a competing implementation or change the separate E2E infrastructure programme.

For each slice, record separately: proposed, implemented, locally validated, reviewed, merged, environment-qualified and activated. Link exact commits and reproducible evidence. The user should be able to distinguish a working feature from a promising plan or a completed cache job.