System side effect relations (#22882)

Closes twentyhq/core-team-issues#2667

## What

Default relations to the standard relation objects
(`timelineActivities`, `attachments`, `noteTargets`, `taskTargets`) are
now fully owned by the **metadata side-effect engine**. Neither the API
transpilers nor the SDK manifest builder provision them anymore: any
object creation, rename or deletion — regardless of the caller — goes
through the same engine handlers.

## Why

- Provisioning was duplicated across the API path and the SDK manifest
builder, with diverging behavior.
- Universal identifiers of relation fields were derived from object
**names**, so renaming an object mutated them and forced lossy
delete+create cycles on manifest sync.

## How

### Engine-owned lifecycle (side-effect handlers)

- `objectSystemRelationsOnCreate`: provisions the 8 forward/reverse
relation fields (+ join column indexes) when an object is created.
- `objectSystemRelationsOnUpdate`: renames the reverse morph fields
(`target<ObjectName>`) when their host object is renamed — a lossless
`fieldMetadata.update`.
- `objectSystemSideEffectsOnDelete`: cascades deletion of engine-owned
fields/indexes when the object is deleted.
- The API transpilers and the SDK `buildManifest` no longer inject these
fields; `isSystemSideEffect: true` marks engine-owned entities, guarded
by a granular property allowlist (only `isActive` is user-editable) and
excluded from manifest deletion inference.

### Name-free deterministic universal identifiers

New `getSystemRelationFieldUniversalIdentifier({
applicationUniversalIdentifier, objectUniversalIdentifier,
relationTargetObjectUniversalIdentifier })` in `twenty-shared`, exported
from `twenty-sdk/define`. The identifier is keyed on the two **object**
identifiers instead of field names (direction encoded by argument
order), so object renames never mutate relation field identifiers. It
cannot collide with the name-based `getFieldUniversalIdentifier`
derivation (field names cannot contain `:`).

### twenty-standard re-owned

All 48 forward/reverse system relation field declarations in
`STANDARD_OBJECTS` now pin the derived name-free identifiers (computed
inline via the shared util) and carry `isSystemSideEffect: true`, with
labels/icons declared explicitly (translated via `msg`).
`twenty-standard` is projected as if the engine had generated these
fields itself.

### 2.23 upgrade commands

- `reconcile-system-relation-field-universal-identifier`: structurally
matches existing default relation fields per workspace and backfills the
derived universal identifiers, `isSystemSideEffect` flags, and standard
labels/icons.
- `upgrade-people-data-labs-application`: upgrades installed PDL apps to
`1.0.7` right after the backfill to close the desync window (its views
reference the re-derived identifiers).

### Misc

- `people-data-labs` `1.0.7`: views temporarily pin the new derived
identifiers (TODO: import from the next released `twenty-sdk`).
- `UpgradeStatusModule` split out of `UpgradeModule` so the application
module cluster can consume upgrade status/migration services without
importing the versioned command bundles (fixes a require cycle that
crashed boot).
- Docs: `system-fields.mdx` documents the system relation fields and
their resolver; `sync-and-recovery.mdx` plan example no longer shows
auto-injected relations.

## Known red CI

`people-data-labs (dockerhub-latest)` fails by design until the 2.23
server image is published: the app pins the new identifiers which only
exist on a 2.23 server. The `local` leg (server built from this branch)
is green.

## System fields are no longer manifest-authorable (accepted regression)

The manifest converter no longer derives `isSystem` /
`isSystemSideEffect` from field names. Reserved-system-named manifest
fields (`id`, `createdAt`, `updatedAt`, `deletedAt`, `createdBy`,
`updatedBy`, `position`, `searchVector`) are now skipped at conversion
time when they carry the exact derived universal identifier (keeps
manifests built with older SDKs installable), and rejected with
`INVALID_INPUT` when they pin any other identifier. System fields are
therefore fully engine-canonical: nothing a manifest carries can produce
a system-flagged entity anymore.

**Accepted regression**: a manifest can no longer influence system field
properties at all. Previously a (legacy) re-declaration could shape them
at creation — which actually produced broken system fields, e.g. a
nullable, non-unique `id` — and could still toggle the allowlisted
`isActive` / `universalSettings` afterwards. We consider this acceptable
for now: per-app granularity over system fields will be reintroduced
later through the **override framework**, which will also settle update
semantics by forbidding direct updates over `isSystemSideEffect: true`
entities and expressing divergence as overrides.

`isSystemSideEffect`-only entities (the default relation fields
provisioned by this PR) still have no engine-level update guard (see
Follow-up below); that part is unchanged and also lands with the
overrides refactor.

## Follow-up

`isSystemSideEffect` field update/delete guards intentionally live at
the API layer (`sanitize-raw-update-field-input.ts`,
`from-delete-field-input-...util.ts`) rather than in the engine-level
`FlatFieldMetadataValidatorService`. Moving them into the validator
requires threading operation-origin (direct field mutation vs engine
cascade) through the migration matrix, otherwise legitimate object
rename/delete cascades (which carry `isSystemBuild=false`) would be
rejected. Tracked in twentyhq/core-team-issues#2671.

<!-- This is an auto-generated description by cubic. -->
<a
href="https://cubic.dev/pr/twentyhq/twenty/pull/22882?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
<!-- End of auto-generated description by cubic. -->

packages/twenty-server/src/engine/metadata-modules/flat-object-metadata/utils/from-create-object-input-to-flat-object-metadata-and-flat-field-metadatas-to-create.util.ts

@@ -7,30 +7,24 @@ import {
 import { v4 } from 'uuid';
 
 import { type FlatApplication } from 'src/engine/core-modules/application/types/flat-application.type';
-import { type AllFlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/all-flat-entity-maps.type';
 import { type CreateObjectInput } from 'src/engine/metadata-modules/object-metadata/dtos/create-object.input';
 import { buildNameFlatFieldMetadataForCustomObject } from 'src/engine/metadata-modules/object-metadata/utils/build-name-flat-field-metadata-for-custom-object.util';
-import { buildDefaultRelationFlatFieldMetadatasForCustomObject } from 'src/engine/metadata-modules/object-metadata/utils/build-default-relation-flat-field-metadatas-for-custom-object.util';
 import { type UniversalFlatFieldMetadata } from 'src/engine/workspace-manager/workspace-migration/universal-flat-entity/types/universal-flat-field-metadata.type';
-import { type UniversalFlatIndexMetadata } from 'src/engine/workspace-manager/workspace-migration/universal-flat-entity/types/universal-flat-index-metadata.type';
 import { type UniversalFlatObjectMetadata } from 'src/engine/workspace-manager/workspace-migration/universal-flat-entity/types/universal-flat-object-metadata.type';
 
 type FromCreateObjectInputToFlatObjectMetadataAndFlatFieldMetadatasToCreateArgs =
   {
     createObjectInput: CreateObjectInput;
     flatApplication: FlatApplication;
-  } & Pick<AllFlatEntityMaps, 'flatObjectMetadataMaps'>;
+  };
 
 export const fromCreateObjectInputToFlatObjectMetadataAndFlatFieldMetadatasToCreate =
   ({
     createObjectInput: rawCreateObjectInput,
     flatApplication,
-    flatObjectMetadataMaps: existingFlatObjectMetadataMaps,
   }: FromCreateObjectInputToFlatObjectMetadataAndFlatFieldMetadatasToCreateArgs): {
     flatObjectMetadataToCreate: UniversalFlatObjectMetadata & { id: string };
     flatFieldMetadataToCreateOnObject: UniversalFlatFieldMetadata[];
-    relationTargetFlatFieldMetadataToCreate: UniversalFlatFieldMetadata[];
-    flatIndexMetadataToCreate: UniversalFlatIndexMetadata[];
   } => {
     const createObjectInput =
       trimAndRemoveDuplicatedWhitespacesFromObjectStringProperties(
@@ -105,25 +99,11 @@ export const fromCreateObjectInputToFlatObjectMetadataAndFlatFieldMetadatasToCre
             },
           });
 
-    const {
-      standardSourceFlatFieldMetadatas,
-      standardTargetFlatFieldMetadatas,
-      standardTargetFlatIndexMetadatas,
-    } = buildDefaultRelationFlatFieldMetadatasForCustomObject({
-      existingFlatObjectMetadataMaps,
-      sourceFlatObjectMetadata: universalFlatObjectMetadataToCreate,
-      flatApplication,
-    });
-
-    const flatFieldMetadataToCreateOnObject: UniversalFlatFieldMetadata[] = [
-      ...(isDefined(nameFlatFieldMetadata) ? [nameFlatFieldMetadata] : []),
-      ...standardSourceFlatFieldMetadatas,
-    ];
+    const flatFieldMetadataToCreateOnObject: UniversalFlatFieldMetadata[] =
+      isDefined(nameFlatFieldMetadata) ? [nameFlatFieldMetadata] : [];
 
     return {
       flatObjectMetadataToCreate: universalFlatObjectMetadataToCreate,
       flatFieldMetadataToCreateOnObject,
-      relationTargetFlatFieldMetadataToCreate: standardTargetFlatFieldMetadatas,
-      flatIndexMetadataToCreate: standardTargetFlatIndexMetadatas,
     };
   };

