@peacethinking/mediation-workflows

Deterministic mediation flows — XState v5 machines, workflow templates, voting engine.

Production-ready state machines and workflow infrastructure for building AI-assisted mediation platforms. Includes 8 workflow templates, a pure voting engine with conflict resolution, and psychologically-informed emotional check-in logic.

Install

npm install @peacethinking/mediation-workflows

Usage

XState State Machine

import { participantWorkflowMachine } from '@peacethinking/mediation-workflows';
import { createActor } from 'xstate';

const actor = createActor(participantWorkflowMachine);
actor.start();

// States: idle -> executingElement -> readyToFinalize -> finalized
//         -> waitingForMediation -> reviewingProposals -> voting -> resolved

actor.send({ type: 'START_WORKFLOW', elements: myWorkflowElements });
actor.send({ type: 'ELEMENT_COMPLETED', elementId: 'step-1', data: { text: '...' } });
actor.send({ type: 'NEXT_ELEMENT' });

Workflow Templates

import { WORKFLOW_TEMPLATES, getTemplateById, cloneTemplate } from '@peacethinking/mediation-workflows';

// 8 templates: Simple, Standard, Advanced, Two-Party,
//              Coached, Human-Only, Dual-Mediator, Face-to-Face

const template = getTemplateById('template_standard');
const { steps, roles } = cloneTemplate(template);

| Template | Category | Key Feature | |---|---|---| | Simple | simple | Minimal, AI-only proposals, 1 voting round | | Standard | standard | + Emotional check-ins (flood + 12-emotion) | | Advanced | advanced | + Surveys, AI review, mediator gate, 3 rounds | | Two-Party | simple | No mediator, AI handles everything | | Coached | advanced | Coach + Trusted Ally roles | | Human-Only | advanced | No AI, mediator creates all proposals | | Dual-Mediator | advanced | AI + human mediator, combined proposals | | Face-to-Face | advanced | Live voice conversation with transcription |

Voting Engine

import { computeVoteStatistics, resolveConflicts } from '@peacethinking/mediation-workflows';

const result = computeVoteStatistics(options, totalParticipants);
// { optionStats, isComplete, hasConflicts }

if (result.hasConflicts) {
  const resolution = resolveConflicts(options);
  // Uses preference-rating algorithm (highest avg rating wins)
}

Emotional Check-in

import { assessFloodLevel, getCheckinRequirement } from '@peacethinking/mediation-workflows';

// Gottman-based flooding assessment
const flood = assessFloodLevel(8, 7, 'en');
// { level: 8, isFlooded: true, recommendation: "You are experiencing significant..." }

// Check if a check-in is required
const req = getCheckinRequirement(dialogueConfig, 'BEFORE_VIEWPOINTS');
// { isMandatory: true, isOptional: false, isAvailable: true }

Workflow Element Types

29 step types organized into 7 categories:

• Setup: Consent, Role Briefing, Guidelines, Invitation
• Understanding: Viewpoint Input, Additional Context, Ally Context, Coach Guidance, Live Conversation
• Check-ins: Flood Level, 12-Emotion Radar, Questionnaire
• Analysis: AI Review, AI Analysis, AI Reflection, AI Proposal, Human Proposal
• Review: Mediator Review, Coach Review, Proposal Review, Mediator Approval
• Decision: Voting, Conditional Acceptance, Finalization
• Flow: Wait

License

MIT