# Concordia Domain - Technical Specifications

> Technical specifications for the cooperative mediation and negotiation
> intelligence substrate (Phase 179). Implemented surfaces are grounded in code
> paths; the single planned item (`179.10.8` pilot deployments) is grounded in
> the phase doc and labeled `(planned)`.

Concordia is the cooperative mediation and negotiation substrate introduced by
`TODOS/phase-179.md`. This document provides the technical specification for
every implemented artifact: schemas, API endpoints, streaming services, domain
events, search kernels, product surfaces, and evaluation harnesses. It is
intended for engineers integrating with Concordia from a partner domain or
building on top of its contract package.

The cross-domain contract, OpenAPI, protobuf, event, service-orchestrator,
workbench, benchmark, and cross-domain library surfaces listed below are
**implemented in the repository**. Every Phase 179 task checkbox is marked `[x]`
except `179.10.8` (production pilot deployments in Maat, Themis, Kuanyin, Iris,
Aje, and Yemaya), which is not locally actionable and is documented here as
`(planned)`.

This document distinguishes implemented artifacts (grounded in code paths) from
planned scope (grounded in `TODOS/phase-179.md`).

## Implemented Paths

The table below maps each functional surface to its repository path and
implementation state. Use this as the starting point when navigating to a
specific part of the Concordia implementation.

| Surface                  | Path                                                                         | State       |
| ------------------------ | ---------------------------------------------------------------------------- | ----------- |
| Contract schemas         | `libs/contracts/concordia/` (`@concordia/contracts`)                         | Implemented |
| Domain events            | `libs/contracts/src/events/concordia.ts`                                     | Implemented |
| OpenAPI spec             | `libs/openapi/src/specs/concordia/concordia-api.yaml`                        | Implemented |
| Generated OpenAPI client | `libs/openapi/src/generated/concordia.ts`                                    | Implemented |
| Protobuf streams         | `libs/proto/src/concordia/concordia.proto`                                   | Implemented |
| Service orchestrator     | `services/concordia/orchestrator/` (`@concordia/orchestrator`)               | Implemented |
| Benchmark / test harness | `testing/concordia/` (`@concordia/testing`)                                  | Implemented |
| Oshun workbench          | `apps/oshun/web/src/app/studio/concordia-workbench/`                         | Implemented |
| Workbench components     | `apps/oshun/web/src/components/studio/StudioConcordiaWorkbench*`             | Implemented |
| Iris assistant           | `libs/iris/concordia-assistant/`                                             | Implemented |
| Sophia knowledge         | `libs/sophia/concordia-knowledge/`                                           | Implemented |
| Kuanyin restorative      | `libs/kuanyin/concordia-restorative/`                                        | Implemented |
| Nous sealed memory       | `libs/nous/concordia-sealed-memory/`                                         | Implemented |
| Nous search kernels      | `libs/nous/agreement-search/`                                                | Implemented |
| Nous preference learning | `libs/nous/preference-inference/`                                            | Implemented |
| Nous bargaining session  | `libs/nous/cooperative-bargaining/`                                          | Implemented |
| Themis dispute routing   | `libs/themis/dispute-resolution/`                                            | Implemented |
| Maat negotiation         | `libs/maat/negotiation-intelligence/`                                        | Implemented |
| Aje settlement escrow    | `libs/aje/settlement-escrow/`                                                | Implemented |
| Oshun integration        | `libs/oshun/concordia-integration/`                                          | Implemented |
| V2 substrate composition | `apps/v2/concordia-substrate/` (`@v2/concordia-substrate`)                   | Implemented |
| Governance review        | `docs/compliance/governance-reviews/179.10.7-concordia-governance-review.md` | Implemented |
| System / model cards     | `docs/compliance/cards/concordia/`                                           | Implemented |
| Integration flow test    | `tests/integration/flows/concordia-mediation-lifecycle.integration.test.ts`  | Implemented |

The Phase 179 library layout names `apps/maat/negotiation-console/` as a planned
path; it does not exist as a separate app. Maat-facing procurement negotiation
is delivered through `libs/maat/negotiation-intelligence/` and the Maat
integration modules inside `@concordia/contracts`.

## V2 Substrate Composition

The V2 substrate is the first deployment surface that composes multiple
Concordia libraries into a single deployable unit. It is gated behind a feature
flag so that V2-specific behavior can be rolled out incrementally without
affecting the primary orchestrator service.

`@v2/concordia-substrate` (`apps/v2/concordia-substrate/`) is the first V2
deployment surface. `composeV2ConcordiaNousSubstrate` composes
`@nous/cooperative-bargaining`, `@nous/preference-inference`,
`@nous/agreement-search`, and `@nous/concordia-sealed-memory` with
`@iris/concordia-assistant`, `@oshun/concordia-integration`, and
`@kuanyin/concordia-restorative` for three dispute kinds: `anti-cheat-appeal`,
`tournament-result-dispute`, and `crew-conflict`. The composition produces a
consent-gated appellant/arbiter Iris dialogue scaffold, privacy-projected event
routing, sealed private-party artifacts, a Nash-genetic search summary, and a
Kuanyin restorative-preflight branch for high-impact moderation outcomes.
External launch exposure is gated through `@oshun/config`: the
`ENABLE_V2_CONCORDIA_SUBSTRATE` feature flag defaults disabled and the rollback
policy is `off-rollback-dispute-resolution-only`.

## Cross-Domain Package Map

Each cross-domain library lives in the owning domain's `libs/` directory and
exposes only the API surface that Concordia needs from that domain. The package
map below shows the full set of Concordia-related libraries across all domains.

| Domain  | Package / path                       | State       |
| ------- | ------------------------------------ | ----------- |
| Nous    | `libs/nous/cooperative-bargaining`   | Implemented |
| Nous    | `libs/nous/preference-inference`     | Implemented |
| Nous    | `libs/nous/agreement-search`         | Implemented |
| Nous    | `libs/nous/concordia-sealed-memory`  | Implemented |
| Iris    | `libs/iris/concordia-assistant`      | Implemented |
| Themis  | `libs/themis/dispute-resolution`     | Implemented |
| Maat    | `libs/maat/negotiation-intelligence` | Implemented |
| Kuanyin | `libs/kuanyin/concordia-restorative` | Implemented |
| Aje     | `libs/aje/settlement-escrow`         | Implemented |
| Sophia  | `libs/sophia/concordia-knowledge`    | Implemented |
| Oshun   | `libs/oshun/concordia-integration`   | Implemented |
| Config  | `@oshun/config` feature flags        | Implemented |

The Phase 179 doc lists each Maat / Themis / Aje library under different path
spellings (`libs/themis/dispute-resolution`,
`libs/maat/negotiation-intelligence`, `libs/aje/settlement-escrow`); those
exist. Most of the cross-domain modeling — Maat procurement, Themis governance,
Aje escrow, Kuanyin restorative — is also implemented directly inside
`@concordia/contracts` as integration-specific modules (see Integration Modules
below).

## Core Schemas

`@concordia/contracts` (`libs/contracts/concordia/src/index.ts`) is the
canonical contract package. It exports Zod schemas and pure helper functions
organized into roughly 89 module sections. The schemas below are the most
important ones for a new integrator to understand; they form the spine of the
case lifecycle.

### Case and Party Models

The case model (`src/case/case.ts`, Phase 179.2.1.1) exports:

- `ConcordiaCaseSchema`, `PartySchema`, `PartyRoleSchema`
- `IssueSchema`, `InterestSchema`, `NeedSchema`, `ConstraintSchema`
- `RedlineSchema`, `BATNASchema`, `ReservationPointSchema`
- `EvidenceItemSchema`, `PrivateStatementSchema`, `SharedStatementSchema`

The agreement and preference model (`src/agreement/agreement.ts`) exports
`AgreementTermSchema`, `AgreementCandidateSchema`, `UtilityModelSchema`,
`PreferenceQuerySchema`, `PairwisePreferenceSchema`, `FairnessMetricSchema`. The
search/settlement/review/execution module (`src/search/search.ts`) exports
`SearchRunSchema`, `SettlementDraftSchema`, `ReviewDecisionSchema`,
`ExecutionArtifactSchema`. Party authority (`src/authority/`) exports
`PartyAuthoritySchema`, `SettlementLimitSchema`, `AuthorityProofSchema`, plus
`selfAuthority`, `observerAuthority`, `authorityGapsBlockingAcceptance`,
`isAuthorityReadyForAcceptance`, and `evaluateSettlementLimit`.

### ConcordiaUseCaseClass

The use-case class is set at case creation and determines which AI capabilities
are allowed, which review thresholds apply, and whether the case is eligible for
autonomous acceptance. `src/use-case/use-case-class.ts` defines
`ConcordiaUseCaseClassSchema` (also mirrored in the events module and the
OpenAPI spec):

```typescript
type ConcordiaUseCaseClass =
  | 'low_stakes_personal'
  | 'community_restorative'
  | 'creative_collaboration'
  | 'commerce_negotiation'
  | 'supplier_procurement'
  | 'dao_governance'
  | 'platform_dispute'
  | 'employment_sensitive'
  | 'family_sensitive'
  | 'legal_claim'
  | 'regulated_financial'
  | 'medical_sensitive'
  | 'agent_to_agent_contract'
  | 'simulation_only';
```

The module also exports `USE_CASE_CLASS_PROFILES`, `getUseCaseClassProfile`,
`allowsAutonomousAcceptance`, and `isEligibleForConcordia` for risk-tier and
escalation routing.

### ConcordiaOperationalMode

The operational mode refines the use-case class at the level of the interaction
style: for example, a `dao_governance` case might run in `governance_process`
mode, while a `low_stakes_personal` case runs in `brainstorming` mode.
`src/banners/operational-mode.ts` defines the operational mode banner used at
case creation:

```typescript
type ConcordiaOperationalMode =
  | 'brainstorming'
  | 'facilitated_mediation'
  | 'procurement_negotiation'
  | 'governance_process'
  | 'arbitration_support'
  | 'legal_review_required'
  | 'restorative_circle'
  | 'agent_to_agent'
  | 'simulation_only';
```

The module also exports `chooseOperationalMode`, `getOperationalBannerProfile`,
and `DEFAULT_MODE_BY_USE_CASE_CLASS`.

### ConcordiaCase

`ConcordiaCaseSchema` is the root entity that drives the entire mediation
lifecycle. Its `status` field is the state machine that the orchestrator
advances as the case progresses. The `domainExtension` discriminated union
carries the domain-specific fields for the nine recognized integration kinds.

```typescript
interface ConcordiaCase {
  id: string;
  tenantId: string;
  title: string;
  description?: string;
  useCaseClass: ConcordiaUseCaseClass;
  operationalMode: ConcordiaOperationalMode; // mode-at-creation
  partyIds: readonly string[]; // min 1
  createdBy: string;
  createdAt: string; // RFC 3339
  updatedAt: string;
  closedAt?: string;
  status:
    | 'draft'
    | 'intake_in_progress'
    | 'intake_complete'
    | 'search_in_progress'
    | 'awaiting_review'
    | 'awaiting_acceptance'
    | 'accepted'
    | 'executed'
    | 'closed'
    | 'escalated'
    | 'withdrawn'
    | 'refused';
  pinnedModelVersions?: Record<string, string>; // §179.5.3.3
  pinnedOptimizerVersion?: string;
  domainExtension?: ConcordiaDomainExtension; // discriminated union
}
```

### Party and PartyAuthority

`PartySchema` carries the identity and authority information for a single
participant in a case. The `role` field determines which panels the party can
see in the workbench and which actions they can take. The `authority` field
encodes whether this participant can negotiate, accept, and bind an
organization, and whether they require human approval or counsel review before
doing so.

`PartySchema` carries `id`, `caseId`, `displayName`, `role` (`PartyRoleSchema`:
`individual`, `organization_representative`, `minor_with_guardian`,
`representative`, `counsel`, `mediator`, `reviewer`, `procurement_officer`,
`supplier_representative`, `dao_steward`, `dao_member`, `platform_operator`,
`community_member`, `autonomous_agent`), an optional `customRoleLabel`,
`principalId`, `languagePreferences` (BCP-47), `timezone`, an optional typed
`authority` (`PartyAuthoritySchema`), `joinedAt`, and `withdrawnAt`.

`PartyAuthoritySchema` carries the §179.2.1.3 authority booleans
(`canNegotiate`, `canAccept`, `canBindOrganization`, `requiresHumanApproval`,
`requiresCounselReview`, `requiresGuardianOrRepresentative`), a
`verificationState` (`unverified`, `self_attested`, `reviewer_verified`,
`documentary_verified`, `revoked`, `expired`), an array of `settlementLimit`
records, `proofs` (`AuthorityProofSchema`), and delegation/approval linkage
(`delegatedFromPrincipalId`, `approverPartyIds`, `counselPartyId`,
`guardianPartyId`).

### Privacy and Visibility Model

The privacy model is the enforcement layer that prevents any private party field
from reaching an opposing party or an unauthorized reviewer. Visibility labels
are applied at the field level and checked by the projection layer before any
serialization.

`src/privacy/privacy-scope.ts` defines `PrivacyScopeSchema`:

- **`PrivacyVisibilitySchema`** classifies who may see a field:
  `private_to_party`, `mediator_only`, `shared_with_all`, `reviewer_only`,
  `sealed_until_consent`.
- **`SensitivityLevelSchema`** (`none`, `low`, `moderate`, `high`, `critical`)
  is carried as `legalSensitivity` and `safetySensitivity` to drive reviewer
  escalation thresholds.
- **`RetentionPolicySchema`** (`inheritFromUseCase`, `retentionDaysOverride`,
  `legalHoldOverride`, `note`) and `PrivilegeClaimSchema` support per-field
  retention and legal-privilege declarations.
- Helper predicates `allowsCrossPartyDisclosure`, `allowsMediatorAccess`, and
  `allowsReviewerAccess` are exported for use by the orchestrator and adapters.
- Constants `DEFAULT_PRIVATE_PRIVACY`, `DEFAULT_SHARED_PRIVACY`, and
  `DEFAULT_REVIEWER_ONLY_PRIVACY` provide canonical defaults for new fields.

`src/projections/projections.ts` (Phase 179.2.1.5) implements the projection
layer that enforces the confidentiality model. The following functions strip
private fields before any cross-party serialization: `effectivePrivacy`,
`isVisibleToViewer`, `projectCaseForViewer`, `toSharedView`,
`toOpposingPartyPromptPayload`, `toMediatorView`, `toReviewerView`,
`toOwningPartyView`, keyed by a `ConcordiaViewerRole`. Contract tests
(`src/case/case.test.ts`, `src/projections/projections.test.ts`) assert no
private party field can serialize into a shared view or an opposing-party prompt
payload.

## Agreement DSL

The Agreement DSL is the formal language for expressing settlement terms. Rather
than storing agreements as free text, Concordia represents every clause as a
typed structure that can be validated, mutated by search kernels, and audited
for provenance. The DSL lives under `src/dsl/` (Phase 179.2.3) and is composed
of five implemented modules.

- **Core DSL** (`dsl.ts`, §179.2.3.1): `DslAgreementSchema`, `DslClauseSchema`,
  `DslVariableSchema`, `DslConstraintSchema`, `DslClauseDependencySchema`,
  `DslTemporalConditionSchema`, `DslSignatorySchema`,
  `DslEnforcementPathSchema`, `DslReviewRequirementSchema`,
  `DslClauseFamilySchema`, with helpers `collectVariableRefs`,
  `collectAgreementVariableRefs`, `gatherReviewerRoles`,
  `gatherEnforcementPathKinds`, `isAgreementBindable`.

- **Term families** (`term-families.ts`, §179.2.3.2): typed payload schemas for
  money, equity, royalties, deadlines, deliverables, service levels, licensing,
  exclusivity, territory, data rights, governance rights, voting thresholds,
  apology, confidentiality, non-disparagement, restitution, restorative actions,
  access revocation, buy-sell clauses, escrow release, and monitoring, plus
  `validatePayload`, `estimateMonetaryCommitment`,
  `termFamilyPresumesCounselReview`, and `narrowToFamily`.

- **Provenance** (`provenance.ts`, §179.2.3.3): `ClauseProvenanceSchema`,
  `ClauseProvenanceSourceSchema` (party interest, evidence item, legal/policy
  template, optimizer move, reviewer edit), `ClauseOptimizerMoveSchema`,
  `appendOptimizerMove`, `describeMoveChain`, `aggregateUtilityDelta`,
  `toSharedExplanationDigest`, `isProvenanceReviewerReady`. Provenance tracks
  every mutation a clause has passed through, allowing reviewers and auditors to
  understand why a clause looks the way it does.