packages/twenty-server/src/engine/metadata-modules/flat-object-metadata/utils/from-delete-object-input-to-flat-field-metadatas-to-delete.util.ts

@@ -59,6 +59,10 @@ export const fromDeleteObjectInputToFlatFieldMetadatasToDelete = ({
     });
   const flatFieldMetadatasToDelete = objectFlatFieldMetadatas.flatMap(
     (flatFieldMetadata) => {
+      if (flatFieldMetadata.isSystemSideEffect === true) {
+        return [];
+      }
+
       if (
         isMorphOrRelationFlatFieldMetadata(flatFieldMetadata) &&
         flatFieldMetadata.relationTargetObjectMetadataId !==
@@ -87,6 +91,10 @@ export const fromDeleteObjectInputToFlatFieldMetadatasToDelete = ({
   ).filter(
     (flatIndex): flatIndex is FlatIndexMetadata =>
       isDefined(flatIndex) &&
+      !(
+        flatIndex.isSystemSideEffect === true &&
+        flatIndex.objectMetadataId === flatObjectMetadataToDelete.id
+      ) &&
       (flatIndex.objectMetadataId === flatObjectMetadataToDelete.id ||
         flatIndex.flatIndexFieldMetadatas.some((flatIndexField) =>
           fieldIdsToDelete.has(flatIndexField.fieldMetadataId),

packages/twenty-server/src/engine/metadata-modules/flat-object-metadata/utils/handle-flat-object-metadata-update-side-effect.util.ts

@@ -53,6 +53,7 @@ export const handleFlatObjectMetadataUpdateSideEffect = ({
           toFlatObjectMetadata,
           flatObjectMetadataMaps,
           flatIndexMaps,
+          systemSideEffectMorphFieldsOnly: false,
         })
       : {
           morphRelatedFlatIndexesToUpdate: [],

packages/twenty-server/src/engine/metadata-modules/flat-object-metadata/utils/rename-related-morph-field-on-object-names-update.util.ts

@@ -3,6 +3,7 @@ import {
   type FieldMetadataType,
   type FromTo,
 } from 'twenty-shared/types';
+import { capitalize } from 'twenty-shared/utils';
 
 import { computeMorphOrRelationFieldJoinColumnName } from 'src/engine/metadata-modules/field-metadata/utils/compute-morph-or-relation-field-join-column-name.util';
 import { computeMorphRelationFlatFieldName } from 'src/engine/metadata-modules/field-metadata/utils/compute-morph-relation-flat-field-name.util';
@@ -52,9 +53,15 @@ const updateMorphFlatFieldName = ({
       })
     : undefined;
 
+  const newLabel =
+    fromMorphFlatFieldMetadata.isSystemSideEffect === true
+      ? capitalize(toRelationTargetFlatObjectMetadata.nameSingular)
+      : fromMorphFlatFieldMetadata.label;
+
   return {
     ...fromMorphFlatFieldMetadata,
     name: newMorphFieldName,
+    label: newLabel,
     universalSettings: {
       ...fromMorphFlatFieldMetadata.universalSettings,
       joinColumnName: newJoinColumnName,
@@ -69,7 +76,9 @@ type RenameRelatedMorphFieldOnObjectNamesUpdateArgs = FromTo<
   Pick<
     AllFlatEntityMaps,
     'flatFieldMetadataMaps' | 'flatObjectMetadataMaps' | 'flatIndexMaps'
-  >;
+  > & {
+    systemSideEffectMorphFieldsOnly: boolean;
+  };
 
 type RenameRelatedMorphFieldOnObjectNamesUpdateReturnType = {
   morphFlatFieldMetadatasToUpdate: UniversalFlatFieldMetadata<FieldMetadataType.MORPH_RELATION>[];
@@ -81,6 +90,7 @@ export const renameRelatedMorphFieldOnObjectNamesUpdate = ({
   flatFieldMetadataMaps,
   flatObjectMetadataMaps,
   flatIndexMaps,
+  systemSideEffectMorphFieldsOnly,
 }: RenameRelatedMorphFieldOnObjectNamesUpdateArgs): RenameRelatedMorphFieldOnObjectNamesUpdateReturnType => {
   const objectFlatFieldMetadatas =
     findManyFlatEntityByIdInFlatEntityMapsOrThrow({
@@ -92,7 +102,11 @@ export const renameRelatedMorphFieldOnObjectNamesUpdate = ({
     getFlatObjectMetadataTargetMorphRelationFlatFieldMetadatasOrThrow({
       flatFieldMetadataMaps,
       objectFlatFieldMetadatas,
-    });
+    }).filter(
+      (morphFlatFieldMetadata) =>
+        (morphFlatFieldMetadata.isSystemSideEffect === true) ===
+        systemSideEffectMorphFieldsOnly,
+    );
 
   const initialAccumulator: RenameRelatedMorphFieldOnObjectNamesUpdateReturnType =
     {