diff --git a/spec/coordination-model-v0.1.md b/spec/coordination-model-v0.1.md new file mode 100644 index 0000000..72e65cd --- /dev/null +++ b/spec/coordination-model-v0.1.md @@ -0,0 +1,586 @@ +# 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. \ No newline at end of file diff --git a/workplans/COORDINATION-WP-0002-coordination-model-spec.md b/workplans/COORDINATION-WP-0002-coordination-model-spec.md index f718a2a..8241114 100644 --- a/workplans/COORDINATION-WP-0002-coordination-model-spec.md +++ b/workplans/COORDINATION-WP-0002-coordination-model-spec.md @@ -4,11 +4,11 @@ type: workplan title: "Coordination model specification baseline" domain: communication repo: coordination-engine -status: ready +status: finished owner: codex topic_slug: communication created: "2026-06-22" -updated: "2026-06-22" +updated: "2026-06-24" state_hub_workstream_id: "2b62c9df-577d-45ce-81a7-cf343e2fb6b0" --- @@ -20,9 +20,10 @@ Draft the first coordination ontology and message lifecycle spec for the engine. ```task id: COORDINATION-WP-0002-T01 -status: todo +status: done priority: high state_hub_task_id: "0ece010b-4597-4ae9-b77d-26a3ff8c906f" ``` -Write `spec/coordination-model-v0.1.md` covering actors, goals, commitments, and observation loops. +Result 2026-06-24: Authored `spec/coordination-model-v0.1.md` with actors, goals, +commitments, observation loops, and communication-act lifecycle baseline.