- **Static validator** (`validator.ts`, §179.2.3.4): `validateAgreement`,
  `assertAgreementValid`, `diagnosticsByCategory`, `blockedFamiliesForUseCase`,
  `USE_CASE_BLOCKED_FAMILIES_TABLE`, producing categorized
  `DslValidationDiagnostic` records for impossible, contradictory, unlawful,
  unenforceable, unsafe, exploitative, vague, and policy-blocked clauses. The
  static validator runs before any preference scoring, so invalid candidates
  never reach the utility models.

- **Template registries** (`templates.ts`, §179.2.3.5): `ClauseTemplateSchema`,
  `ClauseTemplateRegistrySchema`, `SEEDED_CLAUSE_TEMPLATES`, `selectTemplates`,
  `requiredReviewsForTemplates`, `mandatoryReviewCategoriesForUseCase`, and
  `TemplateMandatoryReviewSchema` flagging legal, employment, family, regulated
  finance, healthcare, and minors-related clauses for mandatory human review.

## REST API Surface

The REST API is the primary integration point for the workbench and for domain
adapters that drive Concordia cases programmatically.
`libs/openapi/src/specs/concordia/concordia-api.yaml` is an OpenAPI 3.1.0 spec
(`Concordia API`, version `0.1.0`). All routes are mounted under a `/v1` prefix;
the generated client lives at `libs/openapi/src/generated/concordia.ts`. All
endpoints require `bearerAuth` (JWT).

| Endpoint                                          | Method | Operation               |
| ------------------------------------------------- | ------ | ----------------------- |
| `/v1/concordia/cases`                             | POST   | `createConcordiaCase`   |
| `/v1/concordia/cases/{caseId}/parties`            | POST   | `addConcordiaParty`     |
| `/v1/concordia/cases/{caseId}/intake`             | POST   | `submitConcordiaIntake` |
| `/v1/concordia/cases/{caseId}/issues`             | POST   | `createConcordiaIssue`  |
| `/v1/concordia/cases/{caseId}/preference-queries` | POST   | `createPreferenceQuery` |
| `/v1/concordia/cases/{caseId}/search-runs`        | POST   | `startSearchRun`        |
| `/v1/concordia/cases/{caseId}/pareto-frontier`    | GET    | `getParetoFrontier`     |
| `/v1/concordia/cases/{caseId}/drafts`             | POST   | `createSettlementDraft` |
| `/v1/concordia/cases/{caseId}/reviews`            | POST   | `createReviewDecision`  |
| `/v1/concordia/cases/{caseId}/execute`            | POST   | `executeSettlement`     |
| `/v1/concordia/audit/{caseId}`                    | GET    | `getCaseAudit`          |

Several response semantics deserve attention because they encode safety and
privacy invariants, not just business logic:

- `POST /cases` returns `409 BoundaryBlocked` (`BoundaryBlockedProblem` with
  `boundaryKind` and `requiredReviewerRole`) when a §179.1.2.2 hard boundary
  blocks the declared use case.
- `POST /intake` returns `403 MissingConsent` (`MissingConsentProblem` carrying
  `missingPurposes`) when a required consent purpose is not granted.
- `POST /search-runs` is asynchronous: it returns `202` with a `SearchRun`, and
  `409` if a run is already in progress.
- `GET /pareto-frontier` returns a viewer-role-scoped projection; private
  artifacts are excluded from the shared explanation layer.
- `GET /audit/{caseId}` defaults `redactPrivateFields=true`; only a token with
  `auditor_full_access` scope may set it `false`.

Errors use RFC 7807 `application/problem+json`. The `SearchKernel` enum in the
spec is `nash_genetic`, `nsga_ii`, `map_elites`, `mcts_lats`, `cp_sat`, `milp`,
`bayesian_optimization`, `psro`, `coalition_stability`. (The contract
`SearchRunSchema` uses the equivalent identifiers `nash_ga`, `cp_sat_milp`,
`coalition_search` for its own `kernels` field.)

## Protobuf and Streaming Surface

The protobuf services handle the real-time, streaming aspects of Concordia that
do not fit the request-response model of REST: live mediation sessions with
audio and transcript, real-time offer exchange, and long-running search progress
updates.

`libs/proto/src/concordia/concordia.proto` (`package oshun.concordia`, proto3)
defines three gRPC services.

**`ConcordiaSessionService`** handles live-session streaming. `StreamSession`
(bidirectional) carries `SessionStart`, `AudioFrame`, and `SessionCommand` from
the client and emits `TranscriptUpdate`, `SpeakerDiarizationUpdate`,
`CoMediatorSuggestion`, `SessionAck`, `SessionPrivacyNotice`, and
`SessionError`. `PauseSession` / `ResumeSession` support mid-session privacy
pauses. `CoMediatorSuggestion` carries an `InterventionKind` (reframe,
summarize, name interest, redirect focus, check understanding, brainstorm
options, emotional acknowledgment, cool-down break, safety escalation, propose
agreement test) and a socio-cognitive label.

**`ConcordiaNegotiationService`** handles real-time offer and counter exchange.
`StreamNegotiation` (bidirectional) handles `OfferMessage`, `CounterMessage`,
`WithdrawMessage`, `AcceptMessage`, and pings; emits `OfferAccepted`,
`OfferRejected`, `OfferExpired`, `CounterProposed`, `AgreementReached`, and
`NegotiationNotice`. `SubmitOffer` is the one-shot equivalent.

