Proof Watcher (Change Stream)

Version: 1.1.0 Date: 2026-07-15

Goal: Automatically trigger certificate ZIP generation when a proof is confirmed in MongoDB, to validate the Hotep certificate pipeline in real conditions without manual testing.

Solution: MongoDB Change Stream on the proofs collection, listening for inserts and updates where status becomes confirmed. Triggers ZipService.generateZipSystem() via a p-queue concurrency limiter. Controlled by PROOF_WATCHER_ENABLED env var (default false).

Features:

• Change Stream watches both insert (status=confirmed) and update (status changed to confirmed)
• p-queue concurrency control via WATCHER_CONCURRENCY env var (default 2)
• Accurate result logging: OK / partial (N/M failed) / crashed per document
• generateZipSystem returns { total, failed } for precise reporting
• System-level ZIP generation without auth context (resolves user from document's jobRef)
• Feature flag: disabled by default, enable with PROOF_WATCHER_ENABLED=true
• Graceful cleanup on module destroy (closes Change Stream cursor, clears queue)
• Temporary feature: meant to be removed after production validation of Hotep ZIP pipeline

Files Modified:

• src/core/proof-watcher/proof-watcher.service.ts - Change Stream listener with p-queue concurrency control
• src/core/proof-watcher/proof-watcher.module.ts - NestJS module (imports DocumentModule for ZipService)
• src/domains/document/zip.service.ts - generateZipSystem returns stats, addProofAndCertificate returns boolean
• src/domains/document/document.module.ts - Export ZipService for cross-module injection
• src/core/hotep/hotep.service.ts - Simplified (removed semaphore, Browserless now self-hosted)
• src/app.module.ts - Conditional import of ProofWatcherModule

Release fragment: feat-proof-watcher