Purpose

Announces that something canonical about a key changed: its label, its spec/control/group references, its usage set, or its isSystem flag. It is emitted only when a value actually changed — a no-op update dispatches nothing, which keeps Airtable “when record updated” automations from looping.

Payload

Envelope is { name, occurredAt, payload } (apps/api-v1/src/modules/shared/domain/events/DomainEvent.ts).

Field	Type	Meaning
parameterKeyId	ParameterKeyId	Key that changed
name	string	Canonical label after the change
parameterSpecId	string | null	Value-semantics reference after the change
parameterControlId	string | null	Presentation reference after the change
parameterGroupId	string | null	Authoring-group reference after the change
updatedAt	Date	When the change was applied

The payload deliberately carries neither lifecycleStatus nor usage, so every handler that needs either re-reads the key from ForStoringParameterKeys rather than trusting the event.

Raised by

apps/api-v1/src/modules/bim-ontology/core/domain/parameter-key/ParameterKey.ts:

• updateCanonicalMetadata — rename, re-describe, re-reference, re-usage
• addUsages — unions usages onto the key, idempotently
• markSystem — sets isSystem (requires approved plus usage:bim_parameter)

Use cases in core/application/use-cases/ParameterKeyAuthoringUseCases.ts: UpdateParameterKeyUseCase.updateParameterKey, AssignParameterKeyToGroupUseCase.assignParameterKeyToGroup.

HTTP: updateParameterKey, assignParameterKeyToGroup.

Consumers

Three handlers are registered in apps/api-v1/src/modules/bim-ontology/composition/bim-ontology.composition.ts, all under adapters/inbound/events/:

Handler	Effect
ParameterKeyUpdatedProjectionEnsureHandler	Guarded. Reloads the key and acts only when it is already approved and carries usage:bim_parameter; then calls EnsureRevitProjectionForParameterKeyUseCase to repair a missing projection. Anything else is recorded as handled and skipped
ArchiveRevitProjectionOnParameterKeyRetirementHandler	Reloads the key and archives the linked projection when it is no longer approved or has lost usage:bim_parameter. Archives, never deletes
CanonicalProjectionMetadataChangedHandler	Calls ResyncDerivedProjectionMetadataUseCase.resyncForParameterKey, refreshing derived (non-overridden) Revit names

The first two are effectively complementary: ensure runs for approved BIM keys, archive-on-retirement runs for everything else. All three key their idempotency off the event’s own identity, never off projection state.

Related

• ParameterKey, RevitParameterProjection
• ParameterKeyApproved — the event that mints the projection in the first place
• ParameterKeyArchived — the unconditional retirement path