Skip to content

[Task]: Decompose governance mutation request model #42

Description

@rian-be

Summary

Decompose MutationRequest into smaller concern oriented components before the request root turns into another flat governance bag of fields.

Goal

Keep MutationRequest as the aggregate root while moving lifecycle, execution, and request payload details into explicit submodels with clearer ownership.

Problem

MutationRequest currently carries target identity, request payload, approval requirements, lifecycle state, execution outcome, concurrency metadata, and request metadata on one flat record. As governance keeps adding persisted runtime fields such as typed side effects and richer execution data, the request model becomes harder to read, evolve, and reason about consistently across runtime, Redis, and query code.

Scope

  • Define decomposition plan for MutationRequest into grouped concern-oriented records
  • Extract lifecycle oriented fields into an explicit lifecycle component
  • Extract execution oriented fields into an explicit execution component
  • Extract target/request payload fields into explicit scope or payload components where appropriate
  • Align runtime, Redis serialization, and query flows with the decomposed request model
  • Update docs and examples where the request shape is part of the public usage surface

Design Expectations

  • MutationRequest should remain the root model, not disappear behind a builder or hidden mapper.
  • The decomposition should follow actual governance concerns rather than arbitrary technical grouping.
  • Runtime and Redis flows should become easier to maintain, not more indirect.
  • Query and persistence code should read more clearly after the split, especially around lifecycle and execution data.
  • The resulting model should make it obvious which data is request intent, which is lifecycle state, and which is execution outcome.

Acceptance Criteria

  • MutationRequest no longer stores all major governance concerns as one flat field list
  • Lifecycle and execution data have explicit submodels with coherent boundaries
  • Redis and in-memory governance persistence round-trip the decomposed model correctly
  • Query, runtime, and example code remain readable after the refactor
  • The new structure reduces the need to keep expanding a single request record over time

Non-Goals

  • This issue does not redesign governance query contracts by itself
  • This issue does not require a new builder or fluent API for request creation
  • This issue does not change optimistic concurrency semantics unless needed by the refactor
  • This issue does not replace MutationRequest with multiple top level public models

Notes

Implemented decomposition:

  • MutationRequest.Scope now groups target identity in MutationRequestScopeDetails.
  • MutationRequest.Payload now groups submitted intent and requester context in MutationRequestPayloadDetails.
  • MutationRequest.Lifecycle now groups lifecycle state and timestamps in MutationRequestLifecycleDetails.
  • MutationRequest.Execution and MutationRequest.Versioning continue to own governed execution and versioning concerns.
  • Runtime lifecycle, approval, resolution, execution, in-memory query materialization, Redis serialization, and governance examples were aligned to the decomposed request shape.

This keeps MutationRequest as the root model while making concern ownership explicit and reducing pressure to keep growing one flat request record.

Metadata

Metadata

Assignees

Labels

abstractionsPublic abstractions and contracts

Type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions