# Bug report: `@x12i/xronox-store` — classify deterministic Mongo errors as non-retryable

**Audience:** maintainers of `@x12i/xronox-store`  
**Origin:** `@x12i/activix` integration behavior under Mongo duplicate-key failures  
**Date:** 2026-03-30

---

## Summary

`xronox-store` currently retries queued persist operations without classifying MongoDB error types. Deterministic data/contract failures such as duplicate-key (`E11000` / code `11000`) are retried as if they were transient failures.

This causes repeated noisy failures and unnecessary queue churn while never succeeding.

---

## Why this should be fixed in `xronox-store` (not in consumers)

- `xronox-store` is the generic persistence layer that already owns queue/retry behavior.
- It should remain activity-agnostic: classification must be based on Mongo error code/labels, not domain fields (like `activityId`).
- Every consumer should benefit from the same retry policy without custom monkey-patching.

---

## Observed symptoms

- Persist error occurs once (for example duplicate key in Mongo).
- Queue retry path schedules additional attempts.
- Same error repeats until max retries.
- Final log is "max retries exceeded".

This is operationally confusing because the root cause is deterministic and non-retryable.

---

## Expected behavior

At minimum:

- Do **not** retry Mongo duplicate-key errors (`code === 11000`, `E11000`).
- Log once as non-retryable and drop the queued operation.

Preferably:

- Add a generic retry classifier in the store layer:
  - **Retryable:** connectivity/timeouts/network/transient labels
  - **Non-retryable:** duplicate-key, schema validation, immutable field, and other deterministic write contract errors

---

## Suggested API shape (optional)

Expose an optional classifier hook in `errorHandling`, with safe defaults:

- internal default classifier handles known Mongo codes
- optional override for advanced consumers

This keeps store behavior generic while allowing policy customization.

---

## Acceptance criteria

- `E11000` errors are not retried.
- Queue retry logic distinguishes transient vs non-retryable Mongo write failures.
- Logs clearly show non-retryable classification and immediate drop behavior.

---

## Reference in this repo

- Activix delegates persistence to `xronox-store` and expects store-level retry policy to be generic and code-based.