Seeded repo with intent and PRD

INTENT.md

@@ -0,0 +1,540 @@
+# INTENT.md
+
+## Project Name
+
+**email-connect**
+
+## Purpose
+
+`email-connect` is a headless email communication and evidence service.
+
+It provides practical tooling for sending, tracking, querying, diagnosing, and managing email communication while also implementing the adapter contract needed to integrate naturally with `coordination-engine`.
+
+The project treats email as a useful but uncertain communication channel. It can provide evidence that an email was accepted, rejected, bounced, opened, clicked, replied to, complained about, or suppressed, but it must not overclaim what email can prove.
+
+The core principle is:
+
+> Email events are evidence, not result satisfaction. `email-connect` reports email-channel facts and uncertainty. `coordination-engine` evaluates intended results.
+
+## Primary Utility
+
+`email-connect` should be useful in two modes.
+
+### Standalone Mode
+
+As a standalone tool, `email-connect` provides a generic API and UI to use, manage, inspect, and query email communication.
+
+It should help users and systems:
+
+* send transactional and notification emails
+* manage message templates and send requests
+* track message timelines
+* inspect provider events
+* classify bounces
+* manage suppressions
+* inspect recipient endpoint quality
+* diagnose delivery uncertainty
+* classify opens and clicks conservatively
+* handle complaints, unsubscribes, replies, and out-of-office messages
+* query message history and evidence
+* expose email-channel health and diagnostics
+
+The standalone product should be practically useful even without `coordination-engine`.
+
+### coordination-engine Adapter Mode
+
+As an adapter, `email-connect` implements `AdapterInterfaceSpecification.md` and emits normalized evidence events for `coordination-engine`.
+
+It should provide:
+
+* adapter descriptor
+* capability profile
+* evidence ceiling
+* native status mappings
+* action execution for email notifications
+* normalized evidence events
+* endpoint quality signals
+* advisory email evidence assessments
+* late-event handling
+* adapter health reporting
+* golden tests for overclaim prevention
+
+## Strategic Role
+
+`email-connect` is the first reference adapter for the broader coordination framework.
+
+It should prove that adapters can be independently useful tools while still fitting cleanly into `coordination-engine`.
+
+Strategically, `email-connect` should become:
+
+```text
+practical email communication tooling
++ provider-neutral email abstraction
++ evidence-normalization service
++ coordination-engine reference adapter
+```
+
+It should not become a full marketing automation platform or newsletter campaign manager. The focus is transactional, operational, coordination-related email communication and evidence handling.
+
+## Core Principle
+
+Email is a weak-to-medium evidence channel for awareness.
+
+`email-connect` must distinguish:
+
+```text
+provider acceptance
+recipient mail-server acceptance
+temporary deferral
+hard bounce
+soft bounce
+async bounce
+provider drop
+suppression
+complaint
+unsubscribe
+open tracking
+proxy/privacy open
+scanner click
+unverified click
+human-like reply
+out-of-office response
+```
+
+It must avoid treating technical email delivery as human awareness.
+
+Important distinctions:
+
+```text
+provider accepted ≠ recipient server accepted
+recipient server accepted ≠ inbox placement
+inbox placement ≠ human awareness
+open event ≠ human reading
+click event ≠ authenticated recipient action
+email reply ≠ legally valid acceptance
+```
+
+## Intended Users
+
+The project is intended for:
+
+* developers integrating email into applications
+* operators monitoring transactional email flows
+* product teams building coordination-heavy applications
+* support teams diagnosing email delivery problems
+* automation agents sending and inspecting email communication
+* `coordination-engine` as a consuming orchestration runtime
+* future UI users who need to query and manage email communication
+
+## Primary Use Cases
+
+### Send Email Notifications
+
+Accept send requests through a generic API and dispatch them through one or more email providers.
+
+### Track Message Timelines
+
+Maintain a timeline of all known events for an email message:
+
+```text
+created
+rendered
+accepted by adapter
+accepted by provider
+queued
+recipient MX accepted
+deferred
+bounced
+opened
+clicked
+replied
+complained
+suppressed
+```
+
+### Diagnose Delivery Uncertainty
+
+Expose useful diagnostics without pretending that email proves delivery or awareness.
+
+Examples:
+
+```text
+recipient MX accepted but no engagement
+privacy-proxy open only
+scanner-like click detected
+hard bounce received
+async bounce arrived late
+recipient reported missing email
+```
+
+### Normalize Provider Events
+
+Translate provider-specific events into email-native events and then into coordination-compatible `EvidenceEvent` records.
+
+### Manage Suppressions
+
+Track suppression states caused by:
+
+```text
+hard bounce
+spam complaint
+unsubscribe
+manual suppression
+provider policy suppression
+```
+
+### Manage Endpoint Quality
+
+Track email endpoint quality signals:
+
+```text
+syntax validity
+domain/MX quality
+hard-bounce history
+complaint history
+engagement history
+suppression state
+catch-all suspicion
+role/shared address suspicion
+```
+
+### Provide Coordination Evidence
+
+Emit normalized events for `coordination-engine`, such as:
+
+```text
+notification.attempt.accepted_by_provider
+notification.endpoint.accepted
+notification.endpoint.rejected_permanent
+notification.endpoint.deferred
+interaction.proxy_or_privacy_interaction
+interaction.scanner_or_bot_interaction
+interaction.unverified_actor_interaction
+interaction.reply_received
+notification.channel.complaint_received
+notification.channel.suppression_added
+```
+
+### Provide Generic UI
+
+Provide or enable a generic UI for:
+
+* viewing sent messages
+* searching communication history
+* inspecting message timelines
+* viewing provider status
+* reviewing bounces and complaints
+* managing suppressions
+* inspecting endpoint quality
+* diagnosing uncertain delivery
+* querying evidence events
+* checking adapter health
+
+## Scope
+
+`email-connect` should include:
+
+* provider-neutral email send API
+* message and attempt records
+* provider abstraction layer
+* provider event ingestion
+* native event preservation
+* native-to-normalized status mapping
+* bounce classification
+* suppression management
+* open/click event classification
+* scanner/proxy detection heuristics
+* reply and out-of-office handling
+* endpoint quality model
+* message timeline API
+* message assessment API
+* adapter descriptor and health endpoints
+* coordination-engine-compatible evidence event output
+* basic UI for operational inspection and management
+
+## Non-Goals
+
+`email-connect` is not primarily:
+
+* a newsletter platform
+* a marketing automation suite
+* a CRM
+* a full workflow engine
+* a legal notice system
+* a document portal
+* a payment system
+* a signature system
+* the owner of coordination case success
+
+It may integrate with such systems, but its core responsibility is email communication and email-channel evidence.
+
+## Architecture Direction
+
+The project should be organized around these internal components:
+
+```text
+email-connect
+  email-api
+  email-ui
+  provider-abstraction
+  message-store
+  event-ingestion
+  native-status-mapping
+  evidence-normalizer
+  evidence-assessment
+  endpoint-quality
+  suppression-manager
+  template-manager
+  tracking-manager
+  adapter-contract
+  provider-health
+```
+
+## Provider Abstraction
+
+`email-connect` should support multiple email providers through provider modules.
+
+Provider modules should handle:
+
+* sending
+* provider message IDs
+* provider webhooks
+* provider event verification
+* bounce event parsing
+* complaint handling
+* suppression handling
+* provider-specific statuses
+* provider health
+
+The internal model should not be hardcoded to one provider.
+
+Provider event mapping should follow:
+
+```text
+provider-native event
+→ email-native event
+→ EmailEvidenceAssessment
+→ coordination EvidenceEvent
+```
+
+## Evidence and Uncertainty Model
+
+`email-connect` should provide an email-native assessment.
+
+```text
+category:
+  success
+  fail
+  undef
+```
+
+The `undef` category is normal and important.
+
+Common `undef` subclasses:
+
+```text
+undef.pending
+undef.provider_accepted_only
+undef.queued
+undef.deferred
+undef.endpoint_accepted_only
+undef.no_signal
+undef.weak_positive
+undef.proxy_open
+undef.scanner_click
+undef.unverified_click
+undef.identity_uncertain
+undef.possibly_spam_or_quarantine
+undef.possibly_silent_drop
+undef.forwarding_unknown
+undef.catch_all_domain
+undef.conflicting_evidence
+undef.channel_degraded
+undef.recipient_reported_missing
+undef.out_of_office
+```
+
+Email evidence must be classified conservatively.
+
+## Evidence Ceiling
+
+`email-connect` should declare the following evidence ceiling by default:
+
+```yaml
+max_positive_event: interaction.unverified_actor_interaction
+max_positive_strength: medium
+can_prove_human_awareness: false
+can_prove_payload_access: false
+can_prove_payload_delivery: false
+can_prove_identity: false
+can_prove_authority: false
+can_prove_non_repudiation: false
+```
+
+Stronger evidence should come from other systems, such as:
+
+* portal login
+* authenticated document download
+* payment settlement
+* signature completion
+* explicit verified acknowledgement
+
+## coordination-engine Compatibility
+
+`email-connect` should implement `AdapterInterfaceSpecification.md`.
+
+It should provide:
+
+```text
+AdapterDescriptor
+AdapterCapabilityProfile
+AdapterActionCapability
+AdapterActionRequest handling
+AdapterActionResult
+AdapterEvent
+EvidenceEvent
+AdapterEvidenceAssessment
+EvidenceGrade
+EvidenceCeiling
+NativeStatusMapping
+EndpointQuality
+AdapterHealth
+CorrelationContext
+LateEventPolicy
+FeatureDependency
+GoldenTests
+```
+
+The adapter should support at least:
+
+```text
+notification.send
+notification.send_reminder
+notification.register_tracking_context
+recipient.suppress
+recipient.unsuppress
+```
+
+## Generic API Direction
+
+The generic API should support:
+
+```text
+POST /email/send
+GET /email/messages
+GET /email/messages/{id}
+GET /email/messages/{id}/timeline
+GET /email/messages/{id}/assessment
+GET /email/endpoints/{id}/quality
+POST /email/suppressions
+DELETE /email/suppressions/{id}
+GET /email/channel-health
+```
+
+Adapter-compatible API concepts should include:
+
+```text
+GET /adapter/descriptor
+GET /adapter/health
+POST /adapter/actions
+POST /adapter/events/provider
+GET /adapter/events
+```
+
+The exact API shape may evolve, but these conceptual operations should remain stable.
+
+## Generic UI Direction
+
+The UI should initially be simple and operational.
+
+Core views:
+
+```text
+Message list
+Message detail
+Message timeline
+Evidence assessment
+Endpoint quality
+Suppression list
+Provider health
+Event search
+Bounce/complaint diagnostics
+Adapter compatibility
+```
+
+The UI should help humans and agents answer questions such as:
+
+```text
+What happened to this email?
+Was it rejected, bounced, accepted, opened, clicked, or replied to?
+Is the recipient endpoint healthy?
+Is the channel suppressed?
+Is this a real engagement signal or likely proxy/scanner activity?
+What evidence can this email provide?
+What can it not prove?
+```
+
+## MVP Focus
+
+The first implementation should prove the useful standalone value and the coordination adapter value.
+
+Recommended MVP:
+
+1. Accept send requests.
+2. Store email message records.
+3. Dispatch through simulated provider or one real provider.
+4. Preserve idempotency.
+5. Ingest provider events.
+6. Normalize provider events.
+7. Generate email evidence assessments.
+8. Emit coordination-compatible evidence events.
+9. Provide message timeline API.
+10. Provide endpoint quality basics.
+11. Provide suppression basics.
+12. Provide adapter descriptor and health.
+13. Provide minimal UI for inspecting messages and timelines.
+
+## MVP Acceptance Criteria
+
+The MVP is useful when it can:
+
+* send or simulate email sending
+* record a message timeline
+* ingest provider events
+* classify provider acceptance as weak evidence
+* classify MX acceptance as weak technical evidence
+* classify hard bounce as strong failure evidence
+* classify proxy opens and scanner clicks as ambiguous
+* preserve raw event references
+* avoid overclaiming awareness
+* expose a useful API
+* expose a basic inspection UI
+* integrate with `coordination-engine` as an adapter
+
+## Design Priorities
+
+1. **Practical usefulness**
+   The system should be useful for real email communication management, not only adapter testing.
+
+2. **Provider neutrality**
+   Avoid binding the core model to one provider.
+
+3. **Evidence correctness**
+   Never overclaim what email proves.
+
+4. **Operational visibility**
+   Make message timelines, bounces, complaints, and suppressions easy to inspect.
+
+5. **Coordination compatibility**
+   Fit naturally into `coordination-engine` through the adapter contract.
+
+6. **Agent friendliness**
+   Provide clear schemas, mappings, APIs, and golden tests.
+
+7. **Security and privacy**
+   Protect credentials, message content, endpoint data, tracking links, and raw provider events.
+
+## Guiding Statement
+
+`email-connect` is a practical email communication and evidence service. It sends and tracks email, normalizes provider events, exposes useful operational APIs and UI, and integrates with `coordination-engine` by reporting conservative email-channel evidence under uncertainty.
+