generated from coulomb/repo-seed
tegwick
74b481931c
Author the baseline coordination ontology covering actors, goals, commitments, observation loops, and communication-act lifecycles. Complete COORDINATION-WP-0002.
586 lines
21 KiB
Markdown
586 lines
21 KiB
Markdown
# 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. |