Affiliation and role period lifecycle
Purpose
The affiliation lifecycle explains when a dated tie and its responsibilities count as current. Ruth’s future employment, current chapter service and former employer need different interpretations even though all three rows remain in her contact. The primary designation adds prominent organization context rather than replacing the full set of current connections.
Our reading is that calendar classification must remain separate from the side effects that follow a start day. A tie can become current immediately in a read while its automatic-role or sharing work is still pending. The lifecycle therefore explains eligibility, designation, retention and removal without promising synchronous midnight processing.
Ownership and Authority
Contact editors and authorized integrations submit dated relationship changes through the owning contact’s save. Organization-page actions use that same contact authority. The workspace calendar changes effective interpretation, and reconciliation workers settle pending roles or defaults under their system context. No inference operation chooses dates, primaries or responsibilities.
The lifecycle preserves the observed aggregate-write route for ending and removal; it does not resolve the open disagreement with Platform’s explicit-operation requirement. The contact version and element restrictions remain part of authority for a relationship change, even when the organization page is the entry point.
The Lifecycle
States
new
The relationship has not been persisted. Entry requires this condition: The affiliation is a draft nested in a contact request. Available behavior is Select organization, type, dates and roles; save after validation.. The proposed relationship has not yet contributed committed coverage.
upcoming
The start date is later than the workspace date; pending role and link choices await eligibility. Entry requires this condition: The saved start date is after the workspace day. Available behavior is Read; edit under contact guards; settle pending work once eligible.. The editor identifies a future tie and defers live sharing.
current
The relationship is effective through its inclusive end date and is not designated primary. Entry requires this condition: The day falls inside the inclusive saved period without a primary designation. Available behavior is Read; edit; select primary only if open-ended; end or remove under contact guards.. The tie can contribute to current-person discovery even when it is secondary.
current primary
An effective, open-ended relationship is designated primary and shares its title with the contact. Entry requires this condition: The tie is effective, open-ended and selected as the contact’s sole primary. Available behavior is Read; change coordinated title; clear primary; end through save.. Its organization and title supply the prominent person context.
past
The workspace date has passed the inclusive end date; the saved relationship remains available as history. Entry requires this condition: The workspace day is later than the inclusive end date. Available behavior is Read dated history; correct permissible dates; remove through an explicit list.. The tie remains visible as former organizational context.
removed
The live affiliation is removed, leaving its earlier values in contact revisions. Entry requires this condition: A valid explicit contact collection removes the affiliation. Available behavior is Inspect earlier values through contact revisions.. The live relationship and owned role periods are absent. This row’s lifecycle ends here; a new request or new record is separate work.
Transitions Explained
new → upcoming
An authorized contact editor starts this change when the following occurs: Save a new affiliation with a future start date. The transition checks this boundary: Workspace-local organization and type, no prohibited overlap and no more than 100 current or future affiliations. The accompanying work is mark automatic roles pending; retain selected default mappings; defer new shared links. A changed contact save captures affiliation and role differences in its aggregate revision. Merely crossing a calendar date writes no relationship revision; settled roles or links create their own contact changes.
new → current
An authorized contact editor starts this change when the following occurs: Save a relationship already effective today. The transition checks this boundary: New-affiliation checks apply, and the end cannot precede the start. The accompanying work is fill eligible empty contact purposes from chosen defaults; raise a post-commit compliance reaction. A changed contact save captures affiliation and role differences in its aggregate revision. Merely crossing a calendar date writes no relationship revision; settled roles or links create their own contact changes.
current → current primary
An authorized editor or integration starts this change when the following occurs: Select a primary affiliation directly or through the Organization command. The transition checks this boundary: It must have started and be open-ended; the save cannot newly select two primaries. The accompanying work is clear previous primary; synchronize contact and affiliation title; assign eligible missing automatic roles; serialize first-contact role assignment. A changed contact save captures affiliation and role differences in its aggregate revision. Merely crossing a calendar date writes no relationship revision; settled roles or links create their own contact changes.
current primary → current
An authorized contact editor starts this change when the following occurs: Clear primary designation or choose another primary. The transition checks this boundary: Pass the owning contact save checks. The accompanying work is leave no automatically selected replacement when merely cleared. A changed contact save captures affiliation and role differences in its aggregate revision. Merely crossing a calendar date writes no relationship revision; settled roles or links create their own contact changes.
upcoming → current
The workspace calendar and reconciliation workers starts this change when the following occurs: The workspace date reaches the start. The transition checks this boundary: Date classification changes without a write; pending effects need reconciliation or a later save. The accompanying work is attempt roles on eligible five-minute passes subject to budgets and locks; apply pending defaults and compliance when date reconciliation is enabled; allow save-time settlement. A changed contact save captures affiliation and role differences in its aggregate revision. Merely crossing a calendar date writes no relationship revision; settled roles or links create their own contact changes.
current → past
An authorized editor or calendar progression starts this change when the following occurs: End by a save or by passing the saved end date. The transition checks this boundary: An edited end must not precede the start. The accompanying work is clip affected role periods when editing the end; leave source links unresolved when no longer effective; refresh compliance through an event or date pass. A changed contact save captures affiliation and role differences in its aggregate revision. Merely crossing a calendar date writes no relationship revision; settled roles or links create their own contact changes.
current primary → past
An authorized editor or integration starts this change when the following occurs: End the primary relationship through the save, departure flow or Organization command. The transition checks this boundary: The normal ending checks apply. The accompanying work is clear primary without replacement; close role periods; remove a zero-day prior stay in the Organization command. A changed contact save captures affiliation and role differences in its aggregate revision. Merely crossing a calendar date writes no relationship revision; settled roles or links create their own contact changes.
current → removed
An authorized contact editor starts this change when the following occurs: Omit an affiliation from an explicit replacement list. The transition checks this boundary: No submitted contact detail may remain linked through it. The accompanying work is delete owned role periods; raise compliance reaction after commit. A changed contact save captures affiliation and role differences in its aggregate revision. Merely crossing a calendar date writes no relationship revision; settled roles or links create their own contact changes.
past → removed
An authorized contact editor starts this change when the following occurs: Remove a relationship entered in error through the explicit list. The transition checks this boundary: Resolve any detail still linked through the relationship. The accompanying work is remove affiliation and owned roles; recalculate affected compliance after commit. A changed contact save captures affiliation and role differences in its aggregate revision. Merely crossing a calendar date writes no relationship revision; settled roles or links create their own contact changes.
What Cannot Happen
A new or redirected future tie cannot become primary. The save returns relationship validation problems, leaving the prior aggregate intact.
A primary tie cannot retain an end date. Staff must choose a valid open-ended current tie or clear the designation.
An existing affiliation identity cannot be redirected to another organization. The save refuses it; a separate tie preserves the distinct episode.
Omitting the affiliations property preserves existing relationships. It produces no removal; an explicit collection excluding the entry is required.
Permissions by State
The state rows reference grants from the CRM authorization model. Read access is distinct from mutation, and history requires the corresponding history and read checks. Administrator and Power User hold administrative record actions; ordinary Standard User grants include applicable read and update operations, while Read Only grants do not authorize edits.
Contact update controls these nested corrections even when initiated from an organization. Archive and locks can still refuse an otherwise authorized change. Calendar interpretation needs no user grant.
Concurrency and Timing
Contact row locking and read-version comparison serialize relationship corrections and pending-role settlement. First-contact assignment also locks the organization so simultaneous joins cannot each independently win the same first-contact decision. This lock arrangement does not prove that all multi-record deadlocks are impossible.
Future, current and past come from dates, while pending work has separate bounded processing. Full record or element locks can defer that work after eligibility begins. Ending a tie clips applicable responsibilities, leaves former context readable and can leave linked details unresolved until an authorized editor chooses a recovery.
Invariants
Our reading is that effective dates must remain independent of primary prominence. A current secondary affiliation contributes relationship context even though another organization appears beside the person’s name. Inclusive ends keep the last day interpretable; a future beginning can change read interpretation before all pending side effects settle. The saved primary and coordinated title must remain consistent. Role-period identities remain attached to their owning affiliation, so a collection save cannot disguise moving another relationship’s responsibility into this one.