# Contracts — Systems Deep Dive

> The `libs/contracts/` area: eleven Nx libraries that own the **typed wire
> contracts** — Zod schemas, event payloads, and cross-domain boundary types —
> every Oshun service validates against. This page is the entity-catalog view of
> the area; the narrative architecture lives in the
> [Contracts domain space](../../docs/domains/contracts/deep-dive/architecture.html).

## What this area is

A "contract" here is a runtime-validated boundary type: a Zod schema (not just a
TypeScript `interface`) so a payload crossing a boundary is checked at the edge,
at run time, not merely at compile time. The `libs/contracts/` directory is not
one package but **eleven separate Nx libraries**. One — `@oshun/contracts` — is
the platform-wide V1 contract surface; the other ten are domain-scoped contract
packages that own a single domain's wire surface (Iris, Psyche, Concordia,
Freya, and the Brigid/Cybele/Saraswati/Annapurna/Athena business domains), plus
the `@maat/contracts` scaffold.

The hard architectural invariant across all eleven is **zero upstream Oshun
dependencies**: a contract package may depend on `zod`, but never on a domain's
business logic. Contracts sit at the bottom of the dependency graph so producer
and consumer can both import the same schema without either pulling in the
other's runtime — the property that lets a payload "validate identically on both
sides" of a boundary.

## How the area is shaped

Every domain-scoped contract library follows the same internal layout, so once
you have read one you can navigate them all:

- `api-schemas.ts` — request/response Zod schemas for the domain's REST surface;
- `events.ts` — the domain's event payload schemas (what it emits onto the bus);
- `cross-domain.ts` — the boundary types other domains consume to integrate;
- `integration.ts` — composed integration contracts and lifecycle types;
- `index.ts` — the barrel that re-exports the public surface;
- `contracts.test.ts` — schema round-trip / parse tests that keep the Zod
  definitions honest.

`@oshun/contracts` is larger and organised by concern (`common`, `events`, the
LLM-gateway contracts, per-domain surfaces) rather than by single domain — it is
the shared V1 spine the BFF treats as canonical. The relationship between the
two tiers, the 181-event taxonomy, and the BFF-canonical rule are covered in
depth on the
[Contracts domain architecture page](../../docs/domains/contracts/deep-dive/architecture.html);
this catalog focuses on what each individual node is and why it exists.

## How it fits the wider system

These libraries are consumed three ways. The **BFF and domain services** import
the request/response and event schemas to validate traffic at the edge. The
**`@oshun/openapi` tooling** reads the V3 and persistence contracts as canonical
Zod sources to generate OpenAPI specs and typed clients (see the
[OpenAPI domain](../../docs/domains/openapi/deep-dive/architecture.html)). And
**cross-domain integrations** import another domain's `cross-domain.ts` types
instead of re-declaring payload shapes, so a change to a boundary type is a
compile error on both sides rather than a silent drift. Walk the "used by" edges
on any node below to see exactly who depends on it.

## Entity reference

### @oshun/contracts

The platform-wide V1 contract spine (`libs/contracts/src`). Organised by concern
— `common`, `events`, LLM-gateway contracts, and the per-domain V1 surfaces —
and re-exported from a single barrel (`src/index.ts`). It owns the shared
contract envelope and the event taxonomy the BFF treats as canonical, and is the
most heavily consumed contract package in the monorepo. When a V1 domain needs a
wire type that crosses the BFF boundary, this is where it lives. See the
[Contracts domain space](../../docs/domains/contracts/deep-dive/architecture.html)
for the event registry and envelope details.

### @iris/contracts

Wire contracts for **Iris**, the AI-assistant domain (`libs/contracts/iris`):
conversation, assistant-invocation, and tool-call payload schemas. It exists so
the assistant's request/response surface is validated identically wherever Iris
is invoked — the BFF, the web shell, and the agent loop — without any of them
re-declaring the shapes. Its `description` field is authoritative: "API
contracts and schemas for Iris AI Assistant."

### @psyche/contracts

The contract surface for **Psyche** (`libs/contracts/psyche`; the Nx project is
named `psyche-contracts`, package `@psyche/contracts`). Psyche is the
personalization / behavioural-modelling substrate, and these schemas type the
signals and profile payloads it exchanges with consumers so personalization data
never crosses a boundary unvalidated. It is a `layer:contracts` node with no
upstream Oshun dependency, like the rest of the area.

