Skip to content

Commit 0290d75

Browse files
rian-berian-be
committed
Docs: add Redis governance ADRs
1 parent f6e0809 commit 0290d75

3 files changed

Lines changed: 238 additions & 0 deletions

‎Docs/Decision/Adr/ADR_029_Governance_Redis_Provider_Package.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# ADR-029: Governance Redis Provider Package
2+
3+
## Tag
4+
#adr_029
5+
6+
## Status
7+
Accepted
8+
9+
## Date
10+
2026-06-25
11+
12+
## Scope
13+
ModularityKit.Mutator.Governance.Redis
14+
15+
## Context
16+
17+
The governance package already defines:
18+
19+
- durable mutation requests
20+
- optimistic concurrency around request revisions
21+
- request, approval, and decision query contracts
22+
- an in-memory implementation suitable for tests and examples
23+
24+
What remained open was a first persistence provider that can move governance state beyond in-memory storage without coupling `ModularityKit.Mutator.Governance` to a database-specific implementation.
25+
26+
The first provider needs to support:
27+
28+
- durable request document storage
29+
- optimistic concurrency for request updates
30+
- query-oriented reads over governed request data
31+
- simple application integration through DI
32+
33+
At the same time, this should remain separate from the governance abstractions package so provider-specific concerns do not leak into the base runtime API.
34+
35+
## Decision
36+
37+
Introduce a dedicated package:
38+
39+
- `ModularityKit.Mutator.Governance.Redis`
40+
41+
The provider should:
42+
43+
- implement `IMutationRequestStore`
44+
- implement `IMutationRequestQueryStore`
45+
- register through dedicated DI extensions
46+
- keep all Redis-specific logic inside the provider package
47+
- reuse governance query contracts instead of inventing a Redis-specific query surface
48+
49+
The provider should remain additive:
50+
51+
- `ModularityKit.Mutator.Governance` owns contracts and runtime semantics
52+
- `ModularityKit.Mutator.Governance.Redis` owns Redis persistence and Redis-specific internal read/write mechanics
53+
54+
## Design Rationale
55+
56+
- Governance contracts should stay provider-neutral.
57+
- Redis is a pragmatic first persistence backend for request-oriented workflows with simple document state and indexable queue views.
58+
- Package separation allows future providers such as EF Core or PostgreSQL without changing governance abstractions.
59+
- DI registration gives applications a low-friction way to switch from in-memory storage to Redis-backed storage.
60+
61+
## Consequences
62+
63+
### Positive
64+
65+
- Governance gets a real persistence provider beyond in-memory storage.
66+
- Redis-backed request and query implementations can evolve independently from governance contracts.
67+
- Future providers now have a clear packaging precedent.
68+
- Examples and tests can exercise a provider-backed read side without changing core governance APIs.
69+
70+
### Negative
71+
72+
- Provider package maintenance adds another surface to version and test.
73+
- Redis-specific internal design decisions must now be documented and kept coherent over time.
74+
- Query behavior remains contract-compatible but may have different performance characteristics than future relational providers.
75+
76+
## Related ADRs
77+
78+
- ADR-019: Governance Package Separation
79+
- ADR-022: Governance Request Decisions and Storage
80+
- ADR-026: Governance Request Query API

