test: concurrent revision-authority stress scenario (#236)

[mberrys]

Why

#236 makes PDFDocumentContext the single revision authority for caches and asynchronous results, and states the issue stays open until "identity-separation tests, revision-bound cache/job tests, stale-result rejection, and the concurrent stress scenario pass".

Reading dev, the first three are already covered by work that landed from PRs #254/#258:

• PDFDocumentContext / PDFRevisionIdentity (alias PDFRevisionToken) own the fence, separate from persisted PDFArtifactIdentity (UnitTestsIdentitySeparation);
• PDFDocumentSession cache keys carry the revision, and PDFJobScheduler discards results whose revision is no longer current (UnitTestsDocumentSession, UnitTestsJobScheduler);
• the interaction layer publishes the fence through IJobSubmitter and keys surface caches by revision.

The acceptance criterion with no coverage was the stress scenario itself. The existing UnitTestsDocumentSession/concurrentScheduledResults_rejectSupersededRevisions proves the fence in one orchestrated round — every producer is released after the mutation — which is not the hostile workload the issue describes.

What changed

UnitTests/tst_revisionstresstest.cpp (new target UnitTestsRevisionStress) runs the acceptance scenario: render, preflight, thumbnail, and repair-plan jobs in flight together across 64 rounds while the document is mutated and the effective profile changes at points the producers do not observe. Results are admitted through a single revision-gated consumer that models the findings model, the tile presenter, and the evidence cache under one mutex covering the fence and the retained entries together.

It asserts the four properties the issue names:

1. zero stale findings applied;
2. zero stale tiles presented as current past an invalidation boundary;
3. deterministic cancellation — cancelled work is terminal, is never success, and publishes nothing;
4. no cache read ever returns a result for the wrong revision.

A stress test that quietly stops exercising the fence is worse than none, so the non-vacuity checks are deterministic rather than timing-based:

• one phase submits results against the current revision and asserts they are admitted and read back as current (a fence that rejected everything would otherwise pass);
• a second phase holds one producer per job kind inside its work function, mutates the document underneath all of them, and only then releases them — asserting both the consumer-side rejection and the scheduler-side Stale outcome.

A third test walks PDFDocumentSession across document mutations and profile changes, asserting the session follows the context and drops its compiled-page cache rather than reconciling it.

Also: policy test mapping (agent-policy.json), the generated architecture catalog and Phase 5 widgets inventory, the pinned Phase 5 target count (67 → 68), the changelog fragment, and the #236 rows in docs/REVISION_CONTEXT.md, docs/SEMANTIC_TRUST_ENGINE_ACCEPTANCE.md, and docs/UPSTREAM_DIVERGENCE.md.

No production code changed.

Proof

All checks are green on 8a6cb91. The agent-fast / build job ran check-change.py end to end with "status": "pass":

• build:UnitTestsRevisionStress — pass (compiles and links against Qt 6.11.1);
• focused_tests — 25/25 ctest targets passed, including UnitTestsRevisionStress;
• clang_tidy:UnitTests/tst_revisionstresstest.cpp — pass;
• changelog, source integrity, architecture catalog, and policy adapters — pass.

source_integrity, policy, architecture-docs, and CodeQL are also green.

The earlier revision of this description said the build and test evidence was unproven; that was true when the PR was opened (this session has no Qt toolchain, so check-change.py could only run the source-level checks locally) and CI has since supplied it. The two red checks along the way were both generated-evidence bookkeeping that follows from adding a target — a stale docs/generated/phase5-widgets-inventory.json and the Phase 5 contract test's pinned target count — fixed in f4ba214 and 8a6cb91.

UnitTests/CMakeLists.txt is a protected path; the change to it is additive (one new test executable plus its add_test) and introduces no new public contract.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MaL7wNZgrcZibFiBZenb6t