**`ConcordiaSearchService`** handles search-progress streaming.
`StreamSearchProgress` emits `SearchStarted`, `SearchIteration`,
`CandidateGenerated`, `FrontierSnapshot`, `SearchKernelMetric`,
`SearchCompleted`, `SearchFailed`, and `SearchCancelled`, with a
`resume_from_seq` reconnect cursor. `CancelSearch` aborts a run.

Every stream message carries a `viewer_role` / `visibility` field; services must
apply `@concordia/contracts` projections before emitting any message so private
artifacts never traverse opposing-party or shared streams. Backward-incompatible
stream changes are gated by protobuf compatibility checks (§179.2.4.3).

## Domain Events

Domain events are the mechanism by which Concordia notifies partner domains that
something significant has happened in a case. Downstream consumers — for
example, the Aje escrow service waiting for `concordia.settlement.accepted`, or
a Themis oversight reporter polling for `concordia.escalation.required` —
subscribe to these events rather than polling the REST API.

`libs/contracts/src/events/concordia.ts` defines twelve canonical event schemas
(source `concordia`), each built with `createEventSchema` and registered in
`ConcordiaEventSchemaRegistry`. Payloads carry only identifiers and viewer-safe
metadata; private party fields are never included. 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`
- `concordia.escalation.required`

The `concordia.escalation.required` payload deserves special attention because
it drives safety routing across multiple domains. It carries an escalation
`priority` (`p0`-`p3`), an enumerated `triggers` array (hard boundary, safety
flag, coercion, redline violation, authority gap, missing consent, privacy
breach, bias, unverified authority, hallucinated law, sanctions/KYC, regulated
financial, medical sensitive, child safety), and a `reviewerQueue` target.

## Preference and Utility Inference

Preference inference is the module that converts a party's pairwise comparisons
— "I prefer outcome A to outcome B" — into a calibrated utility model. That
model is then used by the search kernels to find candidates that maximize joint
welfare. The five estimators reflect different statistical assumptions; the
active learning module selects which comparisons to ask for next.

`@nous/preference-inference` (`libs/nous/preference-inference/`) implements
§179.3.2-179.3.3:

- **Pairwise prompts** (`pairwise-prompt.ts`): strict-JSON comparison prompt
  builders with `PairwiseComparisonResponseSchema`, citation to private intake
  snippets (`Citation`), and `parsePairwiseComparisonResponse`.

- **Five calibrated estimators**: Bradley-Terry (`bradley-terry.ts`, logistic
  link, Newton-Raphson with a Laplace posterior), Thurstone-Mosteller
  (`thurstone-mosteller.ts`, probit link), Plackett-Luce (`plackett-luce.ts`,
  full-ranking likelihood), Gaussian-process preference (`gaussian-process.ts`,
  Chu-Ghahramani 2005), and a neural utility ranker (`neural-ranker.ts`,
  feed-forward MLP with deep-ensemble uncertainty). All adapt to the contract
  `UtilityModel` via `toContractUtilityModel`.

- **Active learning** (`active-learning.ts`): selects comparison pairs that
  maximally reduce uncertainty near the Pareto frontier and party redlines,
  minimizing the number of questions a party must answer.

- **Stability probes** (`stability-probes.ts`, `prompt-perturbations.ts`,
  `calibration.ts`): test preference consistency across paraphrase variants,
  prompt-template variants, model-version variants, order effects, and
  adversarial framing; ECE and Brier calibration metrics.

- **Abstention** (`abstention-gate.ts`): incomparability and abstention states
  for low-confidence, unstable, refused, redline-blocked, and non-tradeable
  comparisons; abstained utilities are excluded from optimizer selection.

- **Hard constraints** (`hard-constraints.ts`): redlines and hard minimums
  modeled separately from soft preferences so that search kernels never propose
  candidates that cross a redline.

- **BATNA** (`batna-model.ts`, `batna-plausibility.ts`): walkaway utility with a
  confidence interval and a strategic-manipulation plausibility score.

- **Multi-attribute utility** (`multi-attribute-utility.ts`,
  `multi-attribute-inference.ts`): issue weights, diminishing returns,
  time-discounting, risk aversion, inequity aversion, relationship preservation.

- **Fairness** (`fairness-metrics.ts`, `fairness-profiles.ts`): Nash product,
  utilitarian sum, max-min, egalitarian welfare, Kalai-Smorodinsky proportional
  gains, envy-freeness, regret, inequality, burden symmetry, procedural dignity,
  plus cultural and domain fairness profiles.

The `@concordia/contracts` `UtilityModelSchema` is the contract surface for
posterior mean, credible interval, comparison count, and instability state.

## Search Kernels

The search kernels are the algorithms that explore the space of possible
agreements and identify candidates on the Pareto frontier. Different kernels are
suited to different case types: Nash genetic search works well for two-party
negotiations, CP-SAT handles discrete procurement terms, and coalition stability
search handles multi-party disputes.

`@nous/agreement-search` (`libs/nous/agreement-search/`) implements §179.4:

- **Kernel registry** (`kernel-registry.ts`): `SEARCH_KERNEL_REGISTRY`,
  `getKernelDescriptor`, `rankKernelsForCaseProfile` with cost/capability
  descriptors per kernel.

- **Candidate generation** (`candidate-generation.ts`,
  `proposal-decomposition.ts`): seed candidates from party proposals, mediator
  templates, domain playbooks, precedent agreements, policy constraints, and LLM
  brainstorm bundles; structured proposal decomposition borrows clauses across
  candidates.

- **Domain playbooks** (`domain-candidate-generators.ts`): specialized candidate
  generators for procurement, creative royalty, DAO governance, platform
  moderation appeal, marketplace dispute, cofounder equity, supplier service
  level, collaborative production, multiplayer guild governance, and
  agent-to-agent contract use cases.

- **Clause mutators** (`clause-mutators.ts`): sandboxed numeric perturbation,
  deadline shift, proportional split, installment schedule, equity vesting,
  royalty waterfall, scope narrowing, escalation ladder, audit right, and
  reversible trial period.

- **Candidate filter** (`candidate-filter.ts`): safety, legality, policy,
  feasibility, and enforceability gates before utility scoring. Candidates that
  fail these gates never reach the preference models.

- **Search kernels**: `nash-genetic.ts` (Nash-product genetic search with
  uncertainty-aware selection), `nsga-ii.ts` and `map-elites.ts`
  (multi-objective Pareto search), `mcts-lats.ts` (tree-search agreement
  search), `cp-sat.ts` (CP-SAT/MILP discrete search),
  `bayesian-optimization.ts`, `psro-opponent-model.ts`, `coalition-stability.ts`
  (core membership, blocking coalitions, Shapley attribution, bargaining sets,
  side payments), `ga-operators.ts`.

- **Explanations** (`pareto-explanations.ts`, `shared-neutral-explanation.ts`,
  `party-private-briefing.ts`): shared neutral explanations and party-specific
  private briefings with no cross-party leakage. Each explanation summarizes why
  a candidate scores well without exposing the opposing party's utility model.

- **Choice architecture** (`coercive-choice-audit.ts`, `workbench-controls.ts`):
  dark-pattern, countdown-pressure, hidden-authority, manipulated-anchor, and
  asymmetric-disclosure safeguards; "show more like this", "protect this term",
  and "human review" controls.

- **Anti-gaming** (`spec-gaming-audit.ts`): specification-gaming detection for
  candidates that score well but contain brittle, exploitative, vague, or
  one-sided clauses.

`@nous/cooperative-bargaining` (`libs/nous/cooperative-bargaining/`) provides
the `BargainingSession` lifecycle: `buildBargainingSession`, `advancePhase`,
`allStakeholdersCanAccept`, `stakeholdersBlockingAcceptance`.

## Identity, Authorization, and Privacy

Access control in Concordia operates at three levels: identity assurance (can
this party prove who they are?), RBAC/ABAC (what actions are they allowed to
take?), and negative authorization (what are they explicitly forbidden from
doing?). All three are implemented in `@concordia/contracts`.

`@concordia/contracts` implements the §179.2.5 access surface:

- **Identity** (`src/identity/`): `PartyIdentityVerificationSchema`,
  `IdentityAssuranceLevelSchema`, `SignatoryVerificationSchema`,
  `MINIMUM_IDENTITY_ASSURANCE_BY_USE_CASE`, `acceptanceReadinessGaps`,
  `isReadyToAccept`.

- **RBAC / ABAC** (`src/access/`): `ConcordiaRoleSchema`,
  `ConcordiaResourceKindSchema`, `ConcordiaActionSchema`, `evaluateAccess`,
  `listRoleActions`, `rolesGranting`, with party, mediator, reviewer, counsel,
  procurement officer, DAO steward, safety reviewer, and auditor roles under
  tenant and case isolation. `src/access/negative-authorization.test.ts` asserts
  negative authorization: no inference, listing, search, export, logging, or
  subscription of another party's private fields, another tenant's cases, or
  reviewer-only materials.

- **Conflict of interest** (`src/conflicts/`): `ConflictDisclosureSchema`,
  `evaluateAssignment`, `isProfessionalEligible`.

- **Throttling** (`src/throttling/`): `RateLimitPolicySchema`, token-bucket rate
  limiting, session controls, and `evaluateSuspiciousAccess` for invitations,
  evidence downloads, private-intake reads, and agreement exports.

Sealed memory and zero-retention routing live in
`@nous/concordia-sealed-memory`: `createSealedMemoryStore` (envelope encryption,
per-party data keys, KMS provider, audit sink for every read), and
`zero-retention-mode.ts` (`requiredRetentionMode`,
`useCaseRequiresZeroRetention`, `generateRetentionAttestation`,
`verifyAttestation`). `confidential-compute.ts` covers §179.5.1.4
confidential-compute exploration.

## Consent, Evidence, and Settlement

Consent, evidence custody, and settlement execution are three distinct lifecycle
concerns that share a common requirement: every action must be auditable and
reversible (within legal constraints). The modules below implement these
concerns inside `@concordia/contracts`.

- **Consent** (`src/consent/`, `src/consent-ledger/`): `ConsentPurposeSchema`
  covers the following consent purposes — private statement, evidence, BATNA
  estimate, reservation point, confidential concession, emotional context,
  settlement authority, meeting transcription, reviewer access, model scoring,
  training-data reuse, and settlement execution. The append-only consent ledger
  records every grant and revocation via `recordConsent`, `revokeConsent`,
  `extendConsent`, `withdrawParty`, and `expireOverdueGrants`.

- **Revocation** (`src/revocation/`): `planRevocation` stops future processing,
  quarantines derived utility models, notifies reviewers, and preserves
  legally-required audit records.

- **Evidence custody** (`src/evidence-custody/`): malware scan verdict, content
  hash, custody event chain, redaction state, `validateCustodyChain`,
  `detectTamper`, `admissibilityScore`, `isAdmissible`.

- **Redaction** (`src/redaction/`): per-channel detection and redaction of PII
  before content enters summaries, prompts, vector stores, logs, candidate
  clauses, shared explanations, or benchmark datasets.

- **Data-subject lifecycle** (`src/data-subject/`): `planExport`,
  `planDeletion`, `planLegalHold`, `planResidencyCheck`, `planRetentionSweep`,
  `statutoryDeadline`.

- **Settlement lifecycle** (`src/settlement-lifecycle/`): a state machine
  (`openDraft` → `updateObligation` → `rescindAgreement`) covering versioned
  redlines, counsel comments, e-signature / countersignature, document export,
  acceptance ceremony, amendment, rescission, default notice, remedy tracking,
  and obligation completion monitoring.

- **Financial controls** (`src/finance-controls/`): sanctions screening, KYC
  level, payment-rail policy, tax treatment, approval thresholds, invoice
  reconciliation, and currency exposure.

- **Feature flags** (`src/feature-flags/`): `killFlag`, `enableFlag`,
  `disableFlag`, `listActiveKills` for model routing, autonomous acceptance,
  smart-contract execution, search kernels, and domain adapters.

On-chain settlement is modeled by the Aje escrow integration module
(`src/aje-integration/`) and `AjeEscrowExtension` (escrow contract reference,
milestone release fractions, arbitration bond, agreement-hash anchoring,
challenge window). `@aje/settlement-escrow` (`libs/aje/settlement-escrow/`)
provides the escrow adapter.

## Integration Modules

`@concordia/contracts` carries cross-domain integration modules so that every
domain in `DOMAINS/README.md` has an owned Concordia path. Rather than each
domain having to write its own Concordia adapter from scratch, these modules
provide the domain-specific contract surface that the orchestrator and adapters
use when routing a case to that domain. The implemented modules are:

- **Maat**: procurement/Pactum agents, working capital, executive approvals, and
  procurement benchmark (§179.7.1).
- **Themis**: proposal mediation, governance compromise, dispute modules, Aje
  escrow, and arbitration backstops (§179.7.2).
- **Kuanyin**: restorative integration, safety-specific terms, Lilith/Aphrodite
  boundary negotiation, Tara wellness support, and restorative outcome metrics
  (§179.7.3).
- **Creative domains**: Yemaya production, Euterpe/Calliope music, Isis
  generation, Aja/Bellona/Neith/Maya/Hathor realtime/virtual-world, and Themis
  Universal Originality Shield disputes (§179.7.4).
- **Commerce and industry**: Aglaea/Freya commerce; Asase/Demeter/Hestia/
  Annapurna food-and-agriculture; Cybele/Seshat/Athena/Brigid/Saraswati
  industrial; Lakshmi/Aje regulated-finance; and Nyx/Metis/Mnemosyne/Nisaba/
  Kalika/Veritas research-and-education disputes (§179.7.5).
- **Agent-to-agent**: agent protocol, capability negotiation, policy-constrained
  autonomous acceptance, and agent economic-value scoring (§179.7.6).

The `domainExtension` field on `ConcordiaCase` is a discriminated union
(`src/domain-extensions/`) with nine kinds: `maat_procurement`,
`themis_governance`, `aje_escrow`, `kuanyin_restorative`, `yemaya_royalties`,
`euterpe_licensing`, `maya_guilds`, `lilith_creator_disputes`, and
`iris_personal_coordination`.

## Service Orchestrator

The service orchestrator is the runtime that coordinates all of the above. It
receives REST requests and domain events, fans work out to background workers,
and advances the `ConcordiaCase` state machine.

`services/concordia/orchestrator/` (`@concordia/orchestrator`) is a Fastify
(TypeScript) service. The §179.2.4.5 runtime decision was resolved in favor of
Fastify over Python FastAPI; the rationale (repo convention, contract alignment,
streaming-RPC homogeneity, Python concentrated in workers, Rust/Python solver
sidecars) is recorded in the service README.

- `src/app.ts` builds the Fastify instance with CORS, health routes, an OpenAPI
  route, and service discovery (`/.well-known/concordia-orchestrator`).
- `src/routes/`: `health.ts` (liveness `GET /health`, readiness
  `GET /health/ready` with an OpenAPI-spec availability check), `openapi.ts`,
  `service-discovery.ts`.
- `src/workers/` (§179.6.3.2): a `WorkerRuntime` with a retry policy and a
  job-queue source, plus the workers `intake-summarization`,
  `preference-comparison`, `search-runs`, `candidate-validation`,
  `template-matching`, and `settlement-drafting`.
- `src/event-bus/` (§179.6.3.3): an in-memory bus, an orchestrator bridge, and a
  `backpressure-scheduler` so search runs cannot starve user-facing services.
- `src/observability/` (§179.6.3.4): per-case traces, aggregates, and metrics.
- `src/tenant-config/` (§179.6.3.5): per-tenant disclaimers, eligible use cases,
  model routing, review thresholds, residency, and retention policy.

## Product Surfaces

The workbench is the primary operator interface for running a Concordia case. It
is mounted in the existing `apps/oshun/web` App Router at
`/studio/concordia-workbench`
(`apps/oshun/web/src/app/studio/concordia-workbench/`). Each route corresponds
to a stage of the `ConcordiaCase` status lifecycle:

- `concordia-workbench/page.tsx` — case list / creation.
- `cases/[caseId]/page.tsx` — case overview.
- `cases/[caseId]/parties` — party invitation and authority verification.
- `cases/[caseId]/intake` — private intake submission.
- `cases/[caseId]/issues` — issue map.
- `cases/[caseId]/evidence` — evidence room.
- `cases/[caseId]/preferences` — preference review and correction.
- `cases/[caseId]/frontier` — Pareto frontier comparison.
- `cases/[caseId]/drafts` — settlement drafting.
- `cases/[caseId]/review` — reviewer queue and decisions.
- `cases/[caseId]/execute` — settlement execution.
- `cases/[caseId]/audit` — audit export.

Workbench composition lives in
`apps/oshun/web/src/components/studio/StudioConcordiaWorkbenchRouteMap.ts`,
`StudioConcordiaWorkbenchWorkspace.tsx`, and
`StudioConcordiaWorkbenchAdapter.ts`. Workbench mediator, party, and
organization modes are modeled in `@concordia/contracts` (`src/mediator-mode/`,
`src/party-mode/`, `src/organization-mode/`) along with accessibility /
localization / low-bandwidth (`src/accessibility-l10n/`). The Iris Concordia
agent is `@iris/concordia-assistant` (intake flow, party-isolated context,
multi-device intake, meeting co-mediator, conversation-to-agreement, language
detection, safety pipeline, unsuitable-for-AI routing).

## Evaluation and Benchmarks

The evaluation harness exists to give the team objective evidence that Concordia
is producing fair, stable, and safe outcomes. The benchmark suites are diverse
enough to catch kernel regressions that only show up in specific use-case
classes.

`testing/concordia/` (`@concordia/testing`) exports shared fixtures
(`fixtureCase`, `fixtureParty`, `fixturePrivateStatement`, `fixtureRedline`,
`fixtureEvidence`, `fixtureSharedStatement`, `fixtureBundle`) and two benchmark
families:

- **`ALL_BENCHMARK_SCENARIOS`** — synthetic two-party, multi-party, procurement,
  legal-low-stakes, DAO, creative, restorative, and agent-to-agent suites with
  `runAllBenchmarks`.
- **`ALL_MEDIATOR_AI_SCENARIOS`** — Mediator.ai-style scenarios: cofounder
  equity, roommate chores, parenting-plan brainstorming, contractor payment,
  supplier terms, creative royalties, and marketplace refunds, with
  `runAllMediatorAiScenarios`.

`@concordia/contracts` carries the evaluation modules: ANAC / GeniusWeb / NegMAS
adapters (`src/anac-adapters/`), LLMediator / Robots-in-the-Middle intervention
evaluation (`src/mediator-intervention-evaluation/`), ProMediate proactive
mediator evaluation (`src/promediate-session-evaluation/`), outcome / subjective
/ domain / cost / safety metrics, adversarial party simulations
(`src/adversarial-simulations/`), sensitive-case refusal scenarios, clause
exploit tests, the baseline benchmark gate (`src/baseline-benchmark-gate/`,
§179.10.6), release gates (`src/release-gates/`), and internal leaderboards.
Phase D research modules — learned mediator policy, causal durability,
culturally-calibrated negotiation, self-play negotiation league — are also
present as contract modules.

`tests/integration/flows/concordia-mediation-lifecycle.integration.test.ts`
exercises the cross-domain mediation lifecycle end to end.

## Implementation Phases

`TODOS/phase-179.md` §179.9 sequences the work in four phases, all marked `[x]`:

- **Phase A — Foundation**: contracts, OpenAPI, protobuf, events, privacy views,
  private intake, issue map, agreement DSL, candidate generation, pairwise
  preference inference, Nash baseline, benchmark harness, privacy red teams,
  identity/authority, RBAC/ABAC, consent ledger, evidence custody, abstention.
- **Phase B — Surpass Mediator.ai**: multi-party / coalition / CP-SAT / MCTS /
  Bayesian / multi-objective kernels, formal clause validation, shared/private
  explanations, uncertainty-aware active learning, the mediator workbench, live
  co-mediator mode, review queues, procurement/DAO integrations, reviewer
  capacity, off-chain settlement lifecycle, kill switches,
  negative-authorization automation.
- **Phase C — Ecosystem Rollout**: first-pilot integrations for Maat, Themis,
  Kuanyin, Iris, Aje, Yemaya; remaining-domain adapters; agent-to-agent
  negotiation; the de-identified training-data flywheel.
- **Phase D — Bleeding-Edge SOTA**: confidential-compute preference scoring,
  learned mediator policies, causal durability models, cross-cultural and
  accessibility calibration, self-play negotiation leagues.

## Verification and Completion Criteria

`TODOS/phase-179.md` §179.10 lists fourteen completion criteria. Thirteen are
marked `[x]`: `pnpm contracts:check` coverage, unit tests, integration tests,
Playwright workbench coverage, privacy-leakage security tests, benchmark gates
over baselines on six domain suites, the §179.10.7 governance review
(`docs/compliance/governance-reviews/179.10.7-concordia-governance-review.md`),
Nx-graph repo-integration checks, authorization automation, consent/evidence
tests, accessibility automation, settlement-lifecycle tests, and training-data
gates.

The single open criterion is **`179.10.8` `(planned)`**: production pilot
deployments in Maat, Themis, Kuanyin, Iris, Aje, and Yemaya showing measurable
value without unresolved P0/P1 safety or privacy incidents. This is a deployment
milestone rather than a code task and remains unchecked.

## Source Coverage

This specification was written from the implemented code —
`@concordia/contracts` (`libs/contracts/concordia/src/`),
`libs/contracts/src/events/concordia.ts`,
`libs/openapi/src/specs/concordia/concordia-api.yaml`,
`libs/proto/src/concordia/concordia.proto`, `services/concordia/orchestrator/`,
`testing/concordia/`, the `concordia-workbench` route tree, the cross-domain
`libs/{nous,iris,sophia,kuanyin,themis,maat,aje,oshun}/*concordia*` and
`*negotiation*`/`*dispute*`/`*settlement*` libraries, and
`apps/v2/concordia-substrate/` — cross-checked against `TODOS/phase-179.md`.
Implemented surfaces are grounded in code paths; the single planned item
(`179.10.8` pilot deployments) is grounded in the phase doc and labeled
`(planned)`.