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:

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.

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

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

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:

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:

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:

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.

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.

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:

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.

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.

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:

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

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.

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:

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:

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:

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:

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:

unknown
device_known
session_authenticated
mfa_verified
identity_provider_verified
qualified_identity_verified

Example authority grades:

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:

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.

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:

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:

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:

required action
participant endpoints
payload type
action surface
required assurance
deadline
adapter health
adapter capability
feature dependencies
cost/latency constraints
scenario policy

Outputs:

candidate adapters
candidate actions
suitability ranking
reasoning
known limitations

Example:

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

Example:

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:

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:

Event:
  email notification.endpoint.accepted

Evidence ceiling:
  cannot prove human awareness

Result requirement:
  awareness >= medium

Outcome:
  insufficient; participant remains unresolved

Example:

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:

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:

AdapterEvidenceAssessment is advisory.
coordination-engine remains authoritative for participant and case state.

Example:

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:

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:

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:

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:

Email provider says "delivered":
  MUST emit notification.endpoint.accepted.
  MUST NOT emit interaction.notification.opened.

Example golden test:

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:

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:

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:

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:

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:

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:

SendGrid delivered
Mailgun delivered
SES Delivery
Postmark Delivery

These may all map to:

notification.endpoint.accepted

with meaning:

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.

coordination
participant
payload
access
notification
publication
delivery
interaction
identity
authority
payment
signature
feed
policy
result
system
manual

13.3 Adapter Examples

Email

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

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

rss.item.published
→ feed.item.published

rss.feed.fetched
→ feed.feed.fetched

rss.link.clicked
→ interaction.unverified_actor_interaction

XMPP

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

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:

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:

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:

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:

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:

NextAction:
  id: string
  action_type: string
  target: string
  priority: string
  due_at: timestamp?
  adapter_action_request: AdapterActionRequest?
  explanation: string

Examples:

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

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

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

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:

coordination-engine owns the contract.
*-connect repos implement the contract.

17. Adapter Repository Pattern

Adapters should preferably live in separate repositories.

Example:

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:

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:

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

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

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

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

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

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:

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.