‎Docs/Decision/Adr/ADR_030_Governance_Redis_Request_Storage_and_Query_Strategy.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# ADR-030: Governance Redis Request Storage and Query Strategy
2+
3+
## Tag
4+
#adr_030
5+
6+
## Status
7+
Accepted
8+
9+
## Date
10+
2026-06-25
11+
12+
## Scope
13+
ModularityKit.Mutator.Governance.Redis
14+
15+
## Context
16+
17+
Once the Redis provider package exists, it still needs a concrete storage and read strategy.
18+
19+
Governed request data has two competing needs:
20+
21+
- writes should stay simple and durable
22+
- queue-oriented operational reads should avoid a full scan of every request whenever possible
23+
24+
The provider also needs to preserve governance runtime semantics such as:
25+
26+
- optimistic concurrency by request revision
27+
- storage-agnostic request query filtering
28+
- approval and decision projections built from parent request state
29+
30+
Without an explicit strategy, the Redis provider could drift into ad hoc key naming, inconsistent indexing, or duplicated query behavior that no longer matches the governance abstractions.
31+
32+
## Decision
33+
34+
The Redis provider stores one serialized request document per request and maintains a small set of Redis secondary indexes for common request-oriented reads.
35+
36+
Storage shape:
37+
38+
- one request JSON document per `MutationRequest`
39+
- one revision key per request for optimistic concurrency
40+
- set indexes for:
41+
- all request ids
42+
- requests by `StateId`
43+
- requests by `MutationRequestStatus`
44+
- all pending requests
45+
- pending requests by `PendingMutationReason`
46+
47+
Query shape:
48+
49+
- Redis index selection happens first through candidate-planning internals
50+
- matching request documents are then loaded in bulk
51+
- final filtering is applied through governance query evaluators, not Redis-specific ad hoc logic
52+
- approval views and decision views are projected from loaded parent requests after candidate selection
53+
54+
Internal provider structure should remain decomposed:
55+
56+
- candidate planning and execution
57+
- document key creation and payload loading
58+
- document materialization
59+
- read-side query orchestration
60+
61+
## Design Rationale
62+
63+
- Document-per-request storage maps naturally to the governance request model.
64+
- Separate revision keys give a simple optimistic concurrency mechanism in Redis transactions.
65+
- A small set of explicit secondary indexes improves the common queue and status reads without forcing the provider into a large custom indexing subsystem.
66+
- Reusing governance evaluators keeps provider behavior aligned with in-memory and future providers.
67+
- Internal decomposition makes Redis-specific read mechanics easier to evolve without turning one class into the entire provider.
68+
69+
## Consequences
70+
71+
### Positive
72+
73+
- Request writes stay simple and explicit.
74+
- Common operational views such as pending queues and state/status slices can be narrowed through Redis sets.
75+
- Query semantics remain aligned with governance abstractions because the final filter pass is evaluator-driven.
76+
- Internal provider responsibilities are easier to test and evolve independently.
77+
78+
### Negative
79+
80+
- Broad ad hoc queries still fall back to loading candidate request documents and filtering in memory.
81+
- Index maintenance increases write-path complexity compared to pure document storage.
82+
- Additional indexes may be needed later for higher-volume provider scenarios.
83+
84+
## Related ADRs
85+
86+
- ADR-022: Governance Request Decisions and Storage
87+
- ADR-026: Governance Request Query API
88+
- ADR-029: Governance Redis Provider Package

‎Docs/Decision/Adr/ADR_032_Governance_Redis_Concurrency_and_Index_Maintenance_Model.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# ADR-032: Governance Redis Concurrency and Index Maintenance Model
2+
3+
## Tag
4+
#adr_032
5+
6+
## Status
7+
Accepted
8+
9+
## Date
10+
2026-06-25
11+
12+
## Scope
13+
ModularityKit.Mutator.Governance.Redis
14+
15+
## Context
16+
17+
The Redis provider must preserve governance request semantics during updates, especially:
18+
19+
- optimistic concurrency by request revision
20+
- consistent request replacement on update
21+
- index maintenance for queue and lookup reads
22+
23+
Redis does not provide relational constraints or a built-in document update model. That means the provider must explicitly define how request documents, revision values, and secondary indexes are updated together.
24+
25+
Without an explicit model, the provider risks:
26+
27+
- lost updates when two actors write the same request concurrently
28+
- stale indexes that no longer match the latest request state
29+
- inconsistent pending queues after status or reason changes
30+
31+
## Decision
32+
33+
The Redis provider uses optimistic concurrency around a per-request revision value and treats document persistence plus secondary-index maintenance as one provider-level update operation.
34+
35+
The provider should:
36+
37+
- require expected revision matching on request updates
38+
- reject conflicting writes rather than silently overwrite newer request state
39+
- maintain Redis secondary indexes whenever request status, state, or pending reason changes
40+
- keep concurrency and index maintenance inside the write path, not in external repair code
41+
- model indexes as derivations of the canonical request document, not as independent sources of truth
42+
43+
## Design Rationale
44+
45+
- Governance request updates already assume optimistic concurrency semantics, so Redis should preserve that contract.
46+
- A canonical request document plus derived indexes is simpler than splitting state ownership across many Redis structures.
47+
- Explicit index maintenance keeps common reads fast enough without changing governance query semantics.
48+
- Rejecting conflicting writes is safer than last-write-wins for approval and lifecycle state.
49+
50+
## Consequences
51+
52+
### Positive
53+
54+
- Redis updates preserve governance revision semantics.
55+
- Secondary indexes remain tied to the latest canonical request state.
56+
- Pending queue views and status-based reads stay operationally useful.
57+
- Future providers can compare their concurrency model against a documented Redis baseline.
58+
59+
### Negative
60+
61+
- Write paths are more complex than pure document replacement.
62+
- Bugs in index maintenance can affect operational reads even when the canonical document is correct.
63+
- Higher write volumes may require further batching or index strategy refinement later.
64+
65+
## Related ADRs
66+
67+
- ADR-021: Governance Pending Mutation Lifecycle
68+
- ADR-022: Governance Request Decisions and Storage
69+
- ADR-029: Governance Redis Provider Package
70+
- ADR-030: Governance Redis Request Storage and Query Strategy

0 commit comments

Comments
 (0)