Concordia Domain - Architecture

Architecture for the cooperative mediation and negotiation intelligence substrate (Phase 179). The contract, OpenAPI, protobuf, event, orchestrator, workbench, benchmark, and cross-domain library surfaces are implemented; the open item is production pilot deployment (§179.10.8).

Concordia is a cross-domain service layer rather than a single product silo. It coordinates contracts, private intake, preference learning, agreement search, safety review, settlement drafting, and execution across the domains that own the actual business, governance, community, creative, and agentic workflows. The domain is named for Concordia, the Roman goddess/personification of concord and agreement; service, package, route, API, and event identifiers use the concordia namespace.

Unlike most domains in the monorepo, Concordia does not own a standalone product or a single database table. Instead it acts as a shared mediation substrate: it provides the cross-domain scaffolding that other domains call when they need to help two or more parties reach mutually acceptable terms. Its contract package, orchestrator service, and adapter registry are the central coordination points; the domain-specific logic (procurement thresholds, governance quorum rules, escrow mechanics) continues to live in the owning domain.

Ownership Boundary#

Concordia owns the flow from case creation through settlement audit export, but deliberately delegates domain-specific logic to the owning domain rather than absorbing it. This boundary keeps Concordia's contract package stable and prevents procurement rules, governance quorum requirements, and escrow mechanics from colliding inside a single service.

Concordia owns:

• The shared cooperative bargaining flow from case creation through settlement audit export.
• services/concordia/orchestrator/ and testing/concordia/.
• The Oshun Concordia workbench route (/studio/concordia-workbench) and the Concordia adapter registry (@oshun/concordia-integration).
• Cross-domain Concordia events, benchmark scenarios, and release gates.

Concordia coordinates but does not replace:

• Nous model/search ownership.
• Iris conversational UX ownership.
• Themis governance and dispute ownership.
• Maat procurement and financial-control ownership.
• Kuanyin restorative and safety ownership.
• Aje settlement/escrow ownership.
• Contracts, OpenAPI, and Proto generated artifact ownership.
• Shared identity, authorization, audit, secrets, observability, and retention ownership.

Runtime Topology#

The diagram below shows the call paths that radiate out of the Concordia orchestrator. Each arrow represents a cross-domain dependency: the orchestrator calls into the owning domain rather than reimplementing the capability.

Oshun Concordia workbench / Iris Concordia agent / domain adapters
        |
        v
services/concordia/orchestrator
        |
        +--> Case, party, identity, authority, RBAC/ABAC checks (Shared)
        |
        +--> Private intake and co-mediation sessions (Iris)
        |
        +--> Mediation knowledge and precedent retrieval (Sophia)
        |
        +--> Preference inference and utility uncertainty (Nous)
        |
        +--> Agreement DSL validation (Contracts)
        |
        +--> Agreement search kernels (Nous)
        |
        +--> Review queues and oversight (Themis / Maat / Kuanyin / domain experts)
        |
        +--> Settlement execution (Aje escrow, off-chain documents, domain actions)
        |
        +--> Audit, consent, evidence, observability, and retention (Shared)

Layer Responsibilities#

The mediation flow is organized into ten conceptual layers. Each layer has a well-defined input contract and output contract so that, for example, the search layer can be swapped between kernels without touching the intake or explanation layers.

Confidentiality Architecture#

The most important architectural invariant in Concordia is that no private party field may ever reach an opposing party. This is enforced through physically separate prompt contexts, sealed memory stores, and a projection layer in @concordia/contracts that strips private fields before any cross-party serialization.

• Each party gets a physically separate prompt and memory context.
• Private fields use visibility labels and cannot serialize into shared views, opposing-party prompts, shared explanations, logs, traces, events, or generated agreements unless a contract-level consent path allows it.
• Per-party data keys and sealed stores protect private statements, evidence, BATNA estimates, reservation points, concessions, and emotional context.
• The orchestrator must maintain a consent ledger for collection, processing, model scoring, reviewer access, transcription, settlement export, training reuse, and smart-contract execution.
• All derived artifacts must keep lineage back to consent state and redact or quarantine when consent is withdrawn, subject to legal hold rules.

Agreement Search Architecture#

Agreement search is the computational heart of Concordia. Rather than asking parties to haggle back and forth, Concordia learns each party's preferences and then uses optimization kernels to find candidate agreements that maximize joint welfare. The six-step process below ensures that only safe, valid, and consented candidates ever reach parties for review.

1. Candidate terms are represented as typed AgreementDSL clauses.
2. Static validation rejects contradictory, impossible, unsafe, unlawful, unenforceable, or policy-blocked clauses before scoring.
3. Preference models score candidate families with uncertainty and abstention.
4. Search kernels explore candidate space while preserving redlines as hard constraints.
5. Shared explanations summarize tradeoffs without leaking confidential data.
6. Review queues validate high-risk or authority-bound outcomes before acceptance.

