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 catalog (12)#
The 12 tracked Nx projects in contracts, each a code-linked entity node — package, type, source path, declared targets, and its internal dependency graph (depends-on / used-by, resolved from the package manifests, §6/§8), read from the project graph. Grouped by architectural layer; walk the dependency links to travel the system. 12 of these carry an authored deep-dive (what / why / how it fits); the rest are generated scaffolds awaiting one.
contracts (7)#
API contracts and schemas for Concordia cooperative mediation and negotiation
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.
ConcordiaUseCaseClassSchema19CONCORDIA_USE_CASE_CLASSES19UseCaseRiskTierSchema19UseCaseReviewerSchema19UseCaseEscalationPolicySchema19UseCaseClassProfileSchema19USE_CASE_CLASS_PROFILES19getUseCaseClassProfile19allowsAutonomousAcceptance19isEligibleForConcordia19ConcordiaUseCaseClass19UseCaseRiskTier19UseCaseReviewer19UseCaseEscalationPolicy19 +2600 moreAnnapurna'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.
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.
API contracts and schemas for Iris AI Assistant
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."
ConversationIdSchema34MessageIdSchema34UserIdSchema34AgentIdSchema34MemoryIdSchema34Id34ConversationId34MessageId34UserId34AgentId34MemoryId34DateRangeSchema34Timestamp34DateRange34 +125 moreA 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.
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.
LivingSceneCinematographicTechniqueSchema60LivingSceneTechniqueIdSchema60LivingSceneTechniqueToneBandSchema60LivingScenePinnedTechniqueSchema60LivingSceneTechniqueCatalogVersionSchema60LivingSceneScoreSchema60LivingSceneSegmentSpecSchema60LivingSceneCueSpecSchema60LivingSceneRenderEnvelopeSchema60deepParseLivingSceneScore60NisabaAnnotationSchema87NisabaCitationSchema87NisabaConceptGraphEdgeSchema87NisabaConceptGraphNodeSchema87 +36 moreThe 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.
unclassified (5)#
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.
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.
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.
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.
API contracts and Zod schemas for the Freya luxury goods domain
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.