coordination-engine/spec/RuntimeArchitectureAndAdapterSubsystem.md

# RuntimeArchitectureAndAdapterSubsystem.md

## 1. Document Status

**Document:** RuntimeArchitectureAndAdapterSubsystem.md
**Project:** coordination-engine
**Version:** 1.1
**Status:** Updated Draft
**Scope:** Runtime architecture and adapter subsystem
**Related Documents:**

* `INTENT.md`
* `ProductRequirementsDocument.md`
* `AdapterInterfaceSpecification.md`
* `EmailAdapterSpecification.md`
* `SmsAdapterSpecification.md`
* `RssAdapterSpecification.md`
* `XmppAdapterSpecification.md`
* `HybridmailAdapterSpecification.md`

## 2. Version 1.1 Change Summary

This version incorporates architectural learnings from concrete adapter specifications for email, SMS, RSS, XMPP, and hybrid mail.

Main updates:

1. Adapters are now modeled as semantic evidence components, not simple integration endpoints.
2. Added adapter capability resolution.
3. Added evidence ceiling evaluation.
4. Added native status mapping as an architectural concern.
5. Added endpoint quality as first-class runtime information.
6. Added late-event processing.
7. Added adapter advisory assessments.
8. Added conformance and golden-test harness concepts.
9. Strengthened weakest-safe-mapping and semantic-underclaiming rules.
10. Clarified that result interpretation requires evidence, adapter semantics, and scenario policy.

## 3. Purpose

`coordination-engine` is a headless runtime for digital coordination. It coordinates participants around payloads and action surfaces through notifications, deliveries, access control, interactions, evidence, and policies to achieve intended results under uncertainty.

This document specifies the runtime architecture and adapter subsystem.

The adapter subsystem allows `coordination-engine` to integrate with external protocols, providers, and systems without hardcoding provider-specific semantics into the core engine.

Examples of adapters:

```text id="pi0m7p"
email-connect
sms-connect
rss-connect
xmpp-connect
hybridmail-connect
portal-connect
payment-connect
signature-connect
document-connect
identity-connect
webhook-connect
```

## 4. Architectural Intent

The runtime architecture is based on the following principles.

### 4.1 Coordination is result-driven

A coordination case succeeds when its intended result is satisfied, not when messages are merely sent.

### 4.2 Digital coordination is evidence-driven

The engine records observations from multiple systems and derives participant and case states from evidence.

### 4.3 Adapters are semantic boundary components

Adapters do not only execute actions and emit events. They also declare capabilities, preserve native events, map native events conservatively, expose evidence ceilings, and report limitations.

### 4.4 External systems remain external

The engine should orchestrate and evaluate coordination, not replace email providers, SMS providers, feed servers, XMPP servers, hybrid-mail providers, portals, payment systems, signature systems, document stores, or identity systems.

### 4.5 Uncertainty is first-class

Many signals are ambiguous. The architecture must represent weak, conflicting, late, missing, or uncertain evidence.

### 4.6 Underclaiming is mandatory

If a native provider event is ambiguous, the adapter and runtime must prefer the weakest safe interpretation.

### 4.7 Scenario-specific applications compose selectively

Simple use cases should not require payment, signature, portal, or hybrid-mail semantics. Complex use cases should be able to add stronger identity, authority, payload, access, and evidence requirements.

## 5. Core Runtime Overview

`coordination-engine` is composed of a central coordination controller, specialized domain controllers, an evidence ledger, a policy engine, and an adapter semantics boundary.

```text id="372jsk"
coordination-engine
  coordination-controller
  result-controller
  participant-controller
  payload-controller
  access-controller
  notification-controller
  delivery-controller
  interaction-controller
  identity-authority-controller
  evidence-ledger
  policy-engine
  adapter-semantics-boundary
```

The main runtime object is the `CoordinationCase`.

External systems connect through adapters. Adapters provide actions, emit events, declare capabilities, and constrain interpretation through evidence ceilings and native status mappings.

## 6. High-Level Runtime Flow

### 6.1 Action Flow

```text id="19qc4b"
Policy requests action
→ Capability Resolver selects suitable adapter
→ Adapter Registry checks health and capability
→ Coordination Controller creates AdapterActionRequest
→ Adapter Action Dispatcher sends request
→ Adapter executes action
→ AdapterActionResult is recorded
→ Initial EvidenceEvents are stored
→ Later AdapterEvents are ingested asynchronously
```

### 6.2 Event Flow

```text id="mzs6c8"
Adapter native event
→ Native Status Mapping
→ Normalized EvidenceEvent
→ Evidence Ledger
→ Evidence Ceiling Evaluation
→ Endpoint Quality Update
→ Adapter Assessment Update
→ Policy Evaluation
→ Participant Assessment
→ Case Assessment
→ Next Action Generation
```

### 6.3 Interpretation Flow

The engine MUST interpret evidence using the following inputs:

```text id="1l9qcr"
EvidenceEvent
+ AdapterCapabilityProfile
+ EvidenceCeiling
+ NativeStatusMapping
+ EvidenceGrade
+ ConfidenceGrade
+ EndpointQuality
+ LateEventPolicy
+ FeatureDependencies
+ Scenario Policy
+ IntendedResult
```

The engine MUST NOT infer stronger participant or case state than the evidence ceiling of the originating adapter allows, unless additional evidence from another adapter raises the assurance level.

