coordination-engine/history/260601-RuntimeArchitectureAndAdapterSubsystem.md

Technical Specification Document: coordination-engine Architecture and Adapter Subsystem

1. Document Status

Status: Draft Project: coordination-engine Document Type: Technical Specification Document Scope: Overall runtime architecture and adapter subsystem Primary Audience: Developers, architects, integration partners, automation agents

2. Purpose

This document specifies the technical architecture of coordination-engine and describes how it uses adapters to integrate with external protocols, systems, providers, and technologies.

coordination-engine is a generalized, 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.

The adapter subsystem enables coordination-engine to remain protocol-neutral while integrating with concrete systems such as email, SMS, push notifications, RSS, XMPP, portals, payment providers, signature providers, document stores, identity providers, CRM systems, ERP systems, and webhooks.

3. Architectural Intent

The architecture is based on the following principles:

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

2. Digital coordination is evidence-driven. The engine records observations from multiple systems and derives participant and case states from evidence.

3. Adapters are capability providers. Adapters are not simple transport drivers. They expose actions and emit normalized evidence.

4. External systems remain external. The engine should orchestrate and evaluate coordination, not replace email providers, portals, payment systems, signature systems, document stores, or identity systems.

5. Uncertainty is first-class. Many digital signals are ambiguous. The architecture must represent weak, conflicting, late, missing, or uncertain evidence.

6. Scenario-specific applications should compose concepts selectively. Simple use cases should not require payment, signature, or document-validation logic. Complex use cases should be able to add stronger identity, authority, payload, access, and evidence requirements.

4. System Overview

coordination-engine is a headless coordination runtime composed of a central coordination controller, specialized domain controllers, an evidence ledger, a policy engine, and an adapter layer.

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-layer

The engine manages CoordinationCase objects. Each case represents a goal-directed process initiated by one party to achieve an intended result involving one or more participants.

External systems connect through adapters. Adapters provide actions, such as sending an email or creating a payment request, and signals, such as delivery events, click events, payment settlement events, or signature completion events.

5. Core Runtime Model

5.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

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

5.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

5.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
  threshold: Threshold?
  deadline: timestamp?
  partial_success_rules: RuleRef[]
  failure_rules: RuleRef[]

Examples:

result_type: payload_access
required_outcome: pdf_downloaded
threshold:
  type: percentage
  value: 95
deadline: 2026-12-31T23:59:59Z

result_type: payment_collection
required_outcome: payment_settled
threshold:
  type: amount
  value: 100000
  currency: EUR

5.4 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?

5.5 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

ActionSurface:
  id: string
  type: string
  adapter_ref: string
  url: string?
  endpoint_ref: string?
  supported_interactions: string[]
  access_policy_ref: string?

5.6 EvidenceEvent

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

EvidenceEvent:
  id: string
  event_type: string
  source_adapter: string?
  native_event_type: string?
  coordination_case_id: string
  participant_id: string?
  payload_id: string?
  action_surface_id: string?
  actor_ref: ActorRef?
  timestamp: timestamp
  normalized_meaning: string
  confidence: ConfidenceGrade
  evidence_grade: EvidenceGrade
  raw_event_ref: string?
  correlation: CorrelationContext

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

6. Runtime Components

6.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 layer.
• Close, fail, expire, pause, or escalate cases.

The coordination controller does not directly speak to email, SMS, payment, signature, portal, or other external systems. It uses adapters.

6.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.

Example derived states:

active
partially_completed
completed_successfully
completed_partially
failed
expired
manually_closed

6.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.

Example participant states:

not_started
notification_pending
notified
awareness_uncertain
access_granted
accessed
interaction_started
required_action_completed
failed
expired
escalated
completed

6.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.

6.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

6.6 Notification Controller

The notification-controller manages awareness-oriented signals.

Responsibilities:

• Create notification attempts.
• Select channels according to policy.
• 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.

6.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.

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

6.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

6.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

6.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.
• 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.

6.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.
• 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

6.12 Adapter Layer

The adapter-layer connects coordination-engine to external systems.

Responsibilities:

• Register adapter capabilities.
• Dispatch adapter actions.
• Receive adapter events.
• Normalize events into evidence.
• Monitor adapter health.
• Enforce idempotency and correlation.
• Isolate provider-specific logic from the core engine.

Adapters may be implemented as separate services or libraries. The preferred architectural direction is separate *-connect repositories.

Examples:

email-connect
rss-connect
sms-connect
push-connect
xmpp-connect
portal-connect
payment-connect
signature-connect
document-connect
identity-connect
crm-connect
erp-connect

7. Adapter Architecture

7.1 Adapter Definition

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

An adapter has three roles:

Adapter = Action Provider + Signal Provider + Capability Descriptor

7.2 Action Provider

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

Examples:

• send email
• send SMS
• publish RSS item
• create push notification
• grant portal access
• create payment request
• create signature envelope
• revoke access token
• archive document
• request identity verification

7.3 Signal Provider

As a signal provider, the adapter emits observations.

Examples:

• email provider accepted message
• email hard bounce received
• SMS delivery receipt received
• push notification tapped
• portal login completed
• document downloaded
• payment settled
• signature completed
• form submitted
• identity verified

7.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.

8. Adapter Contract

8.1 AdapterDescriptor

Each adapter shall expose an AdapterDescriptor.

AdapterDescriptor:
  adapter_id: string
  adapter_type: string
  adapter_name: string
  adapter_version: string
  contract_version: string
  supported_actions:
    - AdapterActionCapability
  emitted_event_types:
    - string
  supported_channels:
    - string
  evidence_strength_profile: EvidenceStrengthProfile
  identity_strength_profile: IdentityStrengthProfile
  latency_profile: LatencyProfile
  cost_profile: CostProfile
  failure_modes:
    - string
  configuration_schema_ref: string?
  health_endpoint: string?

Example:

adapter_id: email-connect.default
adapter_type: email
adapter_name: email-connect
adapter_version: 0.1.0
contract_version: 0.1.0
supported_channels:
  - email
supported_actions:
  - action_type: notification.send
  - action_type: notification.send_reminder
emitted_event_types:
  - notification.attempt.accepted_by_provider
  - notification.endpoint.accepted
  - notification.endpoint.rejected_permanent
  - interaction.proxy_or_privacy_interaction
  - interaction.scanner_or_bot_interaction
  - interaction.unverified_actor_interaction
failure_modes:
  - provider_rejected
  - endpoint_rejected
  - deferred
  - hard_bounce
  - soft_bounce
  - complaint
  - suppressed

8.2 AdapterActionRequest

An AdapterActionRequest is sent by the engine to an adapter.

AdapterActionRequest:
  request_id: string
  action_type: string
  coordination_case_id: string
  participant_id: string?
  payload_ref: string?
  action_surface_ref: string?
  channel: string?
  target_endpoint: EndpointRef?
  content_ref: string?
  template_ref: string?
  variables: object?
  tracking_context: TrackingContext
  policy_context: PolicyContext?
  idempotency_key: string
  requested_at: timestamp

Example for email:

request_id: req_123
action_type: notification.send
coordination_case_id: case_456
participant_id: participant_789
channel: email
target_endpoint:
  type: email
  value: recipient@example.com
template_ref: secure-document-available
variables:
  recipient_name: Example Recipient
  portal_link: https://portal.example.com/access/abc
tracking_context:
  correlation_id: corr_001
  notification_id: notif_001
idempotency_key: case_456:participant_789:notif_001

8.3 AdapterActionResult

An AdapterActionResult is returned by the adapter after receiving an action request.

AdapterActionResult:
  request_id: string
  adapter_id: string
  accepted: boolean
  adapter_operation_id: string?
  provider_operation_id: string?
  initial_status: string
  raw_response_ref: string?
  normalized_events:
    - EvidenceEvent
  error:
    code: string?
    message: string?
    retryable: boolean?

The action result is not final proof of outcome. It only records whether the adapter accepted or rejected the requested action and may emit initial evidence events.

8.4 AdapterEvent

An AdapterEvent is an incoming event from an adapter.

