coordination-engine/history/260601-AdapterInterfaceSpecification.md

# AdapterInterfaceSpecification.md

## 1. Document Status

**Document:** AdapterInterfaceSpecification.md
**Project:** coordination-engine
**Version:** 1.0
**Status:** Release Candidate
**Scope:** Contract between coordination-engine and external adapters
**Primary Reference Adapter:** email-connect

## 2. Purpose

This document defines the adapter interface contract between `coordination-engine` and external adapter components such as `email-connect`, `rss-connect`, `sms-connect`, `push-connect`, `xmpp-connect`, `portal-connect`, `payment-connect`, `signature-connect`, `document-connect`, `identity-connect`, and future adapters.

The adapter interface allows `coordination-engine` to remain protocol-neutral while integrating with concrete technologies, providers, systems, and communication channels.

Adapters translate between external systems and the internal coordination model by:

1. Declaring capabilities.
2. Accepting action requests.
3. Returning action results.
4. Emitting normalized evidence events.
5. Exposing health and operational state.
6. Preserving correlation between coordination cases and external provider events.

The goal of this specification is to ensure that adapters are independently useful components while still being compatible with `coordination-engine`.

## 3. Core Design Principle

Adapters are not merely transport drivers.

An adapter is a capability component that can perform actions and produce evidence.

```text
Adapter = Capability Descriptor + Action Provider + Signal Provider
```

The coordination engine remains responsible for:

* coordination case lifecycle
* result evaluation
* participant state derivation
* policy decisions
* follow-up decisions
* uncertainty handling
* case-level success/failure/expiry/escalation

The adapter remains responsible for:

* provider-specific integration
* protocol-specific action execution
* native event ingestion
* native-to-normalized event mapping
* adapter-level diagnostics
* provider-level correlation
* adapter health reporting

## 4. Boundary Between coordination-engine and Adapters

### 4.1 coordination-engine Owns

`coordination-engine` owns:

* `CoordinationCase`
* `Participant`
* `IntendedResult`
* case-level state
* participant-level state
* result predicates
* policy evaluation
* next-action selection
* evidence ledger
* adapter selection
* scenario-specific orchestration
* closure, failure, expiry, escalation, and manual override

### 4.2 Adapters Own

Adapters own:

* provider communication
* protocol-specific execution
* provider credentials and configuration
* native event ingestion
* provider-native identifiers
* native status interpretation
* native-to-normalized event mapping
* adapter-specific retries where appropriate
* adapter-specific diagnostics
* adapter health

### 4.3 Shared Contract

The shared contract consists of:

* `AdapterDescriptor`
* `AdapterCapability`
* `AdapterActionRequest`
* `AdapterActionResult`
* `AdapterEvent`
* `EvidenceEvent`
* `AdapterHealth`
* `CorrelationContext`
* `EvidenceGrade`
* `ErrorDescriptor`

## 5. Adapter Types

An adapter may belong to one or more adapter types.

Recommended canonical adapter types:

```text
notification
communication
access
delivery
interaction
identity
authority
payment
signature
document
archive
crm
erp
webhook
feed
system
manual
```

Examples:

| Adapter repo        | Likely adapter types                     |
| ------------------- | ---------------------------------------- |
| `email-connect`     | notification, communication, interaction |
| `rss-connect`       | notification, feed, communication        |
| `sms-connect`       | notification, communication              |
| `push-connect`      | notification, interaction                |
| `portal-connect`    | access, delivery, interaction, identity  |
| `payment-connect`   | payment, interaction, delivery           |
| `signature-connect` | signature, identity, authority, delivery |
| `document-connect`  | document, payload, archive, delivery     |
| `identity-connect`  | identity, authority                      |
| `webhook-connect`   | system, delivery, interaction            |

Adapter type is descriptive, not exclusive.

An adapter may expose capabilities from multiple types if that reflects its real function.

## 6. Normative Language

The following terms are used in this specification:

* **MUST** means required for contract compliance.
* **SHOULD** means recommended unless a documented reason exists.
* **MAY** means optional.
* **MUST NOT** means prohibited for contract compliance.

## 7. Core Interface Objects

## 7.1 AdapterDescriptor

An `AdapterDescriptor` declares the identity, version, capabilities, event support, evidence profile, and operational characteristics of an adapter.

Adapters MUST expose a descriptor.

```yaml
AdapterDescriptor:
  adapter_id: string
  adapter_name: string
  adapter_version: string
  adapter_contract_version: string
  adapter_types:
    - string
  provider_family: string?
  provider_name: string?
  deployment_mode: embedded | sidecar | external | unknown
  supported_actions:
    - AdapterActionCapability
  emitted_event_types:
    - string
  supported_channels:
    - string
  supported_endpoint_types:
    - string
  evidence_profile: AdapterEvidenceProfile
  identity_profile: AdapterIdentityProfile
  latency_profile: AdapterLatencyProfile?
  cost_profile: AdapterCostProfile?
  reliability_profile: AdapterReliabilityProfile?
  configuration_schema_ref: string?
  health_endpoint_ref: string?
  documentation_ref: string?
  limitations:
    - string
```

### Required Fields

The following fields are REQUIRED:

```text
adapter_id
adapter_name
adapter_version
adapter_contract_version
adapter_types
supported_actions
emitted_event_types
supported_channels
supported_endpoint_types
evidence_profile
identity_profile
limitations
```

### Example: email-connect

```yaml
adapter_id: email-connect.default
adapter_name: email-connect
adapter_version: 1.0.0
adapter_contract_version: 1.0
adapter_types:
  - notification
  - communication
  - interaction
provider_family: email
provider_name: configurable
deployment_mode: external
supported_channels:
  - email
supported_endpoint_types:
  - email_address
supported_actions:
  - action_type: notification.send
    mode: async
    idempotency_required: true
  - action_type: notification.send_reminder
    mode: async
    idempotency_required: true
  - action_type: recipient.suppress
    mode: sync
    idempotency_required: true
  - action_type: recipient.unsuppress
    mode: sync
    idempotency_required: true
emitted_event_types:
  - notification.attempt.accepted_by_provider
  - notification.attempt.rejected_by_provider
  - notification.endpoint.accepted
  - notification.endpoint.deferred
  - notification.endpoint.rejected_permanent
  - notification.channel.complaint_received
  - interaction.proxy_or_privacy_interaction
  - interaction.scanner_or_bot_interaction
  - interaction.unverified_actor_interaction
  - interaction.reply_received
evidence_profile:
  strongest_evidence_level: weak_to_medium
  can_prove_human_awareness: false
  can_prove_payload_delivery: false
  can_prove_identity: false
identity_profile:
  identity_strength: none
  authority_strength: none
limitations:
  - Recipient mail server acceptance does not prove inbox delivery.
  - Open tracking is ambiguous and may be caused by privacy proxies.
  - Click tracking may be caused by security scanners.
  - Email events alone usually cannot prove intended-recipient awareness.
```

## 7.2 AdapterActionCapability

An `AdapterActionCapability` declares one action an adapter can perform.

```yaml
AdapterActionCapability:
  action_type: string
  description: string?
  mode: sync | async | scheduled
  idempotency_required: boolean
  required_fields:
    - string
  optional_fields:
    - string
  supported_channels:
    - string
  supported_endpoint_types:
    - string
  expected_initial_events:
    - string
  possible_later_events:
    - string
  known_failure_modes:
    - string
```

### Action Type Naming

Action types SHOULD use dotted semantic names.

Recommended families:

```text
notification.*
access.*
delivery.*
interaction.*
identity.*
authority.*
payment.*
signature.*
document.*
archive.*
feed.*
webhook.*
recipient.*
system.*
```

Examples:

```text
notification.send
notification.send_reminder
access.grant
access.revoke
delivery.publish_payload
delivery.request_submission
payment.create_request
payment.cancel_request
signature.create_envelope
signature.cancel_envelope
feed.publish_item
recipient.suppress
recipient.unsuppress
```

