Limen Failure Modes & Use Case Catalog¶

Status: Living document.
Version: 0.1
Date: 2026-08-08

This document maps real insurance scenarios to the Limen architecture and identifies what can go wrong. The goal is not optimism. It is proof. If we cannot explain how the architecture survives a scenario, we cannot build it.

1. How to read this document¶

Each scenario follows this structure:

Scenario: The real-world insurance event.
Legacy pain: Why old systems break.
Limen handling: How the engines respond.
Failure modes: What can still go wrong.
Mitigation: How we prevent or recover.
Open questions: What we still need to validate.

2. Term life annual escalation¶

Scenario¶

A policyholder has a ZAR term life policy with a 5% annual escalation. On 1 April, the premium and sum assured must increase by 5%.

Legacy pain¶

Batch job runs overnight on the escalation date.
The batch updates millions of rows in place.
If the batch fails, half the policies are updated and half are not.
Audit trail is a log file, not part of the data model.

Limen handling¶

At contract creation, Kinetic calculates the escalation date and registers it as a scheduled event.
On the escalation date, a stateless worker picks up the event.
Quantum-Tree creates a new version (v5) with the increased sum assured and premium.
Fluid-GL appends an escalation adjustment entry.
The timeline shows the new version with the reason and DMN rule version.
The next scheduled collection event uses the new premium.

Failure modes¶

Failure	Effect	Mitigation
Worker misses the scheduled event	Escalation does not apply.	Use Redis sorted set with at-least-once processing. Monitor lag metrics.
DMN rule version changed before escalation	Calculation may differ from expected.	Escalation uses the DMN version pinned at the last contract modification. Rules are immutable.
Version creation succeeds but ledger append fails	Contract state and money diverge.	Outbox pattern. Roll back the version or append compensating entry. Alert on mismatch.
Multiple escalations scheduled for same day	Ordering matters.	Sequence numbers per contract. Events processed in effective-date order.

Open questions¶

How do we handle escalation dates that fall on public holidays?
What happens if a premium is already due on the escalation date?

3. Short-term property mid-term adjustment (MTA)¶

Scenario¶

A commercial property policy covers a building, machinery, and stock. The client buys new equipment mid-term and increases the sum assured for the machinery component.

Legacy pain¶

MTA is often a manual process with a new endorsement document.
The premium adjustment is calculated by a human or spreadsheet.
The system updates the premium balance in place, breaking the audit trail.
Backdated MTAs require complex corrections.

Limen handling¶

The client or broker submits the MTA via API or portal.
Quantum-Tree loads the current contract version.
DMN recalculates the premium for the changed component and the policy as a whole.
A new version (v6) is created with the new machinery sum assured and the adjusted premium.
Fluid-GL appends an MTA adjustment entry for the remaining days of the period.
Kinetic re-evaluates scheduled events (next collection, renewal, etc.).
The timeline shows the MTA node and the financial delta.

Failure modes¶

Failure	Effect	Mitigation
MTA is backdated to the start of the month	Premium delta must cover multiple days.	Kinetic calculates pro-rata delta based on effective date and UPP/EPP rules.
MTA changes multiple components	Delta calculation is complex.	DMN rule receives the full component tree and outputs a set of ledger entries.
Client rejects the new premium	Version must be superseded without losing history.	Create a reversal version. The original MTA version remains in the timeline.
DMN rule does not cover the new equipment type	Calculation fails or defaults.	DMN rule version must be updated before the MTA is accepted. Reject unknown types.

Open questions¶

Do we allow partial MTAs (e.g., only address change with no premium impact)?
How do we model component dependencies (e.g., machinery must have building cover)?

4. Credit life group retrenchment claim¶

Scenario¶

A credit life policy covers a group of borrowers. One borrower is retrenched. The claim must be paid, and the loan balance must be settled.

Legacy pain¶

The claim is a manual workflow with document verification.
The group policy must be updated to remove the borrower.
The general ledger, loan system, and policy system are separate.
Reconciliation is slow and error-prone.

Limen handling¶

Retrenchment event is ingested via employer feed or API.
Synapse triages the claim: checks retrenchment document, employer record, policy eligibility.
DMN rule decides claim validity and payout amount.
If approved, Fluid-GL appends a claim payment entry.
Quantum-Tree creates a new version with the borrower component terminated.
A settlement event is emitted to the loan system.
The timeline records the claim event and the termination.

Failure modes¶

Failure	Effect	Mitigation
Employer feed is delayed	Claim is paid after the borrower has already defaulted.	DMN rule checks effective date of retrenchment. Reject claims outside the eligibility window.
Borrower is not found in the group	Claim cannot be matched.	Graph-E party matching must be robust. Unmatched claims go to manual queue.
Payout amount exceeds remaining loan balance	Overpayment.	DMN rule caps payout at loan balance. Any excess is handled separately.
Claim is approved, but loan system is down	Settlement event is lost.	Outbox + retry. Idempotency on settlement event.

Open questions¶

How is the group policy premium adjusted after a member termination?
What happens if the retrenchment is later disputed or reversed?

5. Reinsurance cession¶

Scenario¶

A commercial property policy with a R 10 million sum assured is ceded 30% to a reinsurer. Premium and claim recovery must be split proportionally.

Legacy pain¶

Reinsurance is often tracked in spreadsheets outside the PAS.
Cession is calculated after the policy is written, leading to reconciliation errors.
Claims recovery requires manual billing and tracking.

Limen handling¶

The reinsurance treaty is modeled as a participation on the component.
When the premium is recorded, Fluid-GL appends multiple entries simultaneously:
R 70,000 retained by Fordsworth.
R 30,000 ceded to reinsurer.
When a claim occurs, the same proportion applies to recovery.
The ledger shows the cession from day one.

Failure modes¶

Failure	Effect	Mitigation
Treaty is not yet loaded	Cession cannot be calculated.	Reject policy creation until the treaty is active for the product line.
Premium is recorded before treaty effective date	Cession is wrong.	Kinetic checks treaty effective date. DMN rule applies treaty based on the event date.
Reinsurer disputes the cession calculation	Audit trail is needed.	Every cession entry references the treaty version and DMN rule version.
Non-proportional treaty applies	Simple percentage split is insufficient.	DMN rule handles layer, attachment point, and limit. Multiple participation rules per component.

Open questions¶

How do we handle multiple reinsurers on the same component?
How do we handle treaty renewals that change the cession rate mid-term?

6. Broker hierarchy commission override¶

Scenario¶

A broker is reassigned from one branch manager to another. The broker has 500 active policies. Commission must now flow to the new branch manager.

Legacy pain¶

A developer runs an UPDATE statement across thousands of policy records.
The update may fail halfway, leaving the database inconsistent.
Historical commission statements are wrong because the old structure is overwritten.

Limen handling¶

The broker is a party. The relationship to the branch manager is an edge in Graph-E.
To reassign, we terminate the old edge and create a new edge with the new branch manager.
The 500 contracts are not modified. They reference the broker by party ID.
The next commission calculation follows the new edge path.
Historical commission statements use the effective-time edges that were active at the time.

Failure modes¶

Failure	Effect	Mitigation
Edge change is backdated	Commission must be recalculated.	Graph-E supports effective dates on edges. Kinetic replays the affected commission periods.
Old branch manager disputes the change	Governance issue, not technical.	Edge changes require authorization. Audit log records who changed the edge and why.
Commission rule is tied to the old branch manager's tier	New branch manager may have different override.	DMN rule evaluates the hierarchy at the time of the premium event. The edge determines the routing.
Circular hierarchy created	Commission routing loops.	Graph-E validates the hierarchy as a DAG. Cycles are rejected.

Open questions¶

How do we handle commission clawbacks on downgrades or cancellations?
How do we model volume-based tier bonuses that depend on aggregate production?

7. Backdated child addition¶

Scenario¶

A client realizes that a child was not added to the policy at inception two years ago. The child must be added, and the premium and claims history must be recalculated.