## 7. Core Runtime Model

## 7.1 CoordinationCase

A `CoordinationCase` is the primary aggregate.

It represents one goal-directed coordination process.

Example cases:

```text id="ub0h4c"
deliver documents to recipients
collect missing documents
obtain AGB acceptance
close contracts
collect payments
gather acknowledgements
coordinate approvals
send hybrid-mail fallback letters
```

Minimal structure:

```yaml id="ji6fzy"
CoordinationCase:
  id: string
  initiator: ActorRef
  purpose: string
  scenario_type: string
  intended_result: IntendedResult
  participants:
    - ParticipantRef
  payloads:
    - PayloadRef
  action_surfaces:
    - ActionSurfaceRef
  policies:
    - PolicyRef
  state: CoordinationCaseState
  assessment: CoordinationAssessment
  created_at: timestamp
  updated_at: timestamp
```

## 7.2 Participant

A `Participant` is an actor involved in a coordination case.

Participants may be humans, organizations, systems, agents, delegates, signers, payers, approvers, respondents, recipients, or intermediaries.

```yaml id="t2gg15"
Participant:
  id: string
  actor_ref: ActorRef
  roles:
    - string
  contact_endpoints:
    - EndpointRef
  authority_profile_ref: string?
  required_outcomes:
    - RequiredOutcome
  state: ParticipantState
```

## 7.3 IntendedResult

An `IntendedResult` defines what the initiator wants to achieve.

```yaml id="zmxcoo"
IntendedResult:
  id: string
  result_type: string
  target_population: ParticipantSelector
  required_outcome: string
  required_evidence_level: EvidenceLevel
  assurance_requirements: AssuranceRequirement?
  threshold: Threshold?
  deadline: timestamp?
  partial_success_rules:
    - RuleRef
  failure_rules:
    - RuleRef
```

Example:

```yaml id="671wqx"
result_type: payload_access
required_outcome: pdf_downloaded
threshold:
  type: percentage
  value: 95
deadline: 2026-12-31T23:59:59Z
```

## 7.4 AssuranceRequirement

A scenario may define required assurance levels.

```yaml id="kcnj5r"
AssuranceRequirement:
  awareness_assurance: none | weak | medium | strong | conclusive
  delivery_assurance: none | weak | medium | strong | conclusive
  identity_assurance: none | weak | medium | strong | conclusive
  authority_assurance: none | weak | medium | strong | conclusive
  non_repudiation_assurance: none | weak | medium | strong | conclusive
```

The Policy Engine uses this to select adapters and interpret evidence.

## 7.5 Payload

A `Payload` is a meaningful resource involved in the case.

Payloads are not limited to documents. They can include invoices, payment requests, contract drafts, signed contracts, submitted forms, data packages, receipts, terms versions, or structured messages.

```yaml id="y8zwcf"
Payload:
  id: string
  semantic_role: string
  payload_type: string
  version: string?
  representation_refs:
    - RepresentationRef
  integrity_hash: string?
  sensitivity: string?
  retention_policy_ref: string?
  validation_policy_ref: string?
```

## 7.6 ActionSurface

An `ActionSurface` is the place where a participant can interact with a payload or perform a required action.

Examples:

```text id="ekgabs"
portal page
mobile app screen
payment page
signature flow
upload form
approval screen
chatbot flow
API endpoint
email reply parser
XMPP bot
feed item
physical letter
```

```yaml id="dxrso5"
ActionSurface:
  id: string
  type: string
  adapter_ref: string?
  url: string?
  endpoint_ref: string?
  supported_interactions:
    - string
  access_policy_ref: string?
  requires_authentication: boolean?
```

## 7.7 EvidenceEvent

An `EvidenceEvent` is a normalized observation used by the engine to derive state.

```yaml id="dnggme"
EvidenceEvent:
  id: string
  event_type: string
  event_family: string
  source_adapter: string?
  source_adapter_event_id: string?
  native_status_mapping_ref: string?
  coordination_case_id: string
  participant_id: string?
  payload_ref: ResourceRef?
  action_surface_ref: ActionSurfaceRef?
  endpoint_ref: EndpointRef?
  actor_ref: ActorRef?
  occurred_at: timestamp?
  observed_at: timestamp
  normalized_meaning: string
  confidence: ConfidenceGrade
  evidence_grade: EvidenceGrade
  raw_event_ref: string?
  correlation: CorrelationContext
  metadata: object?
```

Evidence events are the basis for assessment, policy evaluation, auditability, and explainability.

## 8. Runtime Components

## 8.1 Coordination Controller

The `coordination-controller` is the central runtime component.

Responsibilities:

* Create and manage `CoordinationCase` objects.
* Coordinate specialized controllers.
* Maintain case lifecycle state.
* Request policy evaluations.
* Apply derived state transitions.
* Trigger adapter actions through the adapter subsystem.
* Close, fail, expire, pause, or escalate cases.

The coordination controller does not directly speak to external systems. It uses adapters through the adapter semantics boundary.

## 8.2 Result Controller

The `result-controller` evaluates whether an intended result has been satisfied.

Responsibilities:

* Evaluate case-level success predicates.
* Evaluate participant-level completion.
* Handle thresholds, deadlines, partial success, failure, expiry, and manual override.
* Produce result assessment events.
* Respect scenario assurance requirements.
* Avoid interpreting adapter evidence beyond its evidence ceiling.