## 7.3 AdapterActionRequest

An `AdapterActionRequest` is a command from `coordination-engine` to an adapter.

Adapters MUST accept action requests in this conceptual shape, even if transport-specific serialization differs.

```yaml
AdapterActionRequest:
  request_id: string
  action_type: string
  coordination_case_id: string
  participant_id: string?
  payload_ref: ResourceRef?
  action_surface_ref: ResourceRef?
  channel: string?
  target_endpoint: EndpointRef?
  actor_context: ActorContext?
  content: ActionContent?
  template_ref: string?
  variables: object?
  tracking_context: TrackingContext
  policy_context: PolicyContext?
  security_context: SecurityContext?
  idempotency_key: string
  requested_at: timestamp
  expires_at: timestamp?
  metadata: object?
```

### Required Fields

The following fields are REQUIRED:

```text
request_id
action_type
coordination_case_id
tracking_context
idempotency_key
requested_at
```

Fields such as `participant_id`, `payload_ref`, `target_endpoint`, or `action_surface_ref` may be optional for system-level or broadcast actions, but adapters MAY require them for specific action types.

### Idempotency

`idempotency_key` MUST be provided for all externally visible actions.

Adapters MUST treat repeated action requests with the same `idempotency_key` as duplicates of the same logical request.

Adapters SHOULD return the original or current action result for duplicate requests.

### Correlation

`tracking_context` MUST contain enough information to correlate later adapter events back to the coordination case.

```yaml
TrackingContext:
  correlation_id: string
  coordination_case_id: string
  participant_id: string?
  notification_id: string?
  delivery_id: string?
  interaction_id: string?
  payload_id: string?
  action_surface_id: string?
  external_context:
    - key: string
      value: string
```

### EndpointRef

```yaml
EndpointRef:
  endpoint_id: string?
  endpoint_type: string
  value: string?
  display_name: string?
  verified: boolean?
  metadata: object?
```

Examples of `endpoint_type`:

```text
email_address
phone_number
push_token
xmpp_jid
rss_feed
webhook_url
portal_account
payment_account
signature_recipient
api_client
physical_address
```

### ActionContent

`ActionContent` represents content or content references.

Adapters SHOULD prefer references over large inline content where possible.

```yaml
ActionContent:
  content_ref: string?
  subject: string?
  body_text: string?
  body_html: string?
  payload_refs:
    - ResourceRef
  action_links:
    - ActionLink
  attachments:
    - ResourceRef
  inline_data: object?
```

### ResourceRef

```yaml
ResourceRef:
  ref_type: string
  ref_id: string
  uri: string?
  version: string?
  integrity_hash: string?
  metadata: object?
```

### ActionLink

```yaml
ActionLink:
  link_id: string
  purpose: string
  url: string
  expires_at: timestamp?
  tokenized: boolean?
  requires_authentication: boolean?
```

## 7.4 AdapterActionResult

An `AdapterActionResult` is the adapter’s response to an action request.

```yaml
AdapterActionResult:
  request_id: string
  adapter_id: string
  accepted: boolean
  action_state: AdapterActionState
  adapter_operation_id: string?
  provider_operation_id: string?
  initial_events:
    - EvidenceEvent
  raw_response_ref: string?
  error: ErrorDescriptor?
  received_at: timestamp
  completed_at: timestamp?
  metadata: object?
```

### AdapterActionState

```text
accepted
rejected
queued
scheduled
in_progress
completed
failed
cancelled
duplicate
unknown
```

### Important Rule

An accepted action result is not proof that the intended result was achieved.

Example:

For email, `accepted: true` means the email adapter accepted the send request. It does not prove that the recipient received, saw, understood, or acted on the notification.

## 7.5 AdapterEvent

An `AdapterEvent` is an incoming event from an adapter before or during evidence normalization.

Adapters MAY expose native-like adapter events, but MUST provide a mapping to `EvidenceEvent`.