Legacy pain¶

The correction requires manual updates to policy history, premium records, and claim records.
The audit trail is destroyed.
Actuarial and financial reporting becomes inconsistent.

Limen handling¶

The correction is submitted with an effective date two years ago.
Quantum-Tree creates a new fork from the version active at the effective date.
The child component is added to the fork.
Kinetic and DMN replay all scheduled events from the effective date to now.
The financial delta is calculated between the original timeline and the new fork.
A single correcting entry is appended to Fluid-GL with the current system date.
The original timeline remains intact. The new fork becomes the active timeline.

Failure modes¶

Failure	Effect	Mitigation
Replay is non-deterministic	Same inputs produce different outputs.	DMN rule versions are immutable. Use the same rule version that was active at the time.
Delta is huge	Client owes thousands in back premium.	DMN rule can cap the correction or apply grace rules. The business rule decides, not the code.
A claim was paid during the backdated period that would not have been paid	Recovery may be needed.	DMN rule and business process decide recovery. The system records the discrepancy.
Fork creation fails halfway	Timeline is corrupted.	Outbox pattern. The fork is atomic. Compensate if needed.

Open questions¶

How long can a backdated correction go? Is there a limit (e.g., 6 months, 2 years, unlimited)?
How do we handle backdated corrections that affect reinsurance treaties?

8. Bank rejection after 4 days¶

Scenario¶

A debit order is initiated on 1 April. On 4 April, the bank rejects the payment due to insufficient funds.

Legacy pain¶

The system held a "pending" status or locked the policy row for days.
Reconciliation requires manual matching of rejection files.
Late fees and retry rules are hardcoded in code.

Limen handling¶

On 1 April, the collection event is recorded and a "Premium Due" entry is optionally appended.
On 4 April, the bank rejection webhook arrives with the original payment reference.
The gateway checks the idempotency key for the rejection.
DMN rule evaluates the rejection: first rejection, second rejection, third rejection, etc.
Fluid-GL appends a "Premium Reversal" entry.
Quantum-Tree updates the policy status (e.g., PENDING_LAPSE) if the rule requires it.
Kinetic schedules the next retry or lapse event.
A communication event is emitted to notify the policyholder.

Failure modes¶

Failure	Effect	Mitigation
Rejection webhook is lost	Premium is never reversed.	Reconciliation process matches expected rejections against bank files. Idempotent re-delivery is safe.
Rejection arrives twice	Double reversal.	Idempotency key on the rejection reference.
Rejection is for a payment that was already manually matched	Conflict.	Manual match requires an idempotency key. System matches override manual entries only with authorization.
DMN rule says "lapse on third rejection" but first two rejections were reversed	Counting logic must be correct.	DMN rule counts non-reversed rejections. The ledger is the source of truth.

Open questions¶

How do we handle rejections that arrive weeks later due to bank batch processing delays?
How do we handle partial rejections (e.g., R 500 collected out of R 3,000)?

9. Cover-on-demand flight insurance¶

Scenario¶

A traveler buys flight insurance at boarding. The cover is active for the duration of the flight. On arrival, the cover is automatically canceled.

Legacy pain¶

Legacy systems are not designed for micro-duration policies.
Manual activation and cancellation are required.
Premium is not calculated pro-rata to the second.

Limen handling¶

Airline API sends a boarding event.
Quantum-Tree creates a flight component with a bound status.
Kinetic schedules an expiry event for the estimated arrival time.
Fluid-GL appends a premium entry for the micro-duration cover.
On arrival, the airline API sends a landing event.
Kinetic calculates the actual duration and final premium.
A new version sets the component status to EXPIRED.
A final ledger entry adjusts the premium to the exact duration.

Failure modes¶

Failure	Effect	Mitigation
Flight is delayed	Cover extends beyond the original expiry.	Kinetic reschedules the expiry event when the delay is known.
Landing event is missed	Cover remains active indefinitely.	Expiry event has a maximum bound. System expires after a safety window.
Traveler buys cover twice for the same flight	Double premium.	Idempotency key on (traveler, flight). Second request returns the existing cover.
Premium calculation requires external risk data (weather, route)	Latency increases.	Risk data is fetched asynchronously at quote time, not at binding time.

