Release: LeadForge OS v1.1.1-beta.5 (Phases 1-12 & Runtime Fixes)

[kjxcodez]

Overview

This pull request promotes all qualified changes on dev to main for the LeadForge OS production release (v1.1.1-beta.5).

The release consolidates the full architectural progression from Phase 1 through Phase 12, along with the two most recent production fixes addressing DiscoveryRun Cascade Deletion and Workspace Switching & Creation Rehydration. All modifications adhere to LeadForge's core architecture invariant:

• MongoDB is the authoritative business and execution state.
• SQLite is the disposable, workspace-isolated local projection/cache.
• Desktop Renderer reacts via local SQLite IPC projections and React Query cache invalidation without requiring full application reloads.

---

Included Changes

Phase 1 — Safe Optional Email Tracking

• Opt-In by Default: Tracking is strictly opt-in at the campaign level (trackingEnabled = false by default).
• Sanitization & Elimination: When tracking is disabled, zero open-tracking pixels are injected, links are never rewritten, and original URLs are preserved byte-for-byte.
• Validation Runtime: When tracking is enabled, URLs are strictly rewritten against the validated HTTPS endpoint (https://api.leadforge.kapiljangid.pro). Localhost, RFC 1918 private subnets, link manipulation, and loopback destinations are hard-rejected with zero silent fallback.

Phase 2 — Persistent Scheduler Concurrency Policy

• Persisted Concurrency: Scheduler concurrency configuration is persisted in MongoDB and scoped per-workspace.
• Non-Blocking Policy Resolution: Worker policies are resolved at runtime and cached in-memory without querying MongoDB on every scheduler tick.
• SQLite Non-Authoritative: SQLite serves purely as a read cache; concurrency limits and policy rules are authoritative in MongoDB.

Phase 3 — Discovery / Outreach Scheduler Fairness

• Anti-Starvation Admission Control: Scheduler admission segregates worker pools into distinct resource classes:
  • outreach: campaign, workflow, IMAP poll
  • discovery: scraper maps, crawler, intelligence, enrichment
• Guaranteed slots prevent heavy discovery crawler bursts from starving active email sequences and outreach jobs.

Phase 4 — IPC Contract Repair

• Contract Reconciliation: Reconciled Renderer → Preload → Main IPC boundaries.
• Dead Channel Pruning: Removed obsolete channels, aligned IpcChannelMap, and eliminated duplicate listeners.
• Verified invocation/event classifications and added automated IPC contract test suites.

Phase 5 — Contact Selection (Explicit IDs)

• ID-Safe Pagination: Replaced fragile index-based selection with explicit contact ID sets (selectedIds).
• Retains selections accurately across pagination, filtering, individual deselections, and bulk actions.

Phase 5B — Select All Matching Contacts

• Mass Query Selection: Enabled workspace/query-wide contact selection without materializing thousands of IDs in renderer memory.
• Managed through a dual-model: explicit IDs (selectedIds[]) or query snapshot (all-matching with excludedIds[] and authoritative query bounds).

Phase 6 — Projection Synchronization / Global Refresh

• Reactive Entity Reconciliation: Automated projection reconciliation for audiences, companies, contacts, campaigns, and discovery_runs.
• Tombstone Integrity: Deleted/archived records write tombstones into SQLite, preventing reconciliation from resurrecting deleted records.
• UI refreshes reactively through React Query invalidations without full-window reloads.

Phase 7 — Safe DiscoveryRun Deletion (Baseline)

• Preserved canonical CRM entities by default while removing run provenance and execution artifacts cleanly.

Phase 8 — Safe Company Deletion Semantics

• Deterministic Deletion Policy: Formalized company deletion modes (company-only vs company-and-eligible-contacts).
• Prevents deletion of contacts with active sequence executions or logged email deliveries to maintain CAN-SPAM audit trails.

Phase 9 — IMAP Polling Efficiency

• Bounded Range Polling: Replaced full mailbox materialization with bounded UID/sequence ranges (startSeq:*) based on configured lookback windows.
• Preserves correlation with outbound Message-IDs without mailbox memory bloat.

Phase 10 — Email Threading / Message Semantics

• RFC-Compliant Header Separation: Preserved distinct separation between RFC Message-ID, provider message ID, and provider thread ID.
• Follow-ups inject valid Message-ID, In-Reply-To, and References headers when predecessor metadata exists, refusing to fabricate threading headers for legacy records lacking RFC identifiers.
• Sanitizes and rejects header-injection payloads.

Phase 11 — Geography Selector

• Hierarchical Selector: Replaced the native <datalist> with a responsive, searchable hierarchical selector (Country → State/Region → City).
• Offline-first, keyboard accessible (Arrow keys, Enter, Escape modal isolation), and bounded scroll safe.

Phase 12 — Email Logs Filter UX

• Responsive Narrow-Pane Layout: Filter groups wrap cleanly within 320–380px panes without horizontal clipping.
• Added active filter count badges, semantic role="group" accessibility, and explicit "Reset Filters" action.

Fix A — DiscoveryRun Cascade Deletion

• Exclusive Entity Cleanup: Deleting a DiscoveryRun automatically deletes companies and contacts that were discovered/created exclusively by that run.
• Pre-Unlinking Provenance Evaluation: Candidate companies are evaluated before deleting provenance links in CompanyDiscoveryRunModel.
• Protection Invariants:
  • Multi-run companies are preserved (unlink junction only).
  • Pre-existing companies (company.createdAt < run.createdAt) are preserved.
  • Companies/contacts with sequence executions, email deliveries, or static audience memberships are preserved.
  • Active/queued crawler jobs for the run are cancelled.
• SQLite Convergence: Soft-deletes run and cascaded companies/contacts in SQLite, broadcasting updates immediately to the renderer.

Fix B — Workspace Switching & Creation Rehydration

• Synchronous Runtime Rehydration: WorkspaceRuntime.start() awaits CacheHydrator.hydrateWorkspaceCache() before signaling readiness, ensuring SQLite is populated before React Query invalidations fire.
• Workspace Creation Parity: Creating a new workspace immediately invokes the canonical switchWorkspace flow.
• Rapid Switching & Superceded Abort: CacheHydrator verifies target workspace before each table batch, immediately aborting stale hydrations if the user switches workspaces rapidly (A -> B -> C).
• Broadcast Scoping: sync:completed events carry { scope: 'all', workspaceId, timestamp } and renderer filters out events targeted at inactive workspaces.

Prior Production Hardening

• Outbound Rejection Circuit Breaker: Auto-pauses campaigns tripping consecutive or windowed provider rejections (PR feat(campaigns): add outbound rejection circuit breaker (#35) #41).
• Domain Pacing & Company Limits: Limits concurrent deliveries per target company and domain (PR feat(outreach): enforce domain pacing and company contact limits (#36) #42).
• Ambiguous Delivery Protection: Prevents blind re-dispatch on timeout/ambiguous provider socket drop (PR fix(email): prevent ambiguous delivery blind re-dispatch (#37) #43).
• Company DNC & Domain Suppression Cascade: Instant cascade cancellation for queued sequence executions on DNC/domain suppression (PR fix(outreach): enforce company dnc and domain suppression cascade (#38) #44).
• DSN Failure Classification: Preserves RFC bounce status codes during provider reconciliation (PR fix(email): preserve DSN failure classification during reconciliation #40).

---

Release-Critical Fixes

1. Decoupled Mailbox Dispatch from Wall Clock: Added referenceTime: Date = new Date() parameter to isMailboxEligibleForDispatch() in @leadforge/schema, resolving non-deterministic test failures when running against historical or simulated timestamps.
2. Root Vitest Configuration Desktop Alias: Added '@': path.resolve(__dirname, 'apps/desktop/src') to root vitest.config.ts, enabling test suites importing desktop UI primitives to execute seamlessly from repository root.
3. ExactOptionalPropertyTypes Compliance: Fixed deleteRun return object in apps/api/src/services/discovery-run/discovery-run.service.ts to conditionally omit undefined keys, guaranteeing strict TypeScript typecheck compliance.

---

Architecture / Safety Notes

• Transactional Boundaries: All authoritative state updates commit to MongoDB first; SQLite acts purely as a local read cache.
• Tombstone Integrity: Soft deletion via LocalCRMRepository.softDeleteFromServer guarantees local cache writes do not revive records removed on the authoritative server.
• CAN-SPAM & Outreach Preservation: Outreach delivery logs (EmailDeliveryModel) and sequence executions (SequenceExecutionModel) are never deleted during run or company cascade cleanup.
• Strict Exclusions: This release explicitly excludes Deliverability Control Plane, SPF/DKIM/DMARC dashboards, custom tracking domains, and spam/inbox placement scoring.

---

Testing

Automated Test Matrix

• Full Monorepo Test Suite: 79 test files passed, 801 tests passed, 0 failures (npx vitest run).
• Native Electron SQLite Integration Test Suite: 17 test files passed, 100% clean (node apps/desktop/scripts/run-tests.js).
• Phase-Specific Regression Suites (269 tests passing):
  • Phase 1 (Tracking Safety): optional-tracking-safety.test.ts, tracking.test.ts
  • Phase 2 (Scheduler Persistence): scheduler-policy-persistence.test.ts, scheduler-policy-loading.test.ts, workspace.test.ts
  • Phase 3 (Scheduler Fairness): scheduler-fairness.test.ts
  • Phase 4 (IPC Contracts): ipc-contract.test.ts
  • Phase 5 & 5B (Contact Selection): contact-selection.test.ts
  • Phase 6 (Projection Sync): projection-sync.test.ts
  • Phase 7 & Fix A (DiscoveryRun Deletion): discovery-run-deletion.test.ts (API & Desktop)
  • Phase 8 (Company Deletion): company-deletion.test.ts
  • Phase 9 (IMAP Polling): imap-poller.test.ts
  • Phase 10 (Email Threading): email-threading.test.ts
  • Phase 11 (Geography Selector): geography-selector.test.ts
  • Phase 12 (Email Logs Filters): email-logs-filters.test.ts
  • Fix B (Workspace Lifecycle): workspace-lifecycle.test.ts
• Static Typecheck: 20/20 packages passed with zero errors (npx turbo run check-types).
• Repository Health: 0 errors across all package configurations (npx tsx scripts/verify-repo-health.ts).

---

Manual Smoke Tests

The following workflows were exercised and validated:

1. Desktop Subsystem Smoke: Initialized SQLite cache schema, local EventBus, log rotation, JobScheduler reconciliation, and telemetry metric validation inside an Electron Node 22 runtime (scripts/smoke-test.ts — PASSED).
2. Workspace Rehydration Lifecycle: Verified switching between populated and empty workspaces updates SQLite projection prior to query invalidations, with superseded background hydrations aborting cleanly on rapid switching.
3. Discovery Cascade Deletion: Verified exclusive companies/contacts are cascade deleted upon discovery run deletion while shared and outreach-linked entities remain intact.
4. Email Tracking Isolation: Verified emails dispatched with trackingEnabled: false contain no open pixels or modified links, while trackingEnabled: true routes exclusively through public HTTPS endpoints.
5. Outreach & Discovery Scheduler Concurrency: Verified concurrent scraper and campaign jobs maintain worker pool fairness without starvation.

---

Known Limitations

• Batch Size on High-Volume Run Deletions: Single discovery runs generating >10,000 exclusive companies evaluate candidates in-memory. For enterprise workloads exceeding 25,000 entities per run, background job batching should be scheduled in a follow-up release.
• Offline Workspace Switching: Switching workspaces without an active network connection relies on cached SQLite projections; background reconciliation sync completes upon connection restoration.

---

Rollback Considerations

• Database Migrations: No destructive MongoDB schema migrations were introduced.
• SQLite Backward Compatibility: SQLite projections remain disposable and can be dropped and regenerated from authoritative MongoDB at any time.
• Safe Reversion: Reverting to the predecessor commit on main requires no database rollback scripts.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
leadforge-os-api	Ready	Preview	Sep 16, 2026 12:33pm UTC
leadforge-os-marketing	Ready	Preview	Sep 16, 2026 12:33pm UTC