# Concordia Domain - Features

> Cooperative mediation and negotiation intelligence substrate
> (`libs/contracts/concordia/`, `services/concordia/*`, `testing/concordia/*`,
> and cross-domain libraries; Phase 179).

Concordia is the cross-domain bargaining substrate for every Oshun workflow
where multiple people, organizations, communities, agents, or systems need to
reach acceptable terms. It models private preferences, searches the Pareto
frontier, explains tradeoffs, detects coercion and manipulation, routes
high-risk cases to qualified review, and can hand accepted agreements to
off-chain documents or on-chain settlement paths.

The real-world problem Concordia solves is that most online dispute resolution
(ODR) and negotiation tools either force parties to disclose sensitive positions
to a central system or rely on blunt positional bargaining. Concordia instead
uses interest-based mediation principles encoded in a formal preference model:
each party shares their private interests with a sealed context, and a search
kernel finds candidates that respect both parties' redlines while maximizing
joint welfare. This means parties can reach better outcomes without having to
reveal their reservation price or BATNA to the other side.

The domain name follows the ecosystem's goddess naming pattern: Concordia is the
Roman goddess/personification of concord, agreement, and social harmony.
Implementation roots, route names, API paths, event prefixes, and contract
identifiers use `concordia`; plain-language feature descriptions still use
mediation and negotiation where those are the actual practices.

## Current Status

Phase 179 introduced the Concordia substrate. The contract, OpenAPI, protobuf,
event, orchestrator, workbench, benchmark, and cross-domain library surfaces are
fully implemented in the repository. Every Phase 179 task checkbox is marked
`[x]` except production pilot deployment (§179.10.8), which is a deployment
milestone rather than a code task.

- Contract package: `libs/contracts/concordia/` (`@concordia/contracts`).
- Service: `services/concordia/orchestrator/` (`@concordia/orchestrator`,
  Fastify).
- Test harness: `testing/concordia/` (`@concordia/testing`).
- User surface: `apps/oshun/web/src/app/studio/concordia-workbench/`.
- V2 deployment: `apps/v2/concordia-substrate/` (`@v2/concordia-substrate`),
  external exposure gated by the `ENABLE_V2_CONCORDIA_SUBSTRATE` flag (default
  disabled).

## Primary Owning Domains

Concordia is a coordination layer, not a standalone domain. The table below maps
each partner domain to its specific responsibility inside Phase 179. Concordia
owns the shared flow; these partner domains own the decision logic, data models,
and execution mechanics within their area.

| Domain    | Responsibility inside Phase 179                                                                                   |
| --------- | ----------------------------------------------------------------------------------------------------------------- |
| Nous      | Preference inference, agreement search, bargaining optimization, evaluation, self-play, learned mediator policies |
| Iris      | Conversational mediation, party-isolated intake, multi-device facilitation, meeting co-mediator mode              |
| Themis    | Governance dispute resolution, DAO proposal compromise, appeals, originality disputes, oversight                  |
| Maat      | Procurement negotiation, approval gates, finance controls, board-level automation oversight                       |
| Kuanyin   | Restorative mediation, coercion and safety detection, sensitive-case routing, community repair                    |
| Aje       | Escrow, settlement anchoring, challenge windows, smart-contract execution                                         |
| Contracts | Canonical Concordia schemas, privacy views, agreement DSL contracts                                               |
| OpenAPI   | REST API specs and generated clients                                                                              |
| Proto     | Streaming RPCs for live sessions and search progress                                                              |
| Sophia    | Mediation knowledge, precedent retrieval, policy/legal template grounding                                         |
| Oshun     | Workbench, shell integration, domain adapter registry                                                             |
| Shared    | Identity, RBAC/ABAC, audit, consent, retention, observability, queues, security                                   |

## Product Boundary

Concordia must support a wide range of dispute and negotiation contexts, from
informal personal coordination to formal procurement negotiations. The list
below defines the in-scope use-case classes that the system is designed to
handle.

Concordia must support:

- Low-stakes personal coordination and conflict brainstorming.
- Community restorative processes.
- Creative collaboration agreements.
- Commerce, marketplace, supplier, and procurement negotiations.
- DAO, corporate, community, and platform-governance disputes.
- Platform moderation appeals and restorative safety terms.
- Creative royalties, credits, licensing, delivery acceptance, and IP disputes.
- Agent-to-agent contracts over tasks, compute, data, tools, deadlines, and
  quality.
- Simulation-only negotiation research and benchmark runs.

Concordia must not produce binding AI-only outcomes for legal claims, employment
adverse actions, custody, domestic violence or coercive control, medical or
disability-rights settlements, regulated financial suitability, or high-stakes
rights waivers. Those cases require explicit qualified human review,
counsel/compliance routing, or refusal.

## Core Feature Families

### Research and Risk Classification

Before Concordia can be deployed in a new use-case class, it must demonstrate
awareness of the competitive and regulatory landscape. This feature family
provides the research baseline and the classification logic that governs which
AI capabilities are allowed for each case type.

- Dated competitive audit of Mediator.ai, legal ODR products, Pactum/Nibble
  procurement products, Kleros-style arbitration, and mediation-assist tooling.
- Source matrix separating commercial claims, academic evidence, standards,
  regulations, benchmarks, and case studies.
- Gap analysis for multi-party support, formal DSLs, privacy isolation,
  uncertainty-calibrated utility models, smart-contract execution, governance
  appeals, procurement metrics, and Oshun integrations.
- Research refresh gate before each pilot.
- Use-case classification, jurisdiction/risk banners, non-legal-advice posture,
  informed consent, and reviewer escalation policy.
- UNCITRAL ODR, EU AI Act, and NIST AI RMF mapping into engineering controls.

### Cross-Domain Contracts

The contract package is the single source of truth for every data structure that
flows through a Concordia case. All other layers — the orchestrator, the
workbench, the search kernels, and the domain adapters — depend on these schemas
rather than defining their own.

The contract package defines the following canonical schemas:

- Case and party models: `ConcordiaCase`, `Party`, `Issue`, `Interest`, `Need`,
  `Constraint`, `Redline`, `BATNA`, `ReservationPoint`, `EvidenceItem`,
  `PrivateStatement`, and `SharedStatement`.
- Search and settlement models: `AgreementCandidate`, `AgreementTerm`,
  `UtilityModel`, `PreferenceQuery`, `PairwisePreference`, `FairnessMetric`,
  `SearchRun`, `SettlementDraft`, `ReviewDecision`, and `ExecutionArtifact`.
- Privacy visibility states: `private_to_party`, `mediator_only`,
  `shared_with_all`, `reviewer_only`, and `sealed_until_consent`.
- Authority fields for negotiation, acceptance, organizational binding, counsel
  review, guardians/representatives, and settlement limits.
- OpenAPI endpoints, protobuf streams, event names, generated clients, and
  codegen drift checks.
- Agreement DSL with typed clauses, variables, constraints, dependencies,
  temporal conditions, signatories, enforcement paths, review requirements, and
  clause-level provenance.

### API and Events

The REST surface and the event bus are the two integration points that domain
adapters and the workbench use to interact with the Concordia orchestrator. The
`concordia-api.yaml` OpenAPI 3.1.0 spec defines the REST surface for the case
lifecycle. All routes are mounted under a `/v1` prefix and require a JWT bearer
token; each endpoint documents authorization, visibility, retention, consent,
audit, idempotency, and reviewer-gate behavior.

| Endpoint                                           | Purpose                                                    |
| -------------------------------------------------- | ---------------------------------------------------------- |
| `POST /v1/concordia/cases`                         | Create a case with its use-case class and operational mode |
| `POST /v1/concordia/cases/{id}/parties`            | Add a party with role, authority, and verification status  |
| `POST /v1/concordia/cases/{id}/intake`             | Submit a party's private intake                            |
| `POST /v1/concordia/cases/{id}/issues`             | Record an issue on the issue map                           |
| `POST /v1/concordia/cases/{id}/preference-queries` | Issue a pairwise preference comparison                     |
| `POST /v1/concordia/cases/{id}/search-runs`        | Launch an agreement search run (async, returns `202`)      |
| `GET /v1/concordia/cases/{id}/pareto-frontier`     | Retrieve the current Pareto frontier of candidates         |
| `POST /v1/concordia/cases/{id}/drafts`             | Generate a settlement draft from a candidate               |
| `POST /v1/concordia/cases/{id}/reviews`            | Record a reviewer decision                                 |
| `POST /v1/concordia/cases/{id}/execute`            | Execute an accepted settlement                             |
| `GET /v1/concordia/audit/{id}`                     | Retrieve the case audit record                             |

Concordia publishes twelve domain events that downstream services and adapters
subscribe to. An event never exposes a private party field unless the schema
explicitly marks the field as shared and the consent ledger records sharing
consent. The twelve events are: `concordia.case.created`,
`concordia.party.joined`, `concordia.intake.completed`,
`concordia.issue.identified`, `concordia.preference.updated`,
`concordia.offer.generated`, `concordia.offer.compared`,
`concordia.search.completed`, `concordia.draft.reviewed`,
`concordia.settlement.accepted`, `concordia.execution.completed`, and
`concordia.escalation.required`.

### Private Intake and Preference Learning

Intake is the phase where each party privately tells the system their interests,
redlines, and constraints. Keeping intake strictly party-isolated is what allows
Concordia to model each party's true preferences rather than their stated
negotiating position.

- Party-isolated Iris intake for facts, interests, needs, outcomes, redlines,
  emotions, relationship context, evidence, BATNA, reservation points, and
  authority.
- Trauma-aware, coercion-aware, multilingual intake with completeness scoring.
- Party review screens to correct inferred priorities before search.
- Pairwise comparison engine with strict JSON outputs, citation to private
  snippets, and uncertainty.
- Bradley-Terry, Thurstone-Mosteller, Plackett-Luce, Gaussian-process, and
  neural utility-ranking models.
- Active learning for comparison pairs near the Pareto frontier.
- Preference stability tests across paraphrases, prompt templates, model
  versions, order effects, and adversarial framing.
- Abstention and incomparability states for low-confidence, refused, redline, or
  non-tradeable comparisons.

### Agreement Generation and Search

Once the system has a calibrated utility model for each party, it uses
algorithmic search to find candidate agreements. The search layer combines
domain-specific playbooks with formal optimization kernels so that candidates
respect real-world constraints (e.g., procurement budget limits, royalty
waterfall structures) while maximizing joint welfare.

- Candidate generation from party proposals, mediator templates, domain
  playbooks, precedent agreements, policy constraints, and LLM brainstormed
  tradeoff bundles.
- Clause mutators in a sandboxed DSL for numeric perturbation, deadlines,
  splits, schedules, vesting, royalty waterfalls, scope, audit rights, and trial
  periods.
- Domain candidate generators for procurement, creative royalties, DAO
  governance, moderation appeals, marketplace disputes, cofounder equity,
  supplier SLAs, production collaboration, multiplayer guild governance, and
  agent-to-agent contracts.
- Nash-product genetic search, NSGA-II/MAP-Elites multi-objective search, MCTS
  and LATS agreement search, CP-SAT/MILP discrete search, Bayesian optimization,
  PSRO/opponent-model search, and multi-party coalition stability.
- Shared and private explanations that preserve confidentiality.
- Choice-architecture safeguards against dark patterns, countdown pressure,
  hidden authority, manipulated anchors, and asymmetric disclosure.

### Safety, Privacy, Security, and Oversight

Because Concordia handles sensitive personal, legal, and financial information,
its safety and privacy model is layered rather than bolt-on. Physical separation
of prompt contexts is the foundation; everything else — consent ledgers, sealed
stores, reviewer queues, kill switches — reinforces that foundation.

- Physically separate prompt contexts per party.
- Sealed memory stores, envelope encryption, per-party data keys, HSM/KMS
  integration, and read audit logs.
- Zero-retention local-model mode for privileged or air-gapped mediation.
- Confidential-compute exploration for sensitive utility scoring.
- Privacy red-team tests for prompt injection, tool exfiltration, summary
  leakage, side channels, and shared explanation leakage.
- BATNA plausibility, inconsistent-statement detection, specification-gaming
  detection, collusion/coercion detection, and cooling-off confirmation.
- Human mediator, counsel, compliance, DAO steward, procurement officer, safety
  reviewer, and domain-expert queues.
- Override, pause, reopen, appeal, nullification, incident reporting, model
  version pinning, and optimizer version pinning.
- Consent ledger, revocation, withdrawal, evidence custody, malware scanning,
  redaction, minimization, data export, deletion, legal hold, residency, and
  retention workflows.
- Reviewer capacity operations, off-chain settlement lifecycle, kill switches,
  sanctions/KYC, payment controls, and training-data governance.

### Product Surfaces

Concordia exposes its capabilities through four distinct product surfaces, each
designed for a different user role.

The **Oshun Concordia workbench** is the case operator surface: a user advances
a case left-to-right through its `ConcordiaCase` status (`draft` to `intake` to
`preference_modeling` to `searching` to `review` to `accepted` to `executed`),
and each panel is gated to that user's role so a party never sees a
reviewer-only or opposing-party panel. The workbench supports case creation,
party invitation, private intake, issue maps, evidence room, preference review,
frontier comparison, settlement drafting, review routing, and audit export.

**Mediator mode** gives a professional mediator a live view of the session: a
live transcript, agreement-point tracker, talk-balance metrics, suggested
reframes, caucus notes, offer ladder, and preparation reports.

**Party mode** is the isolated context a party works in. The private statement
editor and inferred-interest correction screen let a party fix what the
preference model concluded before search runs. The candidate comparison shows
only the shared explanation of a candidate, never another party's private
utility. Party mode includes a private statement editor, inferred-interest
correction, redline controls, candidate comparison, mediator questions, and
acceptance confirmation.

**Organization mode** is for procurement and governance participants. An
organization participant cannot accept past their `Party.settlementLimit`, and a
candidate that breaches a budget constraint or policy bundle is blocked from
acceptance until it routes through the approval chain. Organization mode exposes
settlement authority, approval chain, budget constraints, policy bundles,
signatory status, and execution integration.

The **Iris Concordia agent** is the conversational entry point for cases that
never need the full workbench. It runs each party's intake as a separate
device-isolated conversation, co-mediates a live meeting, and routes a case to
qualified human support the moment it detects a non-low-stakes signal. It covers
low-stakes coordination, two-device private intake, meeting co-mediation,
structured-agreement drafting, and professional support routing.

Behind all of these surfaces, **service orchestrator workers** handle the
long-running async work: intake summarization, preference comparison, search
runs, candidate validation, template matching, settlement drafting, and audit
export.

### Ecosystem Integration

Concordia integrates with every major domain in the Oshun ecosystem so that any
workflow involving negotiation or dispute resolution can use the shared
substrate rather than building a bespoke solution. The integrations are grouped
by domain below.

- **Maat**: procurement, finance, supply chain, working capital, supplier
  scoring, and executive approval.
- **Themis**: governance proposal lifecycle, dispute modules, appeals,
  compromise search, and periodic oversight.
- **Aje**: smart-contract escrow, deposits, milestones, refunds, royalties,
  arbitration bonds, challenge windows, and agreement-hash anchoring.
