Eve library

Contracts — Systems Deep Dive

Guide

Revision 1

On this page

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.

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

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

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

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