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.

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.

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):

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:

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.

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).

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).