Common event framework

Ownership and reusable definitions

EventDefinition → Requirements defines a reusable event and its obligations. ProjectEvent → EventRequirement owns the instantiated obligations and freezes their definition/TimeLimit values. EventSubject connects arbitrary domain records through EntityNode. EventEvidence supports completion; EventDependency gates it; EventTransition retains lifecycle history.

Pure cross-project requirement definitions use Scope = Event and EventDefinitionId. Existing task, programme, safety, competency, deferred, part and resource requirement definitions remain reusable. Only active, non-container requirements are instantiated. Mandatory requirements block completion until Satisfied, Waived or NotApplicable; waivers/non-applicability require a separate permission and reason.

Common lifecycle

Draft → Planned → InProgress → Completed. Planned/InProgress may move to OnHold; OnHold may return to Planned/InProgress. Non-terminal occurrences may be Cancelled. Completed and Cancelled are immutable. Completion requires resolved mandatory obligations, evidence when configured, and completed prerequisite events. Dependencies cannot form cycles.

Existing domain events

When enabled, AppDbContext registers MaintenanceEventMaster, ComponentWorkpackageEvent, MaterialFlowEvent, PowerplantEvent, ComponentReplacementEvent, MaintenanceControlEvent, EngineEventLog and ProductionExecution in the same transaction as their source save. Their lifecycle is changed through the existing controlled domain operation; evidence and added compliance obligations use the common framework. EngineEventLog is a recorded factual occurrence, and an unconfirmed PowerplantEvent remains Draft.

Source state, definitions, evidence and occurrence identity are connected through EntityNode. Domain-specific counters, engineering payloads, inventory actions, signed report-back and recurrence remain on the existing source/services. CriticalEvent is a category definition and TechnicalCaseRootCauseEventAssignment is a relationship; neither is an occurrence to duplicate. Legacy source tables are retained during review. Existing records need an explicit reviewed backfill before the shared event list is complete.

Example: component overhaul

1. Define “Component overhaul” and add reusable inspection, test and release Requirements with EventDefinitionId.
2. Create an occurrence for the pump’s EntityNode; attach the package/order/step nodes as Execution subjects. Its event requirements store the approved definition snapshot.
3. Start work, append measurement/test/document nodes as evidence, and resolve each requirement using that evidence.
4. Complete the overhaul after its prerequisite removal event is Completed. The common service checks every mandatory obligation and records an immutable transition.
5. A later overhaul uses a new occurrence, so subsequent definition revisions do not rewrite the earlier compliance history.

API and activation

/api/event-framework/definitions and /api/event-framework/events support creation/listing; occurrence details include requirements, subjects, evidence, dependencies and history. Controlled operations are events/{id}/subjects, dependencies, evidence, transition and requirements/{requirementId}/resolve. Every update sends ExpectedVersion.

Permissions: controller.eventdefinition.read/created, controller.projectevent.read/created/updated and controller.projectevent.waived. After reviewed schema migration, source backfill and permission setup, set EventFramework:Enabled = true (environment: EventFramework__Enabled=true). Until then, operations return a pending-activation response and automatic source registration remains off.

Frontend routing, external message dispatch, notifications and bulk backfill are not implemented in this change. This is the shared backend framework and review catalog; no legacy event table is marked Dropped by this change.

Suggested next common frameworks

Recommended order below. These are suggestions for project review; no additional tables have been created for them.