Postmaster v9.4.1 qualitative provider click classification

[the-code-learner]

Summary

Implements Postmaster v9.4.1 as an additive qualitative interpretation layer on top of the existing v9.4 fingerprint click analytics.

Classification model

• preserves the authoritative unique-click definition: delivery_id + link_id + client_fingerprint
• never deletes, suppresses or rewrites suspicious raw events
• calculates classification at query time; no provider-score columns are added to tracking_clicks
• adds per-link-event:
  • provider_likelihood (0..100)
  • provider_classification: likely_human, uncertain, likely_email_provider, known_email_proxy
  • provider_guess: null / google / microsoft / yahoo / other
  • classification_reasons
• combines timing + fingerprint + country + browser + User-Agent + proxy-source evidence
• explicit GoogleImageProxy/Gmail proxy signatures classify as known proxy / 100
• stable fingerprints observed across multiple links in one delivery reduce provider likelihood
• recipient domains are used only as a provider guess hint, never as proof or a score by themselves

Analytics / MCP

• get_tracking_summary keeps the v9.4 counters and adds a qualitative_estimate
• also exposes likely_provider_unique_clicks, likely_human_or_unclassified_unique_clicks, uncertain_unique_clicks, potential-provider share, provider suspects and classifier model
• get_tracking_campaign inherits the same link summary
• list_tracking_events annotates link rows with the qualitative fields
• tracking_status reports query-time classification support
• build_status.provider_qualitative_classification=true

Dashboard

• adds a qualitative click-estimate summary next to the unchanged fingerprint totals
• adds provider score/classification/guess/reasons to link-event rows
• pixel and AMP rows remain compatible and are not forced through the click classifier

Ground-truth tests

Adds fixtures for:

• Gmail manual IT/Chrome 151 click -> low provider likelihood
• extra US/Chrome 149 request +3.637s later with changed fingerprint -> high provider likelihood
• stable human fingerprint across another link -> low
• Libero-style same fingerprint across links -> low
• explicit GoogleImageProxy -> 100 / known_email_proxy
• single weak timing/fingerprint signal -> uncertain, not provider proof
• query-time integration proving the DB schema contains no provider columns

Version / docs

• bumps VERSION to 9.4.1
• adds the stable changelog entry
• expands docs/LINK_TRACKING.md with the classifier, output contract, ground-truth rationale and exact Cloudflare endpoint requirements

Deployment / Cloudflare

postmaster-mcp.yml is intentionally unchanged.

No new public endpoint is introduced by v9.4.1.

For deployments using all tracking/AMP features, the existing narrow Cloudflare Access bypasses remain:

/track/open/*
/api/amp/*
/t/c/*

Keep /, /mcp, dashboard/private APIs, analytics, mail/task/memory/skill/file-management routes protected.

/files/* remains the separate pre-existing v9.3 signed file-handoff concern; it is not required to be opened for v9.4.1 tracking.

After the stable release is published, POSTMASTER_VERSION=latest + POSTMASTER_CHECK_UPDATES_ON_START=true requires only a stack/container restart. Cloudflare policy remains an external/manual configuration step.