Domain Adapter Architecture#

Every domain that can host a Concordia case must declare an adapter so there is no unowned Concordia path. The adapter declaration acts as a contract between the domain and the Concordia orchestrator: it tells the orchestrator which cases are eligible, who must review them, and what the domain will do once a settlement is accepted.

Every domain adapter must declare:

• Eligible use-case classes.
• Required human-review thresholds.
• Domain templates and clause families.
• Data inputs, private inputs, and shared outputs.
• Execution permissions and settlement authority boundaries.
• Domain metrics and release gates.
• Whether training-data reuse is allowed, under what consent, and with which de-identification path.

Per §179.9.3.3 every domain listed in DOMAINS/README.md has an adapter record (template-only where a domain is not yet a first-class pilot) so there is no unowned Concordia path. The cross-domain integration modules live inside @concordia/contracts (src/maat-integration/, src/themis-integration/, src/kuanyin-integration/, src/aje-integration/, the per-domain dispute modules, and the agent-to-agent protocol).

Service Orchestrator#

The orchestrator is the runtime home of Concordia's coordination logic. It receives commands from the workbench and domain adapters, fans them out to worker queues, and drives the ConcordiaCase state machine from creation to executed settlement.

services/concordia/orchestrator/ (@concordia/orchestrator) covers:

• Case lifecycle commands.
• Party invitation and identity/authority verification.
• Private intake orchestration.
• Issue map and evidence room orchestration.
• Preference-query batch jobs.
• Search-run workers with queue backpressure.
• Candidate validation and drafting workers.
• Review routing, acceptance, execution, obligation monitoring, and audit export.

The §179.2.4.5 Fastify-versus-Python-FastAPI decision was resolved in favor of a Fastify (TypeScript) service, matching every existing gateway-style service in the monorepo; the rationale is recorded in the orchestrator README. The service wires up Docker, health checks (/health, /health/ready), OpenAPI export, service discovery, the worker runtime, an event bus with a backpressure scheduler, observability, and tenant configuration. Python and Rust remain the intended runtimes for preference-learning and CP-SAT/MILP/NSGA-II solver sidecars, which the orchestrator coordinates rather than hosts.

Safety Architecture#

Concordia handles cases ranging from low-stakes personal disputes to high-risk employment and custody matters. The safety architecture uses the declared use-case class to determine how much autonomy the system may exercise and when it must hand control to a qualified human.

• Use-case class determines whether AI-only brainstorming, mediator-assist, procurement negotiation, governance process, arbitration support, or legal review is allowed.
• Domestic abuse, custody, employment adverse action, medical, regulated financial, disability-rights, immigration, criminal, minors, and high-stakes rights-waiver contexts require refusal or qualified review.
• Coercion, collusion, manipulation, false evidence, hidden side payments, and bad-faith leverage signals trigger pause and escalation workflows.
• Reviewer capacity controls can block product launch or autonomous execution when qualified review is unavailable.
• Kill switches and feature flags must cover model routing, autonomous acceptance, smart-contract execution, search kernels, and domain adapters.

Integration Architecture#

Each major domain integration has a distinct architectural requirement that reflects the owning domain's rules. The boundary between Concordia and each partner domain is defined by what data crosses it and what decisions must remain inside the partner domain.

The boundary between Concordia and Maat exists because procurement approval thresholds, KYC status, and working-capital constraints are owned by Maat's financial-control model; Concordia must not make those decisions. Similarly, Themis owns the quorum and voting rules for governance disputes, so Concordia routes governance cases to Themis review rather than resolving them autonomously. Aje owns the on-chain escrow mechanics, so Concordia hands settlement hashes and milestone schedules to Aje rather than executing smart contracts directly.

Verification#

Concordia is covered by automated contract, unit, integration, Playwright, accessibility, security, authorization, consent, evidence, settlement-lifecycle, benchmark, and governance-review gates (TODOS/phase-179.md §179.10, with the §179.10.7 governance review recorded under docs/compliance/governance-reviews/). The one open completion criterion is the §179.10.8 production pilot deployment in Maat, Themis, Kuanyin, Iris, Aje, and Yemaya. No pilot may launch unless private-info leakage tests, calibrated preference uncertainty, safe refusal, human-review routing, audit replay, and fairness thresholds pass.

Source Coverage#

This architecture document was checked against TODOS/phase-179.md and the implemented code under libs/contracts/concordia/, services/concordia/, testing/concordia/, the cross-domain *concordia* libraries, and apps/v2/concordia-substrate/. It covers the service topology, contract boundaries, privacy architecture, search architecture, domain adapter requirements, orchestration layer, safety model, integration map, and verification gates.