```yaml
AdapterEvent:
  event_id: string
  adapter_id: string
  adapter_event_type: string
  native_event_type: string?
  occurred_at: timestamp
  received_at: timestamp
  correlation: CorrelationContext
  participant_id: string?
  payload_ref: ResourceRef?
  action_surface_ref: ResourceRef?
  endpoint_ref: EndpointRef?
  actor_context: ActorContext?
  provider_refs:
    - ProviderRef
  raw_event_ref: string?
  normalization_status: normalized | ignored | failed | pending
  normalized_events:
    - EvidenceEvent
  metadata: object?
```

## 7.6 EvidenceEvent

An `EvidenceEvent` is the normalized event format consumed by the `evidence-ledger`.

Adapters MUST produce or enable production of `EvidenceEvent` records.

```yaml
EvidenceEvent:
  evidence_event_id: string
  event_type: string
  event_family: string
  occurred_at: timestamp
  observed_at: timestamp
  source_adapter_id: string?
  source_adapter_event_id: string?
  coordination_case_id: string
  participant_id: string?
  payload_ref: ResourceRef?
  action_surface_ref: ResourceRef?
  endpoint_ref: EndpointRef?
  actor_context: ActorContext?
  provider_refs:
    - ProviderRef
  normalized_meaning: string
  evidence_grade: EvidenceGrade
  confidence: ConfidenceGrade
  raw_event_ref: string?
  correlation: CorrelationContext
  metadata: object?
```

### Required Fields

The following fields are REQUIRED:

```text
evidence_event_id
event_type
event_family
occurred_at
observed_at
coordination_case_id
normalized_meaning
evidence_grade
confidence
correlation
```

## 8. Canonical Event Families

The following event families are canonical for adapter-generated evidence.

```text
notification
access
delivery
interaction
identity
authority
payload
payment
signature
feed
webhook
system
manual
result
policy
```

Adapters SHOULD map native events into these families.

## 9. Canonical Event Types

This version defines a starter vocabulary. It is not exhaustive.

## 9.1 Notification Events

```text
notification.attempt.created
notification.attempt.accepted_by_adapter
notification.attempt.rejected_by_adapter
notification.attempt.accepted_by_provider
notification.attempt.rejected_by_provider
notification.attempt.queued
notification.attempt.scheduled
notification.attempt.delayed
notification.attempt.cancelled
notification.endpoint.accepted
notification.endpoint.deferred
notification.endpoint.rejected_temporary
notification.endpoint.rejected_permanent
notification.endpoint.unreachable
notification.endpoint.unknown
notification.channel.complaint_received
notification.channel.unsubscribe_received
notification.channel.suppression_added
notification.channel.suppression_removed
notification.channel.reputation_warning
```

## 9.2 Access Events

```text
access.grant.created
access.grant.issued
access.grant.used
access.grant.denied
access.grant.expired
access.grant.revoked
access.grant.delegated
access.grant.suspicious_use_detected
```

## 9.3 Delivery Events

```text
delivery.payload.available
delivery.payload.presented
delivery.payload.viewed
delivery.payload.retrieved
delivery.payload.downloaded
delivery.payload.submitted
delivery.payload.received
delivery.payload.validated
delivery.payload.validation_failed
delivery.payload.accepted
delivery.payload.rejected
delivery.payload.archived
delivery.payload.failed
```

## 9.4 Interaction Events

```text
interaction.surface.opened
interaction.notification.opened
interaction.link.clicked
interaction.proxy_or_privacy_interaction
interaction.scanner_or_bot_interaction
interaction.unverified_actor_interaction
interaction.authenticated_actor_interaction
interaction.authorized_actor_interaction
interaction.reply_received
interaction.out_of_office_received
interaction.acknowledgement_recorded
interaction.decline_recorded
interaction.dispute_opened
```

## 9.5 Identity Events

```text
identity.actor_unknown
identity.actor_suspected
identity.actor_authenticated
identity.actor_mfa_verified
identity.actor_verified_by_provider
identity.actor_mismatch_detected
```

## 9.6 Authority Events

```text
authority.unknown
authority.self_asserted
authority.delegate_authorized
authority.organizational_representative_verified
authority.signer_authorized
authority.payment_authorized
authority.authorization_failed
```