Example derived states:

```text id="4yxlwc"
active
partially_completed
completed_successfully
completed_partially
failed
expired
manually_closed
```

## 8.3 Participant Controller

The `participant-controller` manages participant state within a case.

Responsibilities:

* Maintain participant roles and required outcomes.
* Link participants to payloads, action surfaces, endpoints, and evidence.
* Derive participant progress states.
* Support delegates, organizations, systems, and agents.
* Track per-participant unresolved/undef subclasses.

Example participant states:

```text id="tgrdx1"
not_started
notification_pending
notified
awareness_uncertain
access_granted
accessed
interaction_started
required_action_completed
failed
expired
escalated
completed
```

## 8.4 Payload Controller

The `payload-controller` manages payload identity, versioning, representation, integrity, validation, and lifecycle references.

Responsibilities:

* Register payloads.
* Link payloads to participants and intended results.
* Track payload availability.
* Track inbound and outbound payload references.
* Integrate with document stores, archives, or payload providers through adapters.

The payload controller does not need to store the payload itself. It may only store metadata and references.

## 8.5 Access Controller

The `access-controller` manages access to payloads and action surfaces.

Responsibilities:

* Create access grants.
* Revoke access.
* Track access usage, denial, expiry, delegation, and abuse.
* Coordinate with identity and authority systems.
* Emit access-related evidence events.

Example access states:

```text id="c4rhw3"
not_granted
granted
used
denied
expired
revoked
delegated
suspicious
```

## 8.6 Notification Controller

The `notification-controller` manages awareness-oriented signals.

Responsibilities:

* Create notification attempts.
* Select channels according to policy and adapter capability.
* Trigger notification adapters.
* Record notification evidence.
* Distinguish technical delivery from awareness evidence.
* Support reminders, retries, and escalation.

Notification does not equal delivery. A notification may point to an action surface or payload but does not necessarily carry the payload.

## 8.7 Delivery Controller

The `delivery-controller` manages payload availability, retrieval, submission, transfer, consumption, and completion.

Responsibilities:

* Track outbound delivery evidence.
* Track inbound delivery evidence.
* Track payload submission and validation results.
* Interpret delivery-side events as possible evidence for notification or result success.
* Distinguish availability, dispatch, handover, access, download, submission, and completion.

Delivery is generalized as controlled payload access, transfer, retrieval, submission, or consumption.

## 8.8 Interaction Controller

The `interaction-controller` classifies meaningful participant actions.

Responsibilities:

* Record interaction events.
* Distinguish anonymous, suspected, authenticated, delegated, authorized, bot, scanner, and proxy interactions.
* Determine whether interactions are result-relevant.
* Feed interaction evidence into participant and result assessment.

Example interactions:

```text id="8dmkz5"
notification_opened
link_clicked
portal_opened
document_viewed
pdf_downloaded
form_started
form_submitted
payment_started
payment_settled
contract_viewed
signature_completed
acknowledgement_recorded
```

## 8.9 Identity & Authority Controller

The `identity-authority-controller` evaluates actor identity and authority.

Responsibilities:

* Link actors to participants.
* Evaluate authentication strength.
* Evaluate authorization, delegation, and representation.
* Provide evidence grades for identity and authority.
* Integrate with IAM, SSO, MFA, signature providers, or authorization systems.

Example identity grades:

```text id="1cx3ei"
unknown
device_known
session_authenticated
mfa_verified
identity_provider_verified
qualified_identity_verified
```

Example authority grades:

```text id="g09lft"
unknown
self_authorized
delegated
organizational_representative
authorized_signer
payment_authorized
admin_override
```

## 8.10 Evidence Ledger

The `evidence-ledger` stores normalized observations.

Responsibilities:

* Persist evidence events.
* Preserve raw event references.
* Support idempotency and deduplication.
* Maintain correlation across adapters.
* Store native-status mapping references.
* Support late events.
* Support audit reconstruction.
* Support state derivation and explainability.

The evidence ledger should be append-oriented. Derived state may be updated, but original evidence events should remain traceable.

## 8.11 Policy Engine

The `policy-engine` interprets state and evidence to determine next actions.

Responsibilities:

* Evaluate result policies.
* Evaluate follow-up policies.
* Evaluate escalation rules.
* Evaluate retry and timeout rules.
* Compare assurance requirements with adapter assurance capabilities.
* Use evidence ceilings to avoid overclaiming.
* Generate next-action recommendations or commands.
* Explain why actions were generated.

Example next actions:

```text id="zfx76u"
wait
send_notification
send_reminder
retry
switch_channel
escalate
request_correction
revoke_access
extend_deadline
manual_review
close_success
close_failure
expire_case
```

## 9. Adapter Semantics Boundary

The adapter subsystem is a semantic boundary layer.

Its purpose is to protect the coordination engine from overinterpreting external system events.

```text id="rb4hj1"
External provider semantics
→ adapter-native model
→ conservative normalized evidence
→ coordination interpretation
```

Adapters do not only emit events. They also declare the maximum meaning of their events.

The runtime MUST evaluate adapter evidence using:

```text id="r321bb"
normalized event type
evidence grade
confidence grade
native status mapping
evidence ceiling
assurance capability
endpoint quality
feature dependencies
late-event policy
scenario result requirements
```

## 10. Adapter Subsystem Components

The adapter semantics boundary consists of:

```text id="d01xuc"
adapter-registry
capability-resolver
adapter-action-dispatcher
adapter-event-ingestor
native-status-mapping-registry
evidence-normalizer
evidence-ceiling-evaluator
endpoint-quality-store
adapter-assessment-store
adapter-health-monitor
late-event-processor
adapter-conformance-harness
```

## 10.1 Adapter Registry

The Adapter Registry stores adapter descriptors.

Responsibilities:

* Register adapters.
* Store `AdapterDescriptor`.
* Store `AdapterCapabilityProfile`.
* Store `EvidenceCeiling`.
* Store `AssuranceCapability`.
* Store supported actions.
* Store supported event types.
* Store feature dependencies.
* Store conformance level.
* Store known limitations.

The Adapter Registry is used by the Capability Resolver and Policy Engine.

## 10.2 Capability Resolver

The Capability Resolver selects suitable adapters for a desired action or assurance requirement.

Inputs:

```text id="qkht2m"
required action
participant endpoints
payload type
action surface
required assurance
deadline
adapter health
adapter capability
feature dependencies
cost/latency constraints
scenario policy
```

Outputs:

```text id="f9motk"
candidate adapters
candidate actions
suitability ranking
reasoning
known limitations
```

Example:

```text id="rqgqc0"
Need awareness >= medium:
  SMS may be suitable if DLR supported.
  XMPP may be suitable if displayed markers supported.
  Email alone may be insufficient.
```

Example:

```text id="y8qg8k"
Need delivery >= strong:
  Portal authenticated download may be suitable.
  Hybrid mail delivery confirmation may be suitable if product supports it.
  Ordinary hybrid-mail postal handover may be insufficient.
```

## 10.3 Adapter Action Dispatcher

The Adapter Action Dispatcher sends `AdapterActionRequest` objects to adapters.

Responsibilities:

* Build action requests.
* Include correlation context.
* Include idempotency key.
* Validate required fields.
* Dispatch to adapter.
* Capture `AdapterActionResult`.
* Store initial evidence events.
* Handle duplicate and idempotency-conflict responses.
* Handle retryable and non-retryable action errors.

## 10.4 Adapter Event Ingestor

The Adapter Event Ingestor receives `AdapterEvent` or `EvidenceEvent` objects.

Responsibilities:

* Validate event shape.
* Verify adapter identity.
* Verify webhook authenticity where applicable.
* Deduplicate events.
* Preserve raw event references.
* Pass events through evidence normalization.
* Append normalized evidence to Evidence Ledger.

## 10.5 Native Status Mapping Registry

The Native Status Mapping Registry stores provider-native to normalized event mappings.

Responsibilities:

* Store adapter-specific native status mappings.
* Store provider status semantics.
* Store weakest-safe mappings.
* Store confidence and ambiguity flags.
* Store product or feature dependencies.
* Support mapping lookup during event normalization.
* Support coding-agent inspection.

Example:

```text id="qrfzif"
Native email "delivered" → notification.endpoint.accepted
Native SMS "delivered" → notification.endpoint.accepted with delivery semantics
Native hybrid-mail "sent" → delivery.payload.submitted unless handover semantics are proven
```

## 10.6 Evidence Normalizer

The Evidence Normalizer converts adapter-native events into normalized `EvidenceEvent` objects.

Responsibilities:

* Apply native status mappings.
* Apply weakest-safe-mapping rule.
* Assign evidence grade.
* Assign confidence grade.
* Preserve native status.
* Preserve raw event reference.
* Attach correlation context.
* Attach adapter semantics metadata.

The Evidence Normalizer must never strengthen evidence beyond the adapter’s declared mapping.

## 10.7 Evidence Ceiling Evaluator

The Evidence Ceiling Evaluator ensures runtime interpretation does not exceed adapter capability.

Responsibilities:

* Compare evidence event against adapter evidence ceiling.
* Compare event against scenario assurance requirement.
* Determine whether evidence is sufficient, insufficient, or conditional.
* Prevent overclaiming in participant and result state derivation.

Example:

```text id="6enfrt"
Event:
  email notification.endpoint.accepted

Evidence ceiling:
  cannot prove human awareness

Result requirement:
  awareness >= medium

Outcome:
  insufficient; participant remains unresolved
```

Example:

```text id="bp4o8c"
Event:
  portal delivery.payload.downloaded

Evidence ceiling:
  can prove payload access if authenticated

Result requirement:
  delivery >= strong

Outcome:
  sufficient if identity evidence also meets policy
```

## 10.8 Endpoint Quality Store

The Endpoint Quality Store maintains endpoint quality signals emitted or inferred from adapters.

Examples:

```text id="6l6e2i"
email hard bounce history
SMS opt-out state
RSS feed validity
XMPP presence / JID quality
postal address validation / return history
```

Responsibilities:

* Store endpoint quality by endpoint reference.
* Update quality from evidence events.
* Expose quality to policy engine.
* Influence adapter selection.
* Avoid treating endpoint quality as result evidence by itself.

## 10.9 Adapter Assessment Store

Adapters may emit advisory `AdapterEvidenceAssessment` objects.