### @concordia/contracts

Contracts for **Concordia**, the cooperative-mediation and negotiation domain
(`libs/contracts/concordia`) — "API contracts and schemas for Concordia
cooperative mediation and negotiation." It types the mediation-session and
negotiation-message payloads that Concordia's service and its counterparties
exchange. Concordia is a Phase-179 domain, and its OpenAPI surface is generated
from these schemas (the `concordia` spec in `@oshun/openapi`), so this package
is the single source of truth for that API.

### @freya/contracts

Shared Zod schemas for the **Freya** luxury-goods domain
(`libs/contracts/freya`) — "API contracts and Zod schemas for the Freya luxury
goods domain." Freya's engines are in-process and `Map`-backed today (see the
[Freya domain](../../docs/domains/freya/deep-dive/architecture.html)), but its
boundary types live here so that downstream consumers — chiefly Aglaea, the
styling domain — can read Freya's product, sizing, and provenance contracts
without importing Freya's business logic.

### @contracts/brigid

The Brigid business-domain contract surface (`libs/contracts/brigid`): the
standard `api-schemas.ts` / `events.ts` / `cross-domain.ts` / `integration.ts`
layout. It owns the wire types for Brigid's REST surface and the events it
emits, and the `cross-domain.ts` types other domains import to integrate with
it. It is paired with the
[Brigid domain space](../../docs/domains/brigid/deep-dive/architecture.html),
which documents the system the contracts describe.

### @contracts/cybele

Cybele's contract package (`libs/contracts/cybele`) — Cybele is the real-estate
/ physical-space domain, the counterpart to Freya's supply side. The library
carries Cybele's `api-schemas.ts`, `events.ts`, and cross-domain boundary types
so its spatial and property payloads validate at the edge. See the
[Cybele domain space](../../docs/domains/cybele/deep-dive/architecture.html).

### @contracts/saraswati

The Saraswati contract surface (`libs/contracts/saraswati`). Notably, its `src/`
is organised by _counterpart domain_ — `asase.ts`, `brigid.ts`, `cybele.ts`, and
so on — because Saraswati (the creative-authoring / "Stage" domain) integrates
with many domains and keeps each cross-domain contract in its own module. That
shape makes the boundary surface explicit: one file per domain it talks to.

### @contracts/annapurna

Annapurna's contract package (`libs/contracts/annapurna`): `api-schemas.ts`,
`events.ts`, a `graphql.ts` module (Annapurna exposes a GraphQL surface in
addition to REST), and the standard cross-domain types. It is the wire surface
for the Annapurna domain — see the
[Annapurna domain space](../../docs/domains/annapurna/deep-dive/architecture.html).

### @contracts/athena

Athena's contract library (`libs/contracts/athena`), with the same
`api-schemas.ts` / `events.ts` / `graphql.ts` shape as Annapurna. It types
Athena's REST and GraphQL payloads and the events it publishes, paired with the
[Athena domain space](../../docs/domains/athena/deep-dive/architecture.html).

### @maat/contracts

A **scaffold**, honestly labelled. `libs/contracts/maat` carries a
`project.json` (but, uniquely in this area, **no `package.json`**, so it is not
independently versioned) and a set of empty `.gitkeep` sub-directories
(`agents/`, `core/`, `finance/`, `intelligence/`, …) reserving the intended
structure for the Maat business-operations contracts. There is no implemented
schema here yet — it is a reserved slot in the catalog, not a working contract
surface, and is shown as such rather than overclaimed.

### @contracts/phoebe

Phase 181 contract surface for the Phoebe BCI/neuroscience/clinical platform
(`libs/contracts/phoebe/src`): zod schemas split by plane — `primitives`
(consent: `ConsentScopeSchema`/`ConsentRecordSchema`, `SeverityBand`), `neural`
(`NeuralModalitySchema`, measurement points), `clinical`
(`AssessmentResultSchema`), `experiment`, `knowledge`, and `uncertainty`.
Contracts-first: the `libs/phoebe/*` implementation packages consume these
schemas; nothing here executes.