## 9.7 Payment Events

```text
payment.request.created
payment.request.presented
payment.started
payment.failed
payment.cancelled
payment.succeeded
payment.settled
payment.partially_settled
payment.refunded
payment.disputed
payment.promise_to_pay_recorded
```

## 9.8 Signature Events

```text
signature.envelope.created
signature.envelope.sent
signature.document.viewed
signature.signing.started
signature.signing.completed
signature.signing.declined
signature.signing.expired
signature.signing.cancelled
signature.document.finalized
signature.document.archived
```

## 9.9 Feed/Webhook/System Events

```text
feed.item.published
feed.item.updated
feed.item.removed
feed.item.fetched
webhook.request.sent
webhook.response.accepted
webhook.response.rejected
webhook.delivery.failed
system.adapter.health_changed
system.provider.degraded
system.provider.unavailable
```

## 10. EvidenceGrade

An `EvidenceGrade` describes what an event can reasonably support.

Adapters MUST assign an evidence grade to normalized evidence events.

```yaml
EvidenceGrade:
  strength: none | weak | medium | strong | conclusive | negative | ambiguous
  actor_certainty: none | low | medium | high
  authority_certainty: none | low | medium | high
  payload_certainty: none | low | medium | high
  interaction_certainty: none | low | medium | high
  timing_certainty: none | low | medium | high
  channel_certainty: none | low | medium | high
  non_repudiation_strength: none | low | medium | high
  notes:
    - string
```

### Examples

#### Email MX Acceptance

```yaml
strength: weak
actor_certainty: none
authority_certainty: none
payload_certainty: low
interaction_certainty: none
timing_certainty: medium
channel_certainty: medium
non_repudiation_strength: none
notes:
  - Recipient mail server acceptance does not prove inbox placement or human awareness.
```

#### Scanner-Like Email Click

```yaml
strength: ambiguous
actor_certainty: low
authority_certainty: none
payload_certainty: low
interaction_certainty: low
timing_certainty: medium
channel_certainty: medium
non_repudiation_strength: none
notes:
  - Click appears automated and should not be treated as recipient engagement.
```

#### Authenticated Portal Download

```yaml
strength: strong
actor_certainty: high
authority_certainty: medium
payload_certainty: high
interaction_certainty: high
timing_certainty: high
channel_certainty: high
non_repudiation_strength: medium
notes:
  - Authenticated participant retrieved the payload.
```

#### Qualified Signature

```yaml
strength: conclusive
actor_certainty: high
authority_certainty: high
payload_certainty: high
interaction_certainty: high
timing_certainty: high
channel_certainty: high
non_repudiation_strength: high
notes:
  - Signature provider reports completed signing with verified signer identity and document integrity.
```

## 11. ConfidenceGrade

`ConfidenceGrade` expresses how confident the adapter is in the normalized interpretation.

```yaml
ConfidenceGrade:
  level: low | medium | high
  basis:
    - string
```

Example:

```yaml
level: medium
basis:
  - Provider event type is known.
  - Native event contains provider message ID.
  - Event was correlated to known action request.
```

## 12. ActorContext

`ActorContext` describes the actor associated with an event, if known.

```yaml
ActorContext:
  actor_ref: string?
  actor_type: human | organization | system | agent | bot | unknown
  identity_strength: none | low | medium | high
  authority_strength: none | low | medium | high
  authenticated: boolean?
  delegated: boolean?
  provider_identity_ref: string?
  metadata: object?
```

Adapters SHOULD avoid overclaiming identity.

For example, `email-connect` SHOULD NOT mark a click as `authenticated` unless it is backed by a trusted identity or portal event.

## 13. CorrelationContext

Correlation is mandatory for useful adapter integration.

```yaml
CorrelationContext:
  correlation_id: string
  request_id: string?
  coordination_case_id: string
  participant_id: string?
  notification_id: string?
  delivery_id: string?
  interaction_id: string?
  payload_id: string?
  action_surface_id: string?
  adapter_operation_id: string?
  provider_operation_id: string?
  provider_message_id: string?
  external_refs:
    - ProviderRef
```