Responsibilities:

* Store adapter-native assessments.
* Expose assessments for diagnostics.
* Keep them separate from coordination-engine authoritative state.
* Allow policy engine to use them as hints, not final truth.

Rule:

```text id="7z2xe6"
AdapterEvidenceAssessment is advisory.
coordination-engine remains authoritative for participant and case state.
```

Example:

```text id="g0pn77"
sms-connect assessment:
  success.delivered

coordination-engine assessment:
  undef.delivered_but_awareness_unproven
```

Both may be correct at different semantic layers.

## 10.10 Adapter Health Monitor

The Adapter Health Monitor tracks adapter and provider health.

Responsibilities:

* Poll adapter health.
* Store health state.
* Detect degradation.
* Feed health into capability resolution.
* Trigger policy fallback where needed.

Health examples:

```text id="vv4o3s"
email provider degraded
SMS route unavailable
RSS feed invalid
XMPP stream disconnected
Hybrid-mail provider status API unavailable
```

## 10.11 Late Event Processor

The Late Event Processor handles events that arrive after state has already progressed.

Examples:

```text id="y8ro1d"
email async bounce
SMS late delivery receipt
RSS delayed fetch log
XMPP delayed delivery receipt
Hybrid-mail return mail after weeks
```

Responsibilities:

* Accept late events.
* Append them to the evidence ledger.
* Decide whether to trigger reassessment.
* Annotate existing participant/case state.
* Reopen participant/case where policy allows.
* Trigger compensating actions or manual review.
* Preserve the event even if policy chooses not to change state.

Rule:

```text id="io3lmx"
Late events are never discarded merely because a participant or case already has a derived state.
```

## 10.12 Adapter Conformance Harness

The Adapter Conformance Harness validates adapter behavior against the adapter interface and golden tests.

Responsibilities:

* Validate `AdapterDescriptor`.
* Validate capability profile.
* Validate evidence ceiling.
* Validate required actions.
* Validate event mappings.
* Validate idempotency behavior.
* Validate weakest-safe-mapping rule.
* Validate golden tests.
* Detect overclaiming.

Example golden test:

```text id="fzwdv0"
Email provider says "delivered":
  MUST emit notification.endpoint.accepted.
  MUST NOT emit interaction.notification.opened.
```

Example golden test:

```text id="h6r30q"
Hybrid-mail ordinary letter handed over:
  MUST emit delivery.postal.handed_over.
  MUST NOT emit delivery.postal.delivery_confirmed.
```

## 11. Adapter Architecture

## 11.1 Adapter Definition

An adapter is a component that connects `coordination-engine` with an external protocol, provider, system, or technology.

An adapter has these roles:

```text id="0kboym"
Adapter =
  Action Provider
  + Signal Provider
  + Capability Descriptor
  + Evidence Normalizer
  + Evidence Ceiling Declaration
  + Endpoint Quality Source
  + Advisory Assessment Source
  + Health / Diagnostics Source
```

## 11.2 Action Provider

As an action provider, the adapter performs operations requested by `coordination-engine`.

Examples:

```text id="y8rvcf"
send email
send SMS
publish RSS item
send XMPP message
submit hybrid-mail letter
grant portal access
create payment request
create signature envelope
revoke access token
archive document
request identity verification
```

## 11.3 Signal Provider

As a signal provider, the adapter emits observations.

Examples:

```text id="8jc1dw"
email provider accepted message
email hard bounce received
SMS delivery receipt received
RSS feed item fetched
XMPP delivery receipt received
hybrid-mail return mail received
portal login completed
document downloaded
payment settled
signature completed
```

## 11.4 Capability Descriptor

As a capability descriptor, the adapter declares what it can do and what evidence it can provide.

This allows `coordination-engine` to reason about which adapters are suitable for a scenario.

## 11.5 Evidence Ceiling Declaration

As an evidence ceiling source, the adapter declares the strongest meaning its events can support.

Examples:

```text id="61vu71"
email cannot prove human awareness
SMS delivered does not prove human read
RSS publication does not prove participant awareness
XMPP displayed marker does not prove comprehension
Hybrid-mail handover does not prove final delivery
```

## 12. Adapter Contract

The adapter contract is defined in `AdapterInterfaceSpecification.md`.

At runtime, the engine expects:

```text id="os2p7w"
AdapterDescriptor
AdapterCapabilityProfile
AdapterActionCapability
AdapterActionRequest
AdapterActionResult
AdapterEvent
EvidenceEvent
AdapterEvidenceAssessment
EvidenceGrade
EvidenceCeiling
NativeStatusMapping
EndpointQuality
AdapterHealth
CorrelationContext
LateEventPolicy
FeatureDependency
AssuranceCapability
```

## 13. Event Normalization

## 13.1 Native Events vs Normalized Events

External systems use different event vocabularies. The adapter layer is responsible for normalizing them.

Example:

```text id="9g284p"
SendGrid delivered
Mailgun delivered
SES Delivery
Postmark Delivery
```

These may all map to:

```text id="pqhamo"
notification.endpoint.accepted
```

with meaning:

```text id="43anbf"
recipient email server accepted the message
```

They must not map directly to business-level success.

## 13.2 Normalized Event Families

The engine defines canonical event families.