- **Kuanyin**: restorative circles, safety terms, moderation appeals, performer
  and creator protection, recurrence measurement, and community health metrics.
- **Lilith, Tara, and Aphrodite**: low-risk boundary support with strict consent
  and safety routing.
- **Yemaya, Euterpe, Calliope, Isis, Aja, Bellona, Neith, Maya, and Hathor**:
  creative production, IP, marketplace, mod, guild, and canon disputes.
- **Aglaea, Freya, Asase, Demeter, Hestia, Annapurna, Cybele, Seshat, Athena,
  Brigid, Saraswati, Lakshmi, Nyx, Metis, Mnemosyne, Nisaba, Kalika, Veritas,
  and Psyche**: domain adapters for commerce, food-and-agriculture, industrial,
  regulated finance, and research-and-education contexts.
- **Agent-to-agent**: Iris/Nous/Maat agent-to-agent negotiation for tools,
  compute, data sharing, budgets, deadlines, and expected quality.

### Evaluation and Release Gates

Before any use-case class can go to production, it must pass a set of automated
release gates designed to catch privacy leakage, preference miscalibration,
unsafe refusal failures, and fairness problems.

The evaluation infrastructure includes:

- Synthetic benchmark suites for two-party, multi-party, procurement,
  legal-low-stakes, DAO, creative, restorative, and agent-to-agent negotiation.
- Mediator.ai-style scenarios, ANAC/GeniusWeb/NegMAS adapters,
  LLMediator/Robots-in-the-Middle intervention evaluation, and ProMediate-style
  proactive mediator evaluation.
- Metrics for agreement rate, Pareto efficiency, Nash product, Kalai-Smorodinsky
  distance, welfare, envy, regret, diversity, stability, perceived fairness,
  dignity, transparency, relationship preservation, procurement savings,
  supplier satisfaction, safety, cost, and latency.
- Red teams for false BATNA, false evidence, manipulation, prompt injection,
  private-info fishing, side deals, collusion, delay tactics, clause exploits,
  sensitive-case refusals, and bad-faith leverage seeking.
- Release gates for private-info isolation, calibrated uncertainty, preference
  stability, safe refusal, human-review routing, audit reproducibility, fairness
  thresholds, authorization denial, consent/evidence lifecycle, accessibility,
  settlement lifecycle, and training-data governance.

## Implementation Sequence

`TODOS/phase-179.md` §179.9 sequences the work in four phases. All four are
marked complete (`[x]`); the only open completion criterion across the phase is
§179.10.8 production pilot deployment.

- **Phase A — Foundation**: contracts, generated clients, private intake, issue
  map, agreement DSL, preference inference, Nash baseline, benchmark harness,
  privacy tests, identity, authority, RBAC/ABAC, consent, evidence custody,
  abstention.
- **Phase B — Surpass Mediator.ai**: multi-party and advanced search, formal
  clause validation, workbench, review queues, procurement/DAO integrations,
  reviewer operations, kill switches, settlement lifecycle,
  negative-authorization automation.
- **Phase C — Ecosystem Rollout**: first-pilot integrations for Maat, Themis,
  Kuanyin, Iris, Aje, Yemaya, and adapters for every remaining domain.
- **Phase D — Bleeding-Edge SOTA**: confidential compute, learned mediator
  policies, causal durability models, cross-cultural and accessibility
  calibration, self-play negotiation leagues.

## Source Coverage

This file was checked against `TODOS/phase-179.md` and the implemented code
under `libs/contracts/concordia/`, `libs/contracts/src/events/concordia.ts`,
`libs/openapi/src/specs/concordia/`, `libs/proto/src/concordia/`,
`services/concordia/`, `testing/concordia/`, the `concordia-workbench` routes,
and the cross-domain `*concordia*` libraries. It captures every Phase 179
capability family, primary owner, code path, integration target, safety
boundary, evaluation family, and release gate at the domain-feature level.
Task-level checkboxes remain in `TODOS/phase-179.md`.