Adapters MUST preserve correlation identifiers where technically possible.

Adapters SHOULD include correlation identifiers in outbound provider metadata, message headers, webhook metadata, URLs, tokens, or provider custom arguments when supported.

## 14. ProviderRef

```yaml
ProviderRef:
  provider_name: string
  ref_type: string
  ref_value: string
```

Examples:

```yaml
provider_name: sendgrid
ref_type: message_id
ref_value: abc123
```

```yaml
provider_name: stripe
ref_type: payment_intent_id
ref_value: pi_123
```

## 15. ErrorDescriptor

```yaml
ErrorDescriptor:
  code: string
  message: string
  retryable: boolean
  category: validation | authentication | authorization | configuration | provider | network | rate_limit | timeout | conflict | unknown
  native_error_code: string?
  native_error_message: string?
  details: object?
```

Adapters MUST return an `ErrorDescriptor` when an action request is rejected or fails before acceptance.

## 16. Adapter Health

Adapters MUST expose health state.

```yaml
AdapterHealth:
  adapter_id: string
  status: healthy | degraded | unavailable | misconfigured | unknown
  checked_at: timestamp
  provider_connectivity: healthy | degraded | unavailable | unknown
  configuration_validity: valid | invalid | partial | unknown
  credential_status: valid | expired | missing | insufficient | unknown
  last_action_success_at: timestamp?
  last_event_received_at: timestamp?
  known_degradations:
    - string
  metrics:
    actions_accepted_last_24h: integer?
    actions_failed_last_24h: integer?
    events_received_last_24h: integer?
    average_action_latency_ms: integer?
```

## 17. Transport Patterns

This specification does not mandate one technical transport.

Adapters MAY integrate through:

```text
REST API
event bus
message queue
webhook
gRPC
embedded library
CLI
file drop
polling
```

However, any transport MUST preserve the semantic contract defined here.

## 18. Adapter Integration Modes

## 18.1 Embedded Mode

Adapter code runs in the same process as `coordination-engine`.

Suitable for:

* local development
* test adapters
* simulated adapters
* simple deployments

## 18.2 Sidecar Mode

Adapter runs next to the engine but is deployed separately.

Suitable for:

* credential isolation
* provider-specific webhook handling
* protocol-specific runtime dependencies

## 18.3 External Service Mode

Adapter is an independently deployed service.

Suitable for:

* reusable `*-connect` components
* multi-tenant installations
* independent scaling
* provider abstraction
* operational separation

Preferred direction for production adapters:

```text
*-connect repositories SHOULD implement external service mode first,
while optionally also offering embedded or sidecar modes.
```

## 19. Adapter Lifecycle

Adapters SHOULD support the following lifecycle:

```text
registered
configured
healthy
degraded
disabled
retired
```

### 19.1 Registration

During registration, the adapter provides its `AdapterDescriptor`.

### 19.2 Configuration

Configuration may include credentials, provider selection, endpoint settings, webhook secrets, templates, routing policies, or tenant-specific settings.

### 19.3 Health Monitoring

The engine or platform periodically checks `AdapterHealth`.

### 19.4 Action Dispatch

The engine dispatches `AdapterActionRequest` objects to the adapter.

### 19.5 Event Ingestion

The adapter emits `AdapterEvent` or `EvidenceEvent` objects.

### 19.6 Degradation Handling

If an adapter is degraded, the policy engine may switch channel, delay actions, retry later, or escalate.

## 20. Event Ordering, Idempotency, and Late Events

### 20.1 Event Ordering

Adapters MUST NOT assume events arrive in causal order.

The engine MUST be able to process late events.

Adapters SHOULD include accurate `occurred_at` and `observed_at` timestamps.

### 20.2 Duplicate Events

Adapters SHOULD provide stable event identifiers where possible.

The engine MUST deduplicate events using:

```text
evidence_event_id
adapter_event_id
provider event id
correlation context
event type
timestamp
```

