Document (and test) FIX

[Mitch5000]

================================================================================
PULL REQUEST

TITLE

docs(repositories): warn peekNextId() is synchronous-only and lock in behavior

BASE BRANCH

main

FEATURE BRANCH

fix/settlement-peeknextid-sync-warning

================================================================================
SUMMARY / MOTIVATION

SettlementRepository.peekNextId() returns the id that the next create() call
will assign, but it performs no locking. That guarantee is safe ONLY because
the store is an in-memory, single-process, synchronous implementation: Node's
event loop serializes all synchronous code, so nothing can interleave between a
caller reading peekNextId() and acting on it.

The method's name and existence invite misuse. If this repository is ever
swapped for an async-backed store (e.g. a real database), the previewed id
could be consumed by a concurrent caller between the peek and the create,
introducing a race that does not exist today.

This change makes that assumption explicit, locks in the current correct
behavior with a test, and flags the persistence-swap risk where the project
already documents "swappable for a persistent store later" intent.

This is a documentation + test-clarification change. No production behavior is
altered, so the risk of regression is effectively zero.

================================================================================
CHANGES

1. src/repositories/settlementRepository.ts

   • Expanded the JSDoc on peekNextId() with an explicit
     "SYNCHRONOUS-ONLY SAFETY GUARANTEE" warning. It now states that the method
     MUST NOT be used to predict/reserve an id across an awaited boundary, is
     safe only because create() is synchronous, and that any async-backed swap
     would break the atomicity guarantee. The returned id is described as a
     hint, not a reservation.

2. src/repositories/settlementRepository.test.ts

   • Added a "peekNextId" describe block with two tests:
     • previews the id that the immediately following create() yields
       (locks in the synchronous-only guarantee: peek -> immediate create
       returns the exact previewed id, and the counter advances by one)
     • yields a stable preview when no create() runs in between
   • Added a "save anchor reindex" test covering the previously uncovered
     anchor-change reindex branch in save(), lifting file coverage to 100%.

3. docs/ARCHITECTURE.md

   • Added a new section "In-Memory Repositories & Future Persistence" that
     documents the persistence-swap risk and lists required guardrails for any
     async-backed repository (allocate ids atomically in a single operation;
     never reserve across an await; keep the locking-in test green).

4. src/repositories/inMemoryRepository.ts

   • Added a source-level NOTE (async-swap risk) on generateId()/peekId()
     explaining that id allocation's atomicity depends on the synchronous,
     single-threaded store and would break under an async swap. Points readers
     to docs/ARCHITECTURE.md.

================================================================================
ACCEPTANCE CRITERIA MAPPING

[OK] peekNextId() carries an explicit doc-comment warning about its
synchronous-only safety guarantee.
-> settlementRepository.ts JSDoc on peekNextId().

[OK] A test locks in the current correct behavior.
-> settlementRepository.test.ts "previews the id that the immediately
following create() yields".

[OK] A note exists flagging the risk for any future async-backed repository
implementation.
-> docs/ARCHITECTURE.md "In-Memory Repositories & Future Persistence"
section, plus a source note in inMemoryRepository.ts.

================================================================================
TEST PLAN

• Run the settlement repository tests:
  npx jest src/repositories/settlementRepository --verbose
  Expect the two new peekNextId tests and the new save reindex test to pass.

• Run the full suite:
  npm test
  Expect all suites to pass (425 tests).

• Build:
  npm run build (tsc)
  Expect a clean compile with no type errors.

• Lint:
  npm run lint (eslint "src/**/*.ts")
  Expect no errors.

• Coverage (touched files):
  npx jest --coverage
  src/repositories/settlementRepository.ts -> 100%
  src/repositories/inMemoryRepository.ts -> 100%
  Exceeds the 95% guideline.

================================================================================
VALIDATION RESULTS (run locally before opening this PR)

Test Suites : 40 passed, 40 total
Tests : 425 passed, 425 total
Build (tsc) : clean, no errors
ESLint : clean, no errors
Coverage : settlementRepository.ts 100%, inMemoryRepository.ts 100%

================================================================================
FILES CHANGED

docs/ARCHITECTURE.md | 37 ++++++++++++++++++++++++
src/repositories/inMemoryRepository.ts | 15 +++++++++-
src/repositories/settlementRepository.test.ts | 41 ++++++++++++++++++++++++++
src/repositories/settlementRepository.ts | 25 ++++++++++++++-
4 files changed, 116 insertions(+), 2 deletions(-)

(No new files were created; all four are modifications.)

================================================================================
NOTE ON SUBMITTING

This change was prepared on the local branch
fix/settlement-peeknextid-sync-warning and committed. It could not be pushed or
opened automatically because this environment has no GitHub credentials / gh
CLI / push access to the upstream repository. To open the PR:

git push -u origin fix/settlement-peeknextid-sync-warning

then open a pull request from that branch into main on GitHub, using the TITLE
and SUMMARY above.

================================================================================

Closes #164