Open questions¶

How do we handle claims that occur during a flight (e.g., missed connection)?
How do we integrate with airline APIs reliably across carriers?

10. Discovery-style wellness premium adjustment¶

Scenario¶

A policyholder goes to the gym. The wellness data integration feeds a gym score. The next premium is adjusted downward based on the wellness score.

Legacy pain¶

Wellness integrations are typically batch interfaces.
Premium adjustments are manual or annual.
The system cannot react to individual behavior in real time.

Limen handling¶

Gym check-in event is ingested via telemetry API.
The event updates the policyholder's dynamic modifiers in the contract version.
DMN rule evaluates the wellness score and the new premium.
Kinetic schedules the next premium adjustment event.
Fluid-GL appends the adjustment when the premium is next due.
The policyholder receives a WhatsApp notification with the updated premium.

Failure modes¶

Failure	Effect	Mitigation
Wellness data is fraudulent	Premium is reduced incorrectly.	DMN rule includes fraud checks. Sudden score spikes are flagged.
Telemetry arrives out of order	Newer score is overwritten by older score.	Events are timestamped. Kinetic applies the latest known score at premium calculation time.
Wellness partner is down	Scores are stale.	DMN rule has a staleness threshold. Stale scores are ignored or capped.
Premium adjustment is too volatile	Customer complains.	DMN rule caps the adjustment per period and per year.

Open questions¶

Who owns the wellness data contract? Limen or the wellness partner?
How do we handle privacy consent for telemetry data under POPIA?

11. Lapse and reinstatement¶

Scenario¶

A policyholder misses three premium payments. The policy lapses. Two months later, the policyholder pays the arrears and requests reinstatement.

Legacy pain¶

Lapse is often a batch status update at month-end.
Reinstatement requires manual review and recalculation of cover.
Historical state of the policy during the lapse is hard to reconstruct.

Limen handling¶

Third rejection triggers the DMN lapse rule.
Quantum-Tree creates a new version with status LAPSED.
Fluid-GL appends a lapse entry and any required premium reversal.
All active components are terminated with effective dates.
On reinstatement request, DMN rule evaluates eligibility (medical evidence, arrears, etc.).
If approved, a new version sets status REINSTATED.
Arrears are recorded as premium entries. Cover is reactivated with effective dates.
The timeline shows the lapse and reinstatement nodes.

Failure modes¶

Failure	Effect	Mitigation
Lapse event is triggered too early	Customer is lapsed before grace period ends.	DMN rule enforces grace period. Lapse is a scheduled event, not immediate.
Reinstatement is backdated	Cover must be reinstated from a past date.	Bi-temporal fork. Replay from the requested effective date.
Medical evidence is required but missing	Cover should not be reinstated.	DMN rule blocks reinstatement until evidence is provided.
Arrears payment fails after reinstatement	Policy should lapse again.	Reinstatement is not final until the payment clears. Use conditional status.

Open questions¶

How do we handle reinstatement with new underwriting terms (e.g., loading due to health change)?
How do we handle claims that occur during the lapse period but are reported later?

12. IFRS 17 reporting¶

Scenario¶

The finance team needs IFRS 17 data: CSM, VFA, PAA, cohort cash flows, experience variances.

Legacy pain¶

IFRS 17 is a multi-year program separate from the PAS.
Data is extracted, transformed, and reconciled across multiple systems.
Actuarial models and the PAS disagree.

Limen handling¶

The ledger is the primary source of actuals.
Contract versions provide cohort tagging and historical data.
DMN rule versions provide the calculation basis.
Actuarial read model (ClickHouse) projects the data into IFRS 17 shapes.
The system feeds external actuarial engines with granular, auditable data.
External CSM adjustments are ingested back through the ledger-to-ledger module.

Failure modes¶

