# 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

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

```yaml
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:

```yaml
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

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

```yaml
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

```text
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:

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

```yaml
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:

```text
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
```

```mermaid
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

```yaml
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:

```text
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:

```text
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:

```text
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:

```text
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:

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