AdapterEvent:
  event_id: string
  adapter_id: string
  event_type: string
  native_event_type: string?
  timestamp: timestamp
  coordination_case_id: string?
  participant_id: string?
  payload_id: string?
  action_surface_id: string?
  message_ref: string?
  endpoint_ref: EndpointRef?
  actor_ref: ActorRef?
  raw_event_ref: string?
  normalized_meaning: string
  confidence: ConfidenceGrade
  evidence_grade: EvidenceGrade
  correlation: CorrelationContext

Adapter events are usually converted into EvidenceEvent records in the evidence ledger.

8.5 AdapterHealth

Adapters should expose health information.

AdapterHealth:
  adapter_id: string
  status: healthy | degraded | unavailable | misconfigured
  last_action_success_at: timestamp?
  last_event_received_at: timestamp?
  provider_connectivity: string?
  configuration_validity: string?
  known_degradation:
    - string

9. Event Normalization

9.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 should not map directly to business-level success.

9.2 Normalized Event Families

The engine should define canonical event families.

coordination.*
participant.*
payload.*
access.*
notification.*
delivery.*
interaction.*
identity.*
authority.*
payment.*
signature.*
policy.*
result.*
system.*
manual.*

9.3 Example Email Normalization

email.provider.accepted
→ notification.attempt.accepted_by_provider

email.transport.mx_accepted
→ notification.endpoint.accepted

email.transport.hard_bounce
→ notification.endpoint.rejected_permanent

email.transport.soft_bounce
→ notification.endpoint.deferred

email.open.proxy_like
→ interaction.proxy_or_privacy_interaction

email.click.scanner_like
→ interaction.scanner_or_bot_interaction

email.click.unverified
→ interaction.unverified_actor_interaction

email.complaint
→ notification.channel.complaint_received

9.4 Example Portal Normalization

portal.login_success
→ identity.actor_authenticated

portal.document_viewed
→ delivery.payload_viewed

portal.pdf_downloaded
→ delivery.payload_retrieved

portal.acknowledgement_submitted
→ interaction.acknowledgement_recorded

9.5 Example Payment Normalization

payment.request_created
→ delivery.payment_request_available

payment.link_clicked
→ interaction.payment_surface_opened

payment.started
→ interaction.payment_started

payment.succeeded
→ payment.succeeded

payment.settled
→ result.payment_settled

payment.failed
→ payment.failed

payment.disputed
→ payment.disputed

10. Evidence Grading

Not all evidence is equally strong. The architecture must avoid treating weak technical signals as business success.

10.1 EvidenceGrade

A generic evidence grade may contain:

EvidenceGrade:
  category: weak | medium | strong | conclusive | ambiguous | negative
  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
  non_repudiation_strength: none | low | medium | high

10.2 Examples

Email MX acceptance:

category: weak
actor_certainty: none
payload_certainty: low
interaction_certainty: none

Anonymous link click:

category: ambiguous
actor_certainty: low
interaction_certainty: medium

Authenticated portal login:

category: strong
actor_certainty: high
interaction_certainty: medium

PDF downloaded by authenticated participant:

category: strong
actor_certainty: high
payload_certainty: high
interaction_certainty: high

Qualified signature completed:

category: conclusive
actor_certainty: high
authority_certainty: high
payload_certainty: high
interaction_certainty: high
non_repudiation_strength: high

11. Case State Derivation

The engine derives state from evidence and policy.

11.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
  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

11.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

12. Policy Engine

12.1 Policy Inputs

The policy engine evaluates:

• case state
• participant states
• evidence events
• evidence grades
• deadlines
• result predicates
• adapter health
• channel availability
• failure modes
• scenario-specific configuration

12.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
request_manual_review
close_participant_success
close_case_partial
expire_case

12.3 Policy Example

if:
  participant.notification_state: notification.endpoint.accepted
  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."

13. Adapter Integration Modes

13.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

13.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

13.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.

14. Adapter Repository Pattern

Adapters should preferably live in separate repositories.

Example:

email-connect
rss-connect
sms-connect
push-connect
portal-connect
payment-connect
signature-connect
document-connect
identity-connect

Each adapter repository should provide:

INTENT.md
docs/AdapterArchitecture.md
docs/EventMapping.md
docs/ProviderModel.md
docs/EvidenceClassification.md
schemas/
src/
tests/

Each adapter should include a compatibility declaration:

coordination_engine_compatibility:
  adapter_contract_version: 0.1.0
  supported_actions:
    - notification.send
  emitted_events:
    - notification.attempt.accepted_by_provider
    - notification.endpoint.accepted
  known_limitations:
    - does_not_prove_inbox_delivery
    - open_tracking_is_ambiguous

15. email-connect as Reference Adapter

email-connect should be the first reference adapter.

15.1 Standalone Role

email-connect should be useful independently as a headless email communication and evidence service.

Standalone capabilities:

• send transactional emails
• ingest provider events
• track message timelines
• classify bounces
• handle suppression
• classify opens and clicks
• expose normalized email evidence
• debug delivery uncertainty

15.2 coordination-engine Role

As an adapter, email-connect provides:

Actions:

notification.send
notification.send_reminder
notification.register_tracking_context
recipient.suppress
recipient.unsuppress

Signals:

notification.attempt.accepted_by_provider
notification.attempt.rejected_by_provider
notification.endpoint.accepted
notification.endpoint.deferred
notification.endpoint.rejected_permanent
interaction.proxy_or_privacy_interaction
interaction.scanner_or_bot_interaction
interaction.unverified_actor_interaction
notification.channel.complaint_received
notification.channel.unsubscribe_received
interaction.reply_received

15.3 Email-Specific Boundary

email-connect may classify email events, but it does not decide case-level success.

It may say:

MX accepted
hard bounce received
open appears privacy-proxy-like
click appears scanner-like

coordination-engine decides:

participant remains unresolved
send reminder
switch channel
close success
escalate
fail participant

16. Data Flow Examples

16.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. Notification Controller creates AdapterActionRequest.
6. email-connect sends email.
7. email-connect emits provider accepted event.
8. Evidence Ledger records normalized event.
9. Later, portal-connect emits authenticated download event.
10. Evidence Ledger records delivery evidence.
11. Result Controller marks participant complete.
12. Coordination Controller updates case progress.

16.2 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.

16.3 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.

17. Reliability Requirements

The architecture shall support:

• idempotent action requests
• duplicate event detection
• late event handling
• retryable and non-retryable errors
• provider outages
• adapter degradation
• correlation across systems
• partial failure
• conflicting evidence
• manual correction or override

18. 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

19. Privacy Requirements

The engine should avoid storing unnecessary personal data.

Recommended practices:

• store participant references instead of full profiles where possible
• store payload references instead of payload content
• support retention policies
• support evidence minimization
• support redaction of raw event data
• separate audit requirements from operational tracking requirements

20. 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
• policy evaluation results
• channel-level failure rates
• case-level progress
• deadline risk

21. MVP Architecture

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

21.1 MVP Components

Required:

• Coordination Controller
• Result Controller
• Participant Controller
• Payload Controller
• Access Controller
• Notification Controller
• Interaction Controller
• Evidence Ledger
• Policy Engine
• Adapter Contract
• Simulated Adapter

Recommended:

• email-connect reference adapter
• portal/action-surface simulated adapter
• webhook event ingestion

21.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

21.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.

22. 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 email-connect?
9. Which provider should be used first for a real email adapter implementation?
10. How should manual override events be represented and audited?

23. Non-Goals

The architecture does not attempt to make coordination-engine:

• a general-purpose BPMN engine
• an email 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.

24. Strategic Implementation Guidance

The recommended implementation path is:

1. Define the core schemas.
2. Implement evidence ledger and case state derivation.
3. Implement adapter contract.
4. Implement simulated adapter.
5. Implement minimal notification-and-access scenario.
6. Create email-connect as reference adapter.
7. Add portal/action-surface adapter or simulation.
8. Validate policy-driven follow-up.
9. Extend toward request/collect, acceptance, signature, and payment patterns.

25. 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. They provide actions and signals, normalize provider-specific events, and declare their capabilities. The engine remains responsible for result evaluation, uncertainty handling, follow-up decisions, and coordination state.

The core architectural idea is:

Adapters translate external capabilities and observations into coordination actions and evidence events. coordination-engine uses those events to evaluate intended results and control follow-up under uncertainty.