Failure	Effect	Mitigation
Cohort tagging is inconsistent	IFRS 17 grouping is wrong.	Cohort is assigned at contract creation and locked. Changes create a new version.
Read model is behind	Finance reports stale data.	Bounded lag SLA. Critical reports validate the projection watermark.
External actuarial engine produces different results	Reconciliation is needed.	Limen provides the granular inputs and the DMN rule version. The external engine must reconcile its own assumptions.
DMN rule version does not match the actuarial model	CSM release is wrong.	DMN rules are validated against the actuarial model before deployment. Rule version is the contract.

Open questions¶

Which IFRS 17 approach (GMM, VFA, PAA) is handled in Limen and which is delegated to an actuarial engine?
How do we handle the 30-year horizon of long-term liabilities in the read model?

13. Multi-cell POPIA scenario¶

Scenario¶

Fordsworth runs Limen for Sanlam in the South Africa cell, AVBOB in the South Africa cell, and a Kenyan insurer in the Kenya cell. A Sanlam customer moves to Kenya and asks to transfer their policy.

Legacy pain¶

Cross-border data transfer is legally restricted.
Separate systems cannot easily transfer a policy.
Customer experience is fragmented.

Limen handling¶

By default, a customer's PII does not cross the cell boundary.
The transfer request is routed to the governance API.
If the customer explicitly consents and the transfer is legally permitted, an export event is generated.
The contract is recreated in the Kenya cell. The original South Africa version is retained with a "transferred" status.
The financial ledger in Kenya starts from the transfer date.
Historical ledger entries remain in South Africa for regulatory reporting.

Failure modes¶

Failure	Effect	Mitigation
Transfer is attempted without consent	POPIA violation.	Denied by default. Consent is logged immutably.
Transfer is allowed but the product is not available in Kenya	Policy cannot be serviced.	Product availability is checked by the governance API before transfer.
Historical ledger data is requested by the Kenyan regulator	Data is in another cell.	Export is governed. Only anonymized or consented data moves.
Code is deployed to Kenya before South Africa	Inconsistent behavior.	GitOps deploys uniformly across cells, but data migrations are cell-specific.

Open questions¶

What is the exact legal mechanism for cross-cell consent under POPIA and Kenya Data Protection Act?
How do we handle a policy that spans multiple jurisdictions during its lifetime?

14. Common failure modes across all scenarios¶

Failure	When it happens	Mitigation
Duplicate event	Network retry, batch re-feed, webhook redelivery.	Idempotency keys at the gateway.
Out-of-order event	Asynchronous integrations, late bank files.	Sequence numbers per contract. Hold events until dependencies arrive.
DMN rule mismatch	Rule updated after a contract was created.	Pin DMN version per contract version. New rules apply to new versions or explicit migrations.
Redis loss	Cache failure, eviction, regional disaster.	Rebuild from ledger + event log. Ledger is the source of truth.
Ledger write conflict	Two commands for the same contract at the same time.	Per-contract serialization or optimistic locking with retry. The ledger itself is append-only, but the command ordering must be consistent.
Read model lag	High event volume, projection failure.	Critical operations do not depend on read models. Use the write model for real-time decisions.
AI proposal error	Misclassification, hallucination.	DMN gate. Human triage for high-risk decisions.
Cross-cell data leak	Misconfigured network, wrong API call.	Network isolation, deny-by-default, audit every cross-cell request.

15. Validation checklist for Phase 1¶

These scenarios must be tested against the first vertical slice:

[ ] Create a contract with one component.
[ ] Create a version for a premium escalation.
[ ] Record a premium and verify the ledger append.
[ ] Reverse a premium and verify the balance is computed correctly.
[ ] Backdate a correction and verify the fork + delta.
[ ] Simulate a bank rejection and verify the saga.
[ ] Change a broker edge and verify the commission routing.
[ ] Generate an actuarial projection from the ledger.
[ ] Verify that a read-model query does not touch the write model.
[ ] Verify that an idempotency key prevents duplicate processing.

Only after these pass do we expand the capability map.