### 20.3 Late Events

Late events MUST still be accepted and recorded if they are relevant.

A late hard bounce may change or annotate a previously unresolved participant state.

A late payment settlement may close an otherwise escalated participant state.

### 20.4 Idempotent Actions

All externally visible actions MUST include `idempotency_key`.

Adapters MUST avoid duplicate external side effects for repeated action requests with the same key.

## 21. Security Requirements

Adapters MUST:

* protect provider credentials
* verify incoming provider webhooks where possible
* validate action request authenticity
* avoid leaking sensitive payloads in logs
* support least-privilege configuration
* preserve correlation without exposing unnecessary personal data
* avoid storing raw sensitive data unless explicitly configured

Adapters SHOULD:

* support tenant separation
* support secret rotation
* support signed callbacks or event signatures
* support audit logging of action execution

## 22. Privacy Requirements

Adapters SHOULD minimize personal data.

Adapters SHOULD support:

* endpoint references instead of full endpoint values where possible
* redaction of raw provider events
* retention limits for raw event data
* configurable storage of message content
* metadata-only mode
* data deletion or anonymization workflows where applicable

The adapter interface MUST allow references to external payloads rather than requiring payload content to be copied into the adapter.

## 23. Standalone Adapter Requirements

Adapters are encouraged to be useful outside `coordination-engine`.

A standalone adapter MAY provide:

* provider abstraction
* operational dashboard
* message timeline API
* diagnostic API
* native event archive
* normalized event stream
* suppression management
* provider health checks
* local policy hints

However, standalone features MUST NOT contradict the coordination-engine contract.

For example, `email-connect` may provide a message-level status called `delivered_to_mx`, but it MUST NOT expose that as business-level proof of recipient awareness.

## 24. email-connect Reference Mapping

The following mapping defines expected behavior for the first reference adapter.

| Email-native event                | Normalized event                                                                        | Evidence interpretation                                                 |
| --------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| Message accepted by email adapter | `notification.attempt.accepted_by_adapter`                                              | Weak evidence that adapter accepted request                             |
| Provider accepted message         | `notification.attempt.accepted_by_provider`                                             | Weak evidence that sending began                                        |
| Provider rejected message         | `notification.attempt.rejected_by_provider`                                             | Strong failure for this attempt                                         |
| Recipient MX accepted message     | `notification.endpoint.accepted`                                                        | Weak technical evidence, not awareness                                  |
| Temporary deferral                | `notification.endpoint.deferred`                                                        | Pending/uncertain                                                       |
| Soft bounce                       | `notification.endpoint.rejected_temporary`                                              | Pending or retryable failure                                            |
| Hard bounce                       | `notification.endpoint.rejected_permanent`                                              | Strong endpoint failure                                                 |
| Spam complaint                    | `notification.channel.complaint_received`                                               | Strong negative channel evidence                                        |
| Unsubscribe/suppression           | `notification.channel.unsubscribe_received` or `notification.channel.suppression_added` | Channel not viable or constrained                                       |
| Open via privacy proxy            | `interaction.proxy_or_privacy_interaction`                                              | Ambiguous/weak                                                          |
| Human-like open                   | `interaction.notification.opened`                                                       | Weak-to-medium, not sufficient for high-assurance cases                 |
| Scanner-like click                | `interaction.scanner_or_bot_interaction`                                                | Ambiguous, should not count as recipient action                         |
| Unverified click                  | `interaction.unverified_actor_interaction`                                              | Weak-to-medium, identity uncertain                                      |
| Reply received                    | `interaction.reply_received`                                                            | Medium-to-strong awareness evidence, identity may still need validation |
| Out-of-office reply               | `interaction.out_of_office_received`                                                    | Evidence mailbox exists, not completion                                 |

## 25. RSS Reference Mapping

`rss-connect` should demonstrate pull-based notification semantics.

