feat(merge-users): dry-run/run framework, handler registry and coverage manifest (#17494)

[Ludovic Bouges (ludovic)]

Proposed changes

• Adds the user reference register as a versioned constant: 100 rows, each with a stable id, a disposition, an entity and a field path. Row ids are never renumbered. The per-row analysis stays in the specification.
• Adds the MergeHandler contract. A handler exposes compute() (reads only) and apply() (writes only); the engine derives both execution modes from them, so dry-run is compute and the real run is compute then apply. A handler has no second code path that could drift from the first.
• Adds the handler registry. A handler declares the register rows it covers, the register version it was written against, and its read and write field sets. Registration rejects an unknown row id, a stale register version, a row already claimed by another handler, and a read set intersecting another handler's write set.
• Adds the two-pass engine. Every handler computes, the full report is produced, then every handler writes. Handlers are never interleaved, so a handler's computation always observes the same platform state in both modes. Before writing, each handler recomputes and its plan fingerprint is compared against the dry pass; a mismatch aborts without writing, since the platform is required to be at rest during a merge. Read/write disjointness is re-checked before each run, not only at registration. A failure returns a FAILED result carrying the merge id rather than throwing, because what was applied is only readable from the journal.
• Adds the coverage manifest, derived from the register rather than from the registered handlers, so an uncovered row is named rather than absent. is_complete is true only when every row is claimed. A disposition filter narrows the returned rows but never the counts. Exposed as userMergeCoverage and attached to every execution report.
• Adds the bulk write primitive: conflicts: 'abort', wait_for_completion: true, refresh: true, throwing when failures is non-empty or version_conflicts is greater than zero, and returning the updated count.
• Adds the execution journal: one entry per handler and per pass, opened before the handler runs and closed with its outcome, so a handler that throws leaves a FAILED entry. Stored in Redis with a 30 day TTL, keyed per entry and indexed in a sorted set globally and per merge id, following the existing playbook-execution pattern.

No handler is registered in this chunk, so a merge still performs no write. Handlers land from #17495 onward.

Related issues

• closes PR2 — Merge engine: handler registry + dry-run/run framework + coverage manifest #17494 — part of feat(userManagement): Merge users #17258

How to test this PR

Stacked on #17507, so review the last 7 commits only. Enable the flag and start the platform:

export APP__ENABLED_DEV_FEATURES='["MERGE_USERS"]'
yarn start

With no handler registered, the coverage manifest must list all 100 register rows as uncovered, by name:

curl -s http://localhost:4000/graphql \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $OPENCTI_TOKEN" \
  -d '{"query":"{ userMergeCoverage { covered_count uncovered_count is_complete uncovered_rows { id disposition entity path } } }"}'

Filtering by disposition must narrow the returned rows while leaving the counts on the whole register:

curl -s http://localhost:4000/graphql \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $OPENCTI_TOKEN" \
  -d '{"query":"{ userMergeCoverage(disposition: TRANSFER) { covered_count uncovered_count uncovered_rows { id } } }"}'

Run a dry merge and read the journal back with the returned id:

curl -s http://localhost:4000/graphql \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $OPENCTI_TOKEN" \
  -d '{"query":"mutation { userMerge(sourceId:\"<source>\", targetId:\"<target>\", options:{dryRun:true}) { merge_id status report { coverage { is_complete } } } }"}'

curl -s http://localhost:4000/graphql \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $OPENCTI_TOKEN" \
  -d '{"query":"{ userMergeJournal(mergeId:\"<merge_id>\") { handler pass status updated } }"}'

The journal entries live in Redis and survive a platform restart for 30 days.

Automated coverage:

npx vitest run --config vitest.config.ci-unit.ts tests/01-unit/modules/userMerge
npx vitest run --config vitest.config.dev.ts tests/03-integration/10-modules/userMerge

Checklist

• I consider the submitted work as finished
• I tested the code for its functionality
• I wrote test cases for the relevant use cases (coverage and e2e)
• I added/updated the relevant documentation (either on GitHub or on Notion)
• Where necessary, I refactored code to improve the overall quality

Further comments

48 unit tests and 21 integration tests. Notable cases: with zero handler registered the manifest lists all 100 register rows as uncovered by name; a filtered manifest keeps its counts on the whole register; a real pass whose recomputation diverges from the dry pass writes nothing; per-disposition register counts are asserted as literals rather than recomputed from the array.

Commit by commit:

Commit	Contents
fc4278de	user reference register, as a versioned constant (100 rows, v2)
c8fa927b	MergeHandler contract and handler registry
5e539e76	bulk write primitive
68b90751	execution journal
422eeca9	two-pass engine
60558cc6	coverage manifest and its API
63ccabcb	journal storage moved to Redis

The precedent in the platform, SanityOperation, exposes dryRun() and run() as two methods each implementation writes, relying on both happening to call the same helper. That is a convention, and conventions drift the day someone fixes a bug in one branch and forgets the other. Here there is a single selection function, so "dry-run equals real impact" cannot drift.

[codecov]

Codecov Report

❌ Patch coverage is 97.86096% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 34.18%. Comparing base (319ad5d) to head (63ccabc).

Files with missing lines	Patch %	Lines
...graphql/src/modules/userMerge/userMerge-journal.ts	91.66%	2 Missing ⚠️
...raphql/src/modules/userMerge/userMerge-coverage.ts	96.55%	1 Missing ⚠️
...graphql/src/modules/userMerge/userMerge-handler.ts	90.90%	1 Missing ⚠️

Additional details and impacted files

@@               Coverage Diff               @@
##           issue/17493   #17535      +/-   ##
===============================================
- Coverage        34.39%   34.18%   -0.22%     
===============================================
  Files             3381     3386       +5     
  Lines           138611   137814     -797     
  Branches         37741    37256     -485     
===============================================
- Hits             47676    47109     -567     
+ Misses           90935    90705     -230     

Flag	Coverage Δ
opencti-client-python	48.37% <ø> (ø)
opencti-front	10.98% <ø> (+0.01%)	⬆️
opencti-graphql	69.26% <97.86%> (-0.20%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.