```text id="iw23ra"
coordination
participant
payload
access
notification
publication
delivery
interaction
identity
authority
payment
signature
feed
policy
result
system
manual
```

## 13.3 Adapter Examples

### Email

```text id="pwlz8d"
email.provider.accepted
→ notification.attempt.accepted_by_provider

email.transport.mx_accepted
→ notification.endpoint.accepted

email.transport.hard_bounce
→ notification.endpoint.rejected_permanent

email.open.proxy_like
→ interaction.proxy_or_privacy_interaction

email.click.scanner_like
→ interaction.scanner_or_bot_interaction
```

### SMS

```text id="26js3x"
sms.provider.accepted
→ notification.attempt.accepted_by_provider

sms.carrier.accepted
→ notification.endpoint.accepted

sms.delivered
→ notification.endpoint.accepted with device/carrier metadata

sms.undelivered
→ notification.endpoint.rejected_permanent or temporary

sms.reply.ack
→ interaction.acknowledgement_recorded
```

### RSS

```text id="06c5vv"
rss.item.published
→ feed.item.published

rss.feed.fetched
→ feed.feed.fetched

rss.link.clicked
→ interaction.unverified_actor_interaction
```

### XMPP

```text id="mnjxnz"
xmpp.stream.ack
→ notification.attempt.accepted_by_provider

xmpp.delivery_receipt
→ notification.endpoint.accepted

xmpp.displayed_marker
→ interaction.notification.opened

xmpp.reply
→ interaction.reply_received
```

### Hybrid Mail

```text id="69qicl"
hybridmail.upload.accepted
→ delivery.payload.accepted

hybridmail.validation.failed
→ payload.validation_failed

hybridmail.production.completed
→ delivery.production.completed

hybridmail.postal.handed_over
→ delivery.postal.handed_over

hybridmail.return.received
→ delivery.postal.return_received
```

## 14. Case State Derivation

The engine derives state from evidence, adapter semantics, and policy.

## 14.1 Participant Assessment

A participant assessment may include:

```yaml id="rri7qg"
ParticipantAssessment:
  participant_id: string
  state: string
  notification_state: string?
  access_state: string?
  delivery_state: string?
  interaction_state: string?
  result_state: string?
  evidence_level: EvidenceLevel
  assurance_level: AssuranceCapability?
  uncertainty_class: string?
  risk_level: string?
  next_actions:
    - NextAction
```

Example uncertainty classes:

```text id="gfeidz"
undef.pending
undef.technical_acceptance_only
undef.no_signal
undef.weak_positive
undef.identity_uncertain
undef.channel_suspicious
undef.conflicting_evidence
undef.delivery_pending
undef.escalation_required
undef.handed_to_postal_service_but_delivery_unproven
```

## 14.2 Case Assessment

A case assessment may include:

```yaml id="anxw5i"
CoordinationAssessment:
  case_id: string
  state: string
  result_satisfied: boolean
  participants_total: integer
  participants_completed: integer
  participants_pending: integer
  participants_failed: integer
  participants_escalated: integer
  progress_percentage: number
  deadline_risk: string?
  channel_risk: string?
  compliance_risk: string?
  next_actions:
    - NextAction
```

## 14.3 State Derivation Rule

Participant and case state derivation MUST use:

```text id="jo48dd"
evidence events
adapter evidence ceiling
adapter assurance capability
native status mapping confidence
scenario policy
intended result
participant requirements
deadline and thresholds
```

The engine MUST NOT turn adapter-native success into coordination success without policy evaluation.

## 15. Policy Engine

## 15.1 Policy Inputs

The policy engine evaluates:

* case state
* participant states
* evidence events
* evidence grades
* confidence grades
* adapter evidence ceilings
* adapter assurance capabilities
* native status mapping confidence
* endpoint quality
* deadlines
* result predicates
* adapter health
* channel availability
* failure modes
* scenario-specific configuration

## 15.2 Policy Outputs

The policy engine produces:

```yaml id="h3h8hu"
NextAction:
  id: string
  action_type: string
  target: string
  priority: string
  due_at: timestamp?
  adapter_action_request: AdapterActionRequest?
  explanation: string
```

Examples:

```text id="u60ell"
send_email_notification
send_sms_reminder
switch_to_push
grant_portal_access
submit_hybridmail_letter
request_manual_review
close_participant_success
close_case_partial
expire_case
```

## 15.3 Policy Example: Email Ambiguity

```yaml id="tt143n"
if:
  participant.notification_state: notification.endpoint.accepted
  source_adapter: email-connect
  participant.delivery_state: none
  age_since_notification: ">72h"
then:
  action_type: send_reminder
  channel_preference: sms
  explanation: Email was technically accepted but no access or interaction evidence was observed within 72 hours.
```

## 15.4 Policy Example: Hybrid-Mail Handover Insufficient

```yaml id="60m9o8"
if:
  participant.delivery_state: delivery.postal.handed_over
  source_adapter: hybridmail-connect
  result_requirement: delivery_confirmation
then:
  action_type: wait_or_request_status
  explanation: Postal handover is dispatch evidence but does not satisfy delivery-confirmation requirement.
```

## 15.5 Policy Example: Cross-Adapter Evidence Upgrade

```yaml id="75e7e2"
if:
  email_event: notification.endpoint.accepted
  portal_event: delivery.payload.downloaded
  portal_identity: identity.actor_authenticated
then:
  action_type: close_participant_success
  explanation: Email alone was weak, but authenticated portal download satisfies payload-access result.
```

## 16. Adapter Integration Modes

## 16.1 Embedded Library Mode

An adapter may be included as a library in the same deployment.

Suitable for:

* simple simulations
* testing
* local development
* low-volume integrations

## 16.2 Sidecar Service Mode

An adapter may run as a service alongside the engine.

Suitable for:

* provider credentials isolation
* webhook ingestion
* retry handling
* operational separation

## 16.3 External Service Mode

An adapter may run as an independently deployed service.

Suitable for:

* reusable connectors like `email-connect`
* multi-tenant environments
* shared provider integrations
* separate scaling and security boundaries

Preferred direction:

```text id="7e1g63"
coordination-engine owns the contract.
*-connect repos implement the contract.
```

## 17. Adapter Repository Pattern

Adapters should preferably live in separate repositories.

Example:

```text id="h3h1sf"
email-connect
sms-connect
rss-connect
xmpp-connect
hybridmail-connect
portal-connect
payment-connect
signature-connect
document-connect
identity-connect
```

Each adapter repository should provide:

```text id="ev9h37"
INTENT.md
docs/AdapterImplementation.md
docs/EventMapping.md
docs/ProviderModel.md
docs/EvidenceClassification.md
docs/GoldenTests.md
schemas/
src/
tests/
```

Each adapter should include a compatibility declaration:

```yaml id="zfsm9g"
coordination_engine_compatibility:
  adapter_contract_version: 1.1
  conformance_level: 3
  supported_actions:
    - notification.send
  emitted_events:
    - notification.attempt.accepted_by_provider
    - notification.endpoint.accepted
  evidence_ceiling:
    max_positive_event: interaction.unverified_actor_interaction
    max_positive_strength: medium
  known_limitations:
    - does_not_prove_human_awareness
```

## 18. Data Flow Examples

## 18.1 Notification and Access Flow

```text id="kq1g7w"
1. Client creates CoordinationCase.
2. Client adds participants and payload.
3. Access Controller creates access grants.
4. Policy Engine requests notification.
5. Capability Resolver selects email-connect.
6. Notification Controller creates AdapterActionRequest.
7. email-connect sends email.
8. email-connect emits provider accepted event.
9. Evidence Normalizer maps it to notification.attempt.accepted_by_provider.
10. Evidence Ledger records normalized event.
11. Later, portal-connect emits authenticated download event.
12. Evidence Ledger records delivery evidence.
13. Evidence Ceiling Evaluator confirms portal event can satisfy delivery/access.
14. Result Controller marks participant complete.
15. Coordination Controller updates case progress.
```

## 18.2 Multi-Channel Fallback Flow

```text id="9ezwd1"
1. Email MX acceptance is recorded.
2. No portal access is observed after threshold.
3. Policy Engine checks email evidence ceiling.
4. Email evidence is insufficient for awareness requirement.
5. Capability Resolver selects SMS fallback.
6. sms-connect sends SMS reminder.
7. SMS delivery receipt arrives.
8. Participant remains unresolved if scenario requires payload access.
9. Portal access later completes participant result.
```

## 18.3 Hybrid-Mail Fallback Flow

```text id="o1xstw"
1. Email and SMS fail or remain unresolved.
2. Policy Engine selects hybridmail-connect.
3. hybridmail-connect submits physical letter.
4. Provider validates document.
5. Provider reports postal handover.
6. Evidence Ceiling Evaluator marks strong dispatch evidence.
7. Result policy determines whether dispatch is sufficient.
8. If delivery confirmation is required, case remains pending until stronger postal evidence or fallback action.
9. If return mail arrives late, Late Event Processor triggers reassessment.
```

## 18.4 Payment Collection Flow

```text id="jc5ryh"
1. Client creates payment collection case.
2. Payload Controller registers invoices.
3. payment-connect creates payment requests.
4. email-connect sends payment notifications.
5. payment-connect emits payment_started and payment_settled events.
6. Evidence Ledger records events.
7. Result Controller marks paid participants complete.
8. Policy Engine triggers reminders for unpaid participants.
```

## 18.5 Contract Signing Flow

```text id="b1h62u"
1. Client creates contract closure case.
2. Payload Controller registers contract draft.
3. Access Controller grants contract access.
4. signature-connect creates signature flow.
5. email-connect sends notification.
6. signature-connect emits viewed, signed, declined, expired events.
7. Identity & Authority Controller evaluates signer authority.
8. Result Controller closes participant on valid signature.
9. Coordination Controller closes case when required signatures are complete.
```

## 19. Reliability Requirements

The architecture shall support:

* idempotent action requests
* duplicate event detection
* late event handling
* out-of-order event handling
* retryable and non-retryable errors
* provider outages
* adapter degradation
* correlation across systems
* partial failure
* conflicting evidence
* manual correction or override
* raw event preservation
* state reassessment after late evidence

## 20. Security Requirements

The architecture shall support:

* adapter credential isolation
* least-privilege adapter access
* secure webhook verification
* event authenticity validation where possible
* sensitive metadata minimization
* secure access grant handling
* audit logs for policy-driven and manual actions
* separation between payload storage and coordination metadata
* strict duplicate side-effect prevention for irreversible actions

## 21. Privacy Requirements

The engine should avoid storing unnecessary personal data.

Recommended practices:

* store participant references instead of full profiles where possible
* store endpoint references instead of raw endpoint values where possible
* store payload references instead of payload content
* support retention policies
* support evidence minimization
* support raw-event redaction
* separate audit requirements from operational tracking requirements
* define adapter-specific privacy profiles

## 22. Observability Requirements

The system should expose metrics for:

* active cases
* completed cases
* failed cases
* expired cases
* unresolved participants
* generated next actions
* adapter action success/failure
* adapter event ingestion latency
* evidence event volume
* late event volume
* policy evaluation results
* channel-level failure rates
* endpoint quality degradation
* evidence-ceiling insufficiency counts
* adapter health changes
* case-level progress
* deadline risk

## 23. MVP Architecture

The MVP should implement a minimal but coherent version of the architecture.

## 23.1 MVP Components

Required:

* Coordination Controller
* Result Controller
* Participant Controller
* Payload Controller
* Access Controller
* Notification Controller
* Delivery Controller
* Interaction Controller
* Evidence Ledger
* Policy Engine
* Adapter Registry
* Capability Resolver
* Evidence Normalizer
* Evidence Ceiling Evaluator
* Adapter Contract
* Simulated Adapter

Recommended:

* email-connect reference adapter
* portal/action-surface simulated adapter
* webhook event ingestion
* basic endpoint quality store
* basic late event processor

## 23.2 MVP Scenario

The recommended MVP scenario is **Digital Payload Notification and Access**.

Flow:

```text id="v7i9l1"
create case
add participants
register payload
grant access
send notification
record provider acceptance
record ambiguous/no signal cases
record authenticated payload access
derive participant states
generate reminders
close completed participants
close case when result predicate is satisfied
```

## 23.3 MVP Acceptance Criteria

The MVP shall demonstrate:

1. Creation of a multi-participant coordination case.
2. Registration of one outbound payload.
3. Definition of an intended result.
4. Dispatch of notification actions through an adapter.
5. Recording of normalized evidence events.
6. Participant-level state derivation.
7. Case-level progress assessment.
8. Ambiguous evidence handling.
9. Policy-generated reminder or escalation.
10. Closure based on sufficient delivery or interaction evidence.
11. Traceability from final state to evidence events.
12. Evidence ceiling preventing overclaiming.
13. Capability-based adapter selection.
14. Late event ingestion and reassessment at least in simulated form.

## 24. Open Technical Questions

1. Should policy rules be expressed as JSON/YAML, a DSL, embedded code, or an external rule engine?
2. Should the evidence ledger be strictly append-only from the first implementation?
3. Should adapter events be pushed, pulled, or both?
4. Should adapters call the engine directly or publish to an event bus?
5. How should raw event payloads be stored, redacted, and retained?
6. Should the engine own scheduling, or should it emit next actions to an external scheduler?
7. Should result predicates be evaluated synchronously on every event or asynchronously by a worker?
8. What is the minimal adapter contract version needed for first implementation?
9. Which adapter should become the first real reference implementation?
10. How should manual override events be represented and audited?
11. How should evidence ceilings interact with multi-adapter evidence fusion?
12. Should endpoint quality be global, tenant-scoped, case-scoped, or all three?
13. When should late events reopen a case versus merely annotate it?
14. How should golden tests be executed across separate adapter repositories?

## 25. Non-Goals

The architecture does not attempt to make `coordination-engine`:

* a general-purpose BPMN engine
* an email provider
* an SMS provider
* an RSS feed platform
* an XMPP server
* a hybrid-mail provider
* a payment provider
* a signature provider
* a document store
* a CRM
* an ERP
* a legal proof system by default
* a complete UI application

The engine coordinates across such systems through adapters.

## 26. Strategic Implementation Guidance

The recommended implementation path is:

1. Define core schemas.
2. Implement evidence ledger and case state derivation.
3. Implement adapter registry.
4. Implement capability resolver.
5. Implement evidence normalizer.
6. Implement evidence ceiling evaluator.
7. Implement adapter contract v1.1.
8. Implement simulated adapter.
9. Implement minimal notification-and-access scenario.
10. Create `email-connect` as reference notification adapter.
11. Add portal/action-surface adapter or simulation.
12. Validate policy-driven follow-up.
13. Add late-event simulation.
14. Extend toward SMS, RSS, XMPP, hybrid mail, payment, signature, and document adapters.

## 27. Summary

`coordination-engine` provides a digital-first coordination runtime. It manages goal-directed coordination cases by combining participants, payloads, action surfaces, access, notifications, deliveries, interactions, evidence, and policies.

Adapters are the bridge between the engine and the outside world, but they are not mere technical connectors. They are semantic boundary components. They provide actions, observe signals, preserve native evidence, map provider-specific events conservatively, declare evidence ceilings, expose endpoint quality, and report limitations.

The core architectural idea is:

> Adapters translate external capabilities and observations into coordination actions and evidence events. coordination-engine uses those events, constrained by adapter semantics and scenario policies, to evaluate intended results and control follow-up under uncertainty.

The core safety rule is:

> The runtime must underclaim rather than overclaim. Evidence may be combined across adapters to reach stronger conclusions, but no single adapter event may be interpreted beyond its declared evidence ceiling.