| RSS-native event       | Normalized event                           | Evidence interpretation                  |
| ---------------------- | ------------------------------------------ | ---------------------------------------- |
| Feed item published    | `feed.item.published`                      | Payload/notice made available            |
| Feed item updated      | `feed.item.updated`                        | Published item changed                   |
| Feed fetched           | `feed.item.fetched`                        | Weak evidence of reader/system retrieval |
| Link clicked from feed | `interaction.unverified_actor_interaction` | Weak-to-medium, identity uncertain       |
| Feed item removed      | `feed.item.removed`                        | Publication revoked or expired           |

RSS publication alone should usually not count as participant awareness unless scenario policy explicitly accepts publication as sufficient.

## 26. Portal Reference Mapping

`portal-connect` is expected to provide stronger access and interaction evidence.

| Portal-native event       | Normalized event                              | Evidence interpretation             |
| ------------------------- | --------------------------------------------- | ----------------------------------- |
| Access grant issued       | `access.grant.issued`                         | Access path created                 |
| Login successful          | `identity.actor_authenticated`                | Stronger actor evidence             |
| Payload page opened       | `interaction.authenticated_actor_interaction` | Actor reached action surface        |
| Document viewed           | `delivery.payload.viewed`                     | Strong payload interaction evidence |
| Document downloaded       | `delivery.payload.downloaded`                 | Strong payload retrieval evidence   |
| Acknowledgement submitted | `interaction.acknowledgement_recorded`        | Strong result-relevant evidence     |
| Access denied             | `access.grant.denied`                         | Failed or blocked access attempt    |
| Access expired            | `access.grant.expired`                        | Access no longer usable             |

## 27. Compatibility Requirements for Adapter Repositories

Every `*-connect` repository SHOULD contain:

```text
INTENT.md
docs/AdapterImplementation.md
docs/EventMapping.md
docs/ProviderModel.md
docs/EvidenceClassification.md
schemas/
src/
tests/
```

Every adapter repository MUST document:

```text
Implemented adapter contract version
Supported actions
Emitted normalized events
Native event mappings
Evidence grading rules
Known limitations
Provider-specific assumptions
Security model
Privacy model
Standalone usage
coordination-engine integration mode
```

## 28. Versioning

### 28.1 Contract Version

Adapters MUST declare `adapter_contract_version`.

This document defines:

```text
adapter_contract_version: 1.0
```

### 28.2 Backward Compatibility

Minor extensions MAY add:

* optional fields
* new event types
* new action types
* new adapter types
* new evidence metadata

Breaking changes include:

* removing required fields
* changing meaning of existing fields
* changing event semantics
* changing idempotency requirements
* changing evidence grade semantics

Breaking changes require a new major version.

## 29. Minimal Compliance Checklist

An adapter is minimally compliant with AdapterInterfaceSpecification 1.0 if it:

1. Exposes an `AdapterDescriptor`.
2. Declares supported actions.
3. Declares emitted event types.
4. Accepts `AdapterActionRequest` objects for supported actions.
5. Returns `AdapterActionResult` objects.
6. Supports idempotency keys.
7. Emits or maps to `EvidenceEvent` objects.
8. Provides `EvidenceGrade` and `ConfidenceGrade`.
9. Preserves `CorrelationContext`.
10. Exposes `AdapterHealth`.
11. Documents known limitations.
12. Does not overclaim result success.
13. Clearly separates provider-native events from normalized evidence.

## 30. Non-Goals

This adapter specification does not define:

* the internal storage model of adapters
* the provider-specific API shape
* the transport protocol used between engine and adapter
* legal validity of evidence
* UI requirements
* billing models
* tenant management model
* full workflow semantics
* complete event vocabulary for every possible domain

Those concerns may be defined in separate documents or scenario-specific specifications.

## 31. Strategic Summary

The adapter interface allows `coordination-engine` to remain a generalized coordination runtime while integrating with many concrete systems.

Adapters perform actions and emit evidence. They translate external provider realities into a normalized coordination vocabulary without deciding overall business success.

The central rule is:

> Adapters report what happened and what it may mean. coordination-engine decides what that means for the coordination case.

This distinction is essential for reliable, extensible, evidence-driven digital coordination.