coordination-engine/spec/coordination-model-v0.1.md

coordination-model-v0.1.md

1. Document Status

Document: coordination-model-v0.1.md Project: coordination-engine Version: 0.1 Status: Baseline Draft Scope: Coordination ontology and communication-act lifecycle Related Documents:

• INTENT.md
• SCOPE.md
• ProductRequirementsDocument.md
• RuntimeArchitectureAndAdapterSubsystem.md
• AdapterInterfaceSpecification.md

2. Purpose

This document defines the first coordination ontology for coordination-engine.

It establishes the foundational vocabulary for how actors align on shared goals through commitments and how the engine closes the loop with observations, assessments, and follow-up actions.

The ontology is intentionally narrower than the full product requirements. Version 0.1 focuses on four pillars:

1. Actors — who participates in coordination
2. Goals — what the coordination process is trying to achieve
3. Commitments — what parties agree to do or enable
4. Observation loops — how evidence drives progress until a goal is satisfied, failed, expired, escalated, or manually closed

Downstream specs (runtime architecture, adapter contracts, scenario patterns) should map to this ontology rather than invent parallel terminology.

3. Core Principle

A coordination case succeeds when its goal is satisfied, not when a message has merely been sent.

Digital coordination is the controlled arrangement of actors, payloads, access, communication acts, and evidence so that intended results can be achieved under uncertainty.

4. Ontology Overview

CoordinationCase
  goal: IntendedResult
  actors: Participant[]
  commitments: Commitment[]
  communication_acts: CommunicationAct[]
  observations: EvidenceEvent[]
  assessments: Assessment[]
  policies: Policy[]

Observation loop:
  CommunicationAct → native signal → EvidenceEvent → Assessment → Policy decision → next CommunicationAct or closure

At runtime, a CoordinationCase is the container object. Actors hold roles. Goals define success. Commitments express required obligations. Communication acts are the outward-facing operations (notify, deliver, interact). Observation loops connect external signals back to case progress.

5. Actors

5.1 Actor

An Actor is any entity that can initiate coordination, receive coordination, perform interactions, emit system events, or be referenced in evidence.

Actor types:

Type	Description	Examples
human	A natural person	Customer, employee, signer
organization	A legal or operational entity	Company, department, authority
system	A software system acting on behalf of a party	ERP, CRM, payment gateway
agent	An automation actor with delegated authority	Custodian agent, workflow bot
bot	An automated endpoint with limited authority	Scanner, webhook processor
unknown	Actor not yet identified	Anonymous portal visitor

An actor may be referenced before identity is confirmed. The engine must support progressive identity strengthening through evidence.

5.2 Participant

A Participant is an actor bound to a specific CoordinationCase with one or more roles, endpoints, and required outcomes.

Participants are case-scoped. The same human may be a participant in multiple cases with different roles.

Common participant roles:

• initiator — starts the case and defines the goal
• recipient — expected to receive awareness, access, or payload
• respondent — expected to submit a response or payload
• signer — expected to sign or countersign
• payer — expected to settle payment
• approver — expected to approve or reject
• delegate — acts with delegated authority for another participant
• intermediary — routes or transforms communication without being the business target
• observer — may view progress or evidence without being required to act

Each participant may carry:

• participant_id
• actor_ref — stable identity reference when known
• roles[]
• endpoints[] — email, phone, portal account, API subject, etc.
• required_outcomes[] — participant-level success conditions
• authority_attributes — signing level, approval limit, delegation chain
• state — derived from evidence (see section 8)
• evidence_level — current confidence in progress toward required outcomes

5.3 ActorContext

ActorContext describes the actor associated with an observation or interaction event.

ActorContext:
  actor_ref: string?
  actor_type: human | organization | system | agent | bot | unknown
  participant_id: string?
  identity_strength: none | suspected | authenticated | verified
  authority_strength: none | delegated | authorized

Actor context may be incomplete at event time. Adapters and controllers append or refine context as stronger evidence arrives.

5.4 Actor Boundaries

Actors are not channels.

Email inboxes, phone numbers, portal sessions, and API clients are endpoints through which actors may be reached or may act. A single actor may have multiple endpoints. A single endpoint may temporarily map to an unknown actor until identity evidence is recorded.

6. Goals

6.1 CoordinationCase

A CoordinationCase is a goal-directed coordination process.

It binds:

• one initiating context
• one primary goal (IntendedResult)
• one or more participants
• zero or more payloads and action surfaces
• the commitments required to reach the goal
• the policies that govern follow-up under uncertainty

Core case attributes:

CoordinationCase:
  id: string
  purpose: string
  scenario_type: string
  goal: IntendedResult
  state: draft | active | paused | partially_completed | completed | failed | expired | cancelled | manually_closed
  created_at: timestamp
  deadlines: Deadline[]

6.2 IntendedResult

An IntendedResult defines what success means for the case.

Examples:

• all required recipients accessed the payload
• all required respondents submitted valid data
• all required signers completed signature
• payment settled above threshold
• incident acknowledged by all critical participants

IntendedResult:
  result_type: access | submission | acceptance | signature | payment | acknowledgement | completion | custom
  target_population: all_required | threshold | named_participants
  required_outcome: string
  required_evidence_level: low | medium | high
  quantitative_threshold: number?
  deadline: timestamp?
  partial_success_rules: PartialSuccessRule[]
  failure_rules: FailureRule[]

A goal is satisfied only when its predicate evaluates true against current assessments with sufficient evidence. Weak channel signals alone do not satisfy a goal.

6.3 Goal States

Case-level goal interpretation uses these assessment states:

State	Meaning
unresolved	Insufficient evidence to judge progress
in_progress	Some required evidence present, goal not yet satisfied
partially_satisfied	Goal rules allow partial success and threshold is met
satisfied	Goal predicate is true with required evidence
failed	Failure rules triggered
expired	Deadline passed without required outcome
escalated	Manual or policy-driven escalation replaced normal closure path
manually_closed	Operator closed the case with documented override

Goal state is always derived from evidence and policy evaluation. It is not set directly by message dispatch.

6.4 Goal vs Communication Act

A goal is not a message.

Sending a notification, granting access, or opening a payment page are communication acts in service of commitments. They may produce evidence relevant to the goal, but they do not constitute goal satisfaction by themselves.

7. Commitments

7.1 Commitment

A Commitment is an explicit or policy-derived obligation that some party will enable, attempt, or perform an outcome relevant to the case goal.

Commitments make coordination auditable. Instead of only recording that an email was sent, the engine records what was obligated, by whom, for whom, by when, and whether observations support fulfillment.

Commitment:
  id: string
  case_id: string
  kind: awareness | access | delivery | interaction | response | payment | signature | acknowledgement | enforcement | custom
  obligor: participant_id | system | policy_engine
  beneficiary: participant_id | case
  subject_ref: payload_id | action_surface_id | communication_act_id?
  due_by: timestamp?
  required_evidence_level: low | medium | high
  state: proposed | active | satisfied | breached | waived | expired | cancelled
  satisfaction_predicate: string

7.2 Commitment Sources

Commitments may originate from:

1. Scenario definition — a contract-signing scenario requires signature commitments from each signer
2. Case creation — the initiator requests collection of documents by a deadline
3. Policy engine — a reminder policy creates a new awareness commitment after non-response
4. Participant action — a delegate accepts responsibility for responding on behalf of another participant

7.3 Commitment Kinds

Kind	Obligation	Typical fulfillment evidence
awareness	Target participant should become aware of the case or payload	notification opened, portal visit, authenticated session
access	Target participant should receive usable access to a payload or action surface	access grant used, payload viewed
delivery	Payload should become available, transferred, submitted, or consumed	delivery submitted, download recorded, archive stored
interaction	Target participant should perform a meaningful action	form submitted, approval recorded, link clicked with identity
response	Target participant should provide a structured answer or artifact	inbound payload accepted, validation passed
payment	Payer should settle an amount	payment initiated, payment settled
signature	Signer should sign or countersign with required assurance	signature completed, authority verified
acknowledgement	Participant should confirm awareness of an urgent item	acknowledgement interaction recorded
enforcement	System should apply deadline or non-compliance consequence	access revoked, account restricted, case escalated

7.4 Commitment Lifecycle

proposed
  → active
    → satisfied
    → breached
    → expired
    → waived
    → cancelled

State transitions are driven by observations and policy rules:

• proposed → active when the engine accepts the commitment and may schedule communication acts
• active → satisfied when satisfaction predicate is met with required evidence
• active → breached when failure rules fire
• active → expired when due_by passes without satisfaction
• active → waived when an authorized actor or policy explicitly waives the obligation
• * → cancelled when the case is cancelled or the commitment is superseded

A commitment may be satisfied at participant level before the case goal is satisfied globally.

7.5 Commitments and Communication Acts

Commitments are the semantic layer above transport.

A notification attempt does not create a commitment by itself. The engine creates or activates a commitment first, then derives communication acts to pursue it.

Example:

Commitment: signer S must sign contract C by Friday
  → CommunicationAct: notify S via email
  → CommunicationAct: grant portal access to signature flow
  → Observation: portal authenticated visit
  → Observation: signature completed
  → Commitment state: satisfied

8. Observation Loops

8.1 Observation

An Observation is a recorded fact about what happened in the world or in an external system.

Observations enter the engine primarily as normalized EvidenceEvent records. Raw provider events are preserved, but assessments are derived from normalized meaning.

EvidenceEvent:
  id: string
  case_id: string
  event_type: string
  observed_at: timestamp
  source_adapter: string
  participant_id: string?
  actor_context: ActorContext?
  payload_ref: string?
  action_surface_ref: string?
  communication_act_ref: string?
  normalized_meaning: string
  confidence: low | medium | high
  evidence_grade: weak | moderate | strong
  raw_event_ref: string?
  correlation_id: string?

8.2 Assessment

An Assessment is a derived judgment based on one or more observations.

Assessments exist at multiple levels:

• participant state — has this participant met required outcomes?
• commitment state — is this obligation satisfied, breached, or still active?
• case progress — how close is the case to goal satisfaction?
• uncertainty flags — conflicting, missing, late, or weak evidence

Assessments must remain traceable to the observations that support them.

8.3 Observation Loop

The engine operates through a repeating observation loop:

1. Goal and commitments define required outcomes
2. Policy engine selects next communication acts
3. Adapters execute acts and emit native signals
4. Adapter boundary normalizes signals into EvidenceEvents
5. Controllers derive participant, commitment, and case assessments
6. Policy engine evaluates assessments against deadlines and thresholds
7. Loop continues with follow-up acts, escalation, or closure

flowchart LR
  G[Goal] --> C[Commitments]
  C --> P[Policy Engine]
  P --> A[Communication Acts]
  A --> N[Native Signals]
  N --> E[EvidenceEvents]
  E --> S[Assessments]
  S --> P
  S --> CL[Closure / Escalation]
  P --> CL

The loop is event-driven and may run continuously as late evidence arrives.

8.4 Loop Properties

Observation loops in coordination scenarios have common properties:

1. Non-linearity — events may arrive out of order, late, duplicated, or in conflict
2. Weak evidence — channel acceptance is not human awareness
3. Progressive strengthening — identity and authority may start unknown and become verified
4. Multi-source fusion — one assessment may depend on notification, access, and interaction evidence combined
5. Policy-gated action — follow-up acts are chosen by policy, not hardcoded per channel
6. Auditable closure — final case state must cite the evidentiary basis

8.5 Uncertainty Handling

Uncertainty is first-class in the loop.

The engine must represent:

• missing expected observations
• contradictory observations
• proxy, scanner, or bot-like interactions
• authenticated actor mismatch
• expired commitments with partial evidence
• adapter evidence ceilings

When evidence is weak, the loop prefers:

• unresolved or in_progress assessment states
• additional observation opportunities
• policy actions such as wait, remind, switch_channel, or manual_review

Underclaiming is mandatory. Adapters report what happened; the engine decides what it means for goals and commitments.

9. Communication Act Lifecycle

9.1 CommunicationAct

A CommunicationAct is an engine-directed operation that pursues one or more commitments through a channel or surface.

Kinds:

• notification — awareness-oriented prompt
• delivery — payload availability, transfer, retrieval, submission, or consumption
• interaction — meaningful action on a payload or action surface
• access_change — grant, revoke, expire, or delegate access
• enforcement — apply deadline or compliance consequence

CommunicationAct:
  id: string
  case_id: string
  kind: notification | delivery | interaction | access_change | enforcement
  commitment_id: string
  adapter_ref: string?
  action_surface_ref: string?
  target_participant_id: string?
  state: planned | requested | accepted | in_flight | observed | failed | cancelled
  requested_at: timestamp?
  correlation_id: string?

9.2 Lifecycle Phases

Every communication act follows a common lifecycle pattern:

intent declared
  → attempt requested
  → attempt accepted or rejected
  → provider or surface activity observed
  → normalized evidence recorded
  → act state updated
  → assessments and policies re-evaluated

This pattern is shared across channels. Channel-specific details belong in adapter specs, not in the core ontology.

9.3 Notification Lifecycle

Notifications pursue awareness commitments.

Typical phases:

notification.planned
notification.requested
notification.accepted_by_adapter
notification.rejected_by_adapter
notification.accepted_by_provider
notification.endpoint_accepted
notification.opened
notification.clicked
notification.failed
notification.expired

Important distinction:

• endpoint_accepted means the channel accepted the message for the endpoint
• it does not mean the participant became aware
• stronger awareness requires additional observations where the channel allows them

9.4 Delivery Lifecycle

Deliveries pursue access, transfer, submission, or consumption commitments.

Typical phases:

delivery.planned
delivery.payload.published
delivery.access.granted
delivery.payload.viewed
delivery.payload.downloaded
delivery.payload.submitted
delivery.payload.validated
delivery.payload.rejected
delivery.completed
delivery.failed

Delivery evidence may also inform notification and goal assessments. For example, portal access can be stronger evidence than email open tracking.

9.5 Interaction Lifecycle

Interactions pursue response, signature, payment, acknowledgement, and other outcome commitments.

Typical phases:

interaction.surface.opened
interaction.identity.started
interaction.identity.completed
interaction.action.started
interaction.action.completed
interaction.declined
interaction.disputed
interaction.failed

Interactions should be classified by actor certainty and authority strength. Result-relevant interactions require stronger evidence than anonymous page loads.

9.6 Act State vs Goal State

Communication act success is local.

A notification act may reach observed while the related awareness commitment remains active because evidence is too weak. Case closure requires goal-level assessment, not merely exhausted communication attempts.

10. Supporting Concepts

The ontology above is intentionally focused. These related concepts appear in adjacent specs and runtime design:

Concept	Role in the ontology
Payload	Subject of access, delivery, and interaction commitments
ActionSurface	Place where interactions occur
AccessGrant	Enabler for access commitments
Policy	Rules that drive observation-loop decisions
Adapter	Boundary that executes acts and supplies observations
Deadline	Time bound on goals and commitments
NextAction	Policy output consumed by controllers

11. Minimal Case Example

Invoice payment collection:

Case goal: payment settled by payer P before due date

Participants:
  - initiator: billing system
  - payer: P

Commitments:
  - awareness: payer P should become aware of invoice I
  - access: payer P should receive access to payment surface S
  - payment: payer P should settle invoice I
  - enforcement: system should escalate if unpaid after deadline

Observation loop:
  1. Publish invoice payload and grant access
  2. Notify payer via email adapter
  3. Observe endpoint_accepted (weak evidence)
  4. Observe portal visit and authenticated session (stronger evidence)
  5. Awareness commitment satisfied
  6. Observe payment initiated then settled
  7. Payment commitment satisfied
  8. Goal assessment: satisfied
  9. Case closed with traceable evidence chain

12. Terminology Mapping

Ontology term (v0.1)	Existing project term
Actor	Actor / entity referenced in events
Participant	Participant
Goal	IntendedResult / case success criterion
CoordinationCase	CoordinationCase
Commitment	Obligation implied by scenario, policy, or participant requirement
CommunicationAct	Notification / Delivery / Interaction operation
Observation	EvidenceEvent
Assessment	Derived participant, commitment, or case state
Observation loop	Evidence-driven policy cycle
Endpoint	Participant contact channel

13. v0.1 Non-Goals

This baseline ontology does not yet specify:

• concrete API schemas or persistence models
• policy language syntax
• full commitment algebra for nested or conditional obligations
• legal validity rules for regulated notice or signature scenarios
• cross-case actor identity merge rules
• runtime controller interfaces

Those belong in later specs once this vocabulary is stable.

14. Success Criteria for v0.1

The ontology is fit for purpose when:

1. A reader can explain a coordination scenario using actors, goals, commitments, and observation loops without referring to transport details.
2. Adapter and runtime specs can map their entities to this document without contradictory definitions.
3. A case can be traced from goal declaration through commitments, communication acts, observations, assessments, and closure.
4. Weak vs strong evidence distinctions remain visible at each loop step.

15. Guiding Statement

coordination-engine coordinates actors around shared goals through explicit commitments, pursues those commitments with communication acts, and uses observation loops to decide progress, follow-up, and closure under uncertainty.