Maintain Dated Links Between Records

Purpose

Record keepers need to express current and past connections without losing their dates. Relationship links hold those facts under administrator-defined types.

How It Works

A staff member starts from either record and chooses its counterpart. The service checks the type, endpoints and available relationship place. Dating and primary rules determine whether the proposed link conflicts with existing links. Staff can correct its own attributes at the version read. Ending preserves a dated connection, while removing can end an open connection or delete a historical correction. Both endpoint cards expose permitted actions and the option to inspect ended links. Locks remain effective when the type is deactivated, while unlocked existing links can still be maintained.

Relationships

Relationship definitions determine link shape. Endpoint deletion and merge apply the corresponding policies, and history captures link changes.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes: Record keepers need to express current and past connections without losing their dates.Both endpoint cards expose permitted actions and the option to inspect ended links.
Surfaces: consoleapi
Preconditions: The type is active and both endpoints belong to the workspace.
Intent sources: services-platform:docs/milestones/plans/PLAT-M6-plan.md#3. How it works for the user; 5. D2 (Andrew, 2026-10-21: in force until it ends)services-platform:docs/milestones/plans/PLAT-M6-plan.md#9. Acceptance scenarios PLAT-M6-S03 to S07, S10, S12services-platform:docs/proposals/custom-objects/09-decisions.md#D-04, D-12, D-16

Controls

23 controls apply, from the corpus control catalogue.

TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-DAT-004 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PI-003 TC-PI-005 TC-PRV-001 TC-PRV-002 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-VEN-001 TC-VEN-002 TC-VEN-003

Permissions

Key	Checked at	Scope
`platform.associations.read`	api	tenant
`platform.associations.create`	api	tenant
`platform.associations.update`	api	tenant
`platform.associations.delete`	api	tenant

Business Rules

13 rules, 12 to be proved before approval. A rule's product intent is derived from its origin: 13 confirmed by a product decision, the rest inheriting this capability's confirmed.

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Confirmed	Creating a link requires an active workspace type and two existing compatible endpoints, rejects self-links and fills an omitted endpoint from the record route. proved by `ATS-PFM-MTD-012-18`, `ATS-PFM-MTD-012-19`, `ATS-PFM-MTD-017-09`, `ATS-PFM-MTD-018-01`, `TST-PFM-MTD-036`, `TST-PFM-MTD-045`	validation	service	test services-platform:modules/associations/tests/integration/services/persistence/associations.integration.spec.js#refuses a record associated with itself
`02`must prove Confirmed	A link remains in force through its inclusive end date in the workspace calendar, or indefinitely when no end date exists. origin: services-platform:docs/milestones/plans/PLAT-M6-plan.md#5. D2 (Andrew, 2026-10-21: "In force until it ends") proved by `ATS-PFM-MTD-018-02`, `TST-PFM-MTD-020`, `TST-PFM-MTD-044`	calculation	service, database	test services-platform:modules/associations/tests/integration/services/persistence/associations.in-force.integration.spec.js#still holds the place on the end date itself when that date is today
`03`must prove Confirmed	Overlapping date spans cannot occupy a duplicate pair, a cardinality-limited endpoint or the primary place of a record and type; unbounded ends and inclusive dates determine conflicts while adjacent spans are allowed. origin: services-platform:docs/milestones/plans/PLAT-M6-plan.md#5. D2 proved by `ATS-PFM-MTD-018-02`, `ATS-PFM-MTD-018-03`, `TST-PFM-MTD-018`, `TST-PFM-MTD-020`, `TST-PFM-MTD-044`, `TST-PFM-MTD-045`	validation	service, database	test services-platform:modules/associations/tests/integration/services/persistence/associations.in-force.integration.spec.js#refuses a second link of a one-place type that starts today, naming the link whose end date has not passed
`04`must prove Confirmed	Concurrent writers cannot both occupy a conflicting relationship place, and the losing write receives a conflict refusal. proved by `ATS-PFM-MTD-018-04`, `TST-PFM-MTD-044`, `TST-PFM-MTD-045`	invariant	service, database	test services-platform:modules/associations/tests/integration/services/persistence/associations.in-force.integration.spec.js#refuses one of two writers of overlapping links of one pair, as a refusal and not a database error
`05`must prove Confirmed	Only dated types accept calendar dates, an end cannot precede its start and only primary-enabled types accept primary links. proved by `ATS-PFM-MTD-018-05`, `TST-PFM-MTD-045`	validation	service, database	test services-platform:modules/associations/tests/integration/services/persistence/associations.integration.spec.js#refuses an end before the start on a dated type
`06`must prove Confirmed	Type and endpoint identities remain fixed, while versioned replacements can change dates, primary designation, position and notes bounded to four thousand characters. origin: services-platform:docs/proposals/custom-objects/09-decisions.md#D-12 (fixed link attributes) proved by `ATS-PFM-MTD-018-06`, `TST-PFM-MTD-036`, `TST-PFM-MTD-045`	invariant	service	test services-platform:modules/associations/tests/e2e/associations.e2e.spec.js#answers 400 to a replacement that names another record
`07`must prove Confirmed	Ending a dated link uses a supplied day or the workspace today and refuses already-ended, invalid or conflicting spans; ending an undated link is refused in favour of removal. proved by `ATS-PFM-MTD-018-07`, `ATS-PFM-MTD-018-13`, `TST-PFM-MTD-019`, `TST-PFM-MTD-045`	lifecycle	service	test services-platform:modules/associations/tests/integration/services/persistence/associations.integration.spec.js#refuses an end before the association started, leaving it open
`08`must prove Confirmed	Removing a dated link without an end date ends it today, removing a dated link with an end date deletes it as a correction, and undated links are deleted. origin: services-platform:docs/milestones/plans/PLAT-M6-plan.md#3. How it works (step 5) proved by `ATS-PFM-MTD-018-08`, `TST-PFM-MTD-045`	lifecycle	service	test services-platform:modules/associations/tests/integration/services/persistence/associations.in-force.integration.spec.js#removes a link that has an end date when it is deleted, correcting history, and ends one with none
`09`must prove Confirmed	Creation permits one thousand links per record and type on each side, counting current and ended links together, while merge can exceed that limit. origin: services-platform:docs/proposals/custom-objects/09-decisions.md#D-16 proved by `ATS-PFM-MTD-018-09`, `TST-PFM-MTD-044`, `TST-PFM-MTD-045`	validation	service	test services-platform:modules/associations/tests/integration/services/persistence/associations.integration.spec.js#refuses an association past the per-record limit of the type, writing nothing
`10`must prove Confirmed	Link lists use the current endpoint label and opposite record name, default to in-force links, offer ended history when requested and isolate workspaces. proved by `ATS-PFM-MTD-018-10`, `TST-PFM-MTD-017`, `TST-PFM-MTD-024`, `TST-PFM-MTD-036`	policy	service	test services-platform:modules/associations/tests/e2e/associations.e2e.spec.js#lists it on the organization’s path in the reverse direction, naming the contact
`11`must prove Confirmed	Relationship cards on custom, contact and organization pages expose permitted link actions and ended history, allowing standard users to maintain links while readers receive no actions. origin: services-platform:docs/milestones/plans/PLAT-M6-plan.md#PLAT-M6-S12 proved by `ATS-PFM-MTD-018-11`, `TST-PFM-MTD-026`, `TST-PFM-MTD-036`	permission	console, api	test react-console:acceptance/custom-objects/playwright/journeys/PLAT-M6-S12.spec.ts#PLAT-M6-S12: a standard user links, ends and removes but has no Relationship Types screen, and a read-only colleague sees no actions
`12` Confirmed	General relationships leave contact-to-organization affiliations under the separate CRM model. origin: services-platform:docs/proposals/custom-objects/09-decisions.md#D-04 (approved 2026-10-18)	policy	service	documented services-platform:docs/associations.md#Associations
`13`must prove Confirmed	Update locks refuse edits and ending, any lock refuses removal, and deactivation does not prevent maintenance of existing unlocked links. proved by `ATS-PFM-MTD-018-12`	policy	service	observed services-platform:modules/associations/services/persistence/associations.ts:updateAssociation

Scenarios

Id	Given	When	Then	Provenance
`01`	Tom charter on Osprey ends on the last day of November.	In October, request Maria charter from today and then from the first day of December.	The overlapping request identifies Tom dates and is refused, while the adjacent charter succeeds.	documented services-platform:docs/associations.md#1a. In force (PLAT-M6 D2)

Edge Cases

Id	Given	When	Then	Provenance
`02`	A member has two sponsor links.	Designate the second sponsor primary in the console.	Primary designation transfers to the second sponsor.	test react-console:acceptance/custom-objects/playwright/journeys/PLAT-M6-S07.spec.ts#PLAT-M6-S07: marking a second sponsor primary moves the primary flag

Planning

Implementation

Maintain Dated Links Between Records ​

Purpose ​

How It Works ​

Relationships ​