# Contracts Domain — Features

> **`@oshun/contracts`** is the shared contract library for the Oshun platform.
> It defines the canonical data schemas, the event envelope, the per-domain
> event payloads, and the Zod runtime-validation utilities that keep
> cross-domain communication type-safe. Every domain that emits or consumes
> events, or shares an entity type across a service boundary, imports from here
> rather than defining its own equivalent. Without a contracts library, each
> domain invents a slightly different `User`, `Asset`, or event envelope, and
> integrating domains becomes a mapping exercise instead of a direct import. The
> library has two primary subpaths — `@oshun/contracts/common` for entity
> schemas and `@oshun/contracts/events` for the event envelope and domain event
> types — plus additional per-domain subpaths (`llm`, `aja`, `arete`, `tara`,
> `nyx`, `metis`, `nisaba`, `veritas`, `v3`, `tts`).

The directory `libs/contracts/` also hosts several **separate** contract
libraries — `@iris/contracts`, `@psyche/contracts`, `@concordia/contracts`,
`@freya/contracts`, `@contracts/brigid`, `@contracts/cybele`,
`@contracts/saraswati`, and the scaffold `@maat/contracts` — described in the
final section.

---

## Common Data Schemas (`@oshun/contracts/common`)

When multiple domains reference the same concept — a User, an Asset, a Project —
they import the canonical type from here rather than each defining their own.
This ensures that serialization round-trips produce the same shape everywhere,
and that a schema change in one place propagates automatically to all consumers.
Every entity is defined as a Zod schema; the TypeScript type is `z.infer`-ed
from it, so compile-time types and runtime validators are always in sync.

### Core Entities

These are the most widely-shared entity types in the platform. Most domain API
handlers, database adapters, and event payloads reference at least one of them.

- **User** — Canonical user record. The full `UserSchema` carries `id` (UUID),
  `email`, nullable `username`, `firstName`, `lastName`, `displayName`, nullable
  `bio`/`avatarUrl`, a `role` (`user`/`creator`/`admin`/`super_admin`), a
  `status` (`pending`/`active`/`suspended`/`deleted`), `emailVerified`, contact
  and profile fields, `lastLoginAt`, and `createdAt`/`updatedAt`.
  `UserSummarySchema` is the minimal embeddable form (`id`, `displayName`,
  `avatarUrl`); `UserProfileSchema` is the public profile view. Companion
  schemas cover preferences, stats, activity, and notifications.
- **Asset** — Shared asset definition. `AssetSchema` carries a UUID `id`, name,
  filename, an asset-type enum (`image`, `video`, `audio`, `model_3d`,
  `document`, `script`, `font`, `texture`, `material`, `animation`, `archive`,
  `other`), a status enum, `sizeBytes`, `mimeType`, storage `url`, thumbnails,
  type-specific metadata, tags, version info, project/folder references, and —
  notably — optional `license` (`AssetLicenseSchema`) and `provenance`
  (`AssetProvenanceSchema`, including AI-generation details and a verification
  status). Used wherever generated content or uploads cross domain boundaries.
- **Project** — Cross-domain project reference. `ProjectSchema` carries a UUID
  `id`, name, slug, a project-type enum (`film`, `game`, `animation`,
  `commercial`, …), status, visibility, thumbnails, tags, `ProjectSettings`,
  owner, organization, member/asset counts, and storage usage. Companion schemas
  cover members, invitations, comments (including spatial comment positions),
  and project activity.
- **Persona** — AI persona definition shared across interaction domains. A large
  schema capturing role, lifecycle stage, approval status, supported modalities
  (`text`/`voice`/`avatar`/`video`), capabilities, a Big-Five personality model,
  a tone profile, disclosure rules, grounding rules, prompt templates,
  escalation triggers/targets, and content links.
- **Passage** — Textual content block for scholarship. A passage carries text
  (with a format and reference scheme), provenance, translations, parallels,
  commentary, and annotations — shared across the contemplative-knowledge
  domains.
- **Source** — Citation and source reference type. Covers source type,
  credibility tier (`high`/`medium`/`low`/`unknown`), contributors, partial
  dates, container, license, provenance, versions, formatted citations, and
  concept links.

### AI and Knowledge Entities

These entities are shared across the knowledge-layer domains (Sophia, Nisaba,
Metis, Veritas) and are referenced in AI-pipeline workflows throughout the
platform.

- **Concept** — Knowledge concept node. `ConceptSchema` carries a UUID `id`,
  slug, `name`, summary, a `category` string, a `complexity` level
  (`basic`/`intermediate`/`advanced`), tags, and arrays of typed concept
  relationships and concept links.
- **Notebook** — Research notebook entity. Aggregates notebook items, sections,
  and collaborators into a named research collection, and links to
  grounded-answer, grounded-report, evidence-pack, source-set, and
  citation-trail IDs.
- **ModelCard** — AI model metadata: model type/format, source type, content
  rating, a safety class (`safe`/`sensitive`/`restricted`/`blocked`), review
  state, promotion decision, creator info, compute/carbon info, fairness
  metrics, bias info, and citations.
- **ModelVersion** — Versioned model artifact: version status, format, engine,
  provider, deployment environment (`preview`/`staging`/`production`), file
  roles, scan status, deployment health, compatibility state, change type, and
  precision.

### Compliance and Safety

Consent and audit are treated as first-class cross-domain concerns rather than
domain-specific features. This means every domain's consent flows produce a
`ConsentRecord` with the same shape and the same lifecycle invariants enforced
at schema level, and every audit trail entry is validated by the same canonical
contract.

- **ConsentRecord** — The platform's consent contract. `ConsentRecordSchema`
  governs a consent category (one of 20 — `privacy`, `marketing`, `memory`,
  `voice`, `avatar`, `biometric`, `recording`, …) for a typed subject and
  target, with a GDPR-style legal basis, a collection context, a verification
  block, permission grants, evidence, the full lifecycle-timestamp set, renewal
  fields, and a chronological history. Extensive validators enforce
  lifecycle-timestamp ordering and require verified verification plus traceable
  evidence for high-risk categories.
- **AuditEvent** — Cross-domain audit trail entry. The legacy `AuditEventSchema`
  (in `audit.ts`) is permissive; the strict ADR-0023 contract
  `CanonicalPlatformAuditEventSchema` (in `canonical-audit-event.ts`, exported
  via the `./common/canonical-audit-event` subpath) requires actor, action
  (dotted namespace), outcome, reason, trace identifiers, and target on every
  event, and is enforced at audit-platform ingestion.
- **Incident** — Safety / operational incident documentation entity
  (`IncidentSchema`), used by moderation and safety-review workflows.
- **SupportCase** — Support-ticket entity (`SupportCaseSchema`) shared between
  domains that generate support events and the platform's support tooling.

### Creative and Content

These entities are shared across domains that produce or handle creative media —
voice synthesis, avatars, contemplative practices, and fact-checked content.

- **VoiceProfile** — TTS voice synthesis profile: provider, origin, training
  status, gender/age category, style, use scopes, consent status, watermark
  status, safety controls, emotion presets, and a quality tier/grade.
- **Ritual** — Cross-domain ceremonial/routine definition shared across the
  contemplative-knowledge domains (`tara`, `arete`, `veritas`, `nyx`, `nisaba`).
  Describes a kind, cadence, schedule, context signals, and an ordered set of
  ritual components.
- **Practice** — Repeatable practice definition shared across the same five
  domains. Records a practice kind (`meditation`, `breathwork`, `journaling`,
  …), difficulty, intensity, cues, steps, tracking mode, safety metadata, and
  grounding mode.
- **AvatarPack** — Avatar customization set: provider, origin, embodiment,
  style, render quality, training status, model format, still variants, preview
  video, consent status, watermark status/method, and a deception-risk level.
- **Claim** — Factual claim type used in fact-checking. `ClaimSchema` carries a
  `statement`, a claim type, a `verdict`, a verification status, `confidence`
  and `checkworthiness` scores (0–1), speaker info, evidence, and typed
  claim-to-claim debate links.
- **EvidencePack** — A collection of evidence used to package grounded research
  results; companion files cover evidence-pack assembly and assembly evaluation.

### Workflows and Operations

These entities coordinate long-running processes, platform governance, and AI
session continuity across domain boundaries.

- **WorkflowTemplate** — Reusable workflow definition
  (`WorkflowTemplateSchema`).
- **PolicyBundle** — Content and governance policy definition
  (`PolicyBundleSchema`).
- **ReviewPackage** — Peer-review submission (`ReviewPackageSchema`);
  `review-stage-graph.ts` defines the review-stage graph.
- **ProvenanceBundle** — Content-provenance lineage for asset attribution
  (`ProvenanceBundleSchema`), with helper functions in
  `provenance-bundle-helpers.ts`.
- **ContinuityState** — Assistant session continuity state: status, momentum,
  surface, journey kind/status, resume mode, reminders, checkpoints, and
  assistant mode (`text`/`voice`/`multimodal`).
- **MemoryScope** — Memory-scope definition: scope kind, owner type, storage
  class, content type, sensitivity, privacy boundary, retention action,
  sharing/sync/consent modes, review state, and share targets.
- **Collection** — Generic ordered collection of cross-domain content
  (`CollectionSchema`).
- **Tenant** — Multi-tenant organisation entity (`TenantSchema`).

### Admin, Privacy, and Governance Contracts

Beyond the canonical entities above, `common/` contains roughly 120 further
schema files — the bulk of the directory. These define typed contracts for the
admin console and compliance surfaces, ensuring that the admin UI, moderation
workflows, and data-governance pipelines all share the same request/response
shapes as the backend APIs.

The 120 files span approximately four categories. The admin console contracts
comprise roughly 80 `admin-*` files covering moderation, inbox, notifications,
incident management, model and persona governance/registry, editorial, billing,
privacy/DSAR/retention/deletion workflows, research-integrity review,
voice/avatar/watermark verification, bulk operations, readiness dashboards,
universal search, copilot surfaces, and more — each is a typed Zod contract for
the corresponding admin UI / API surface. The safety and moderation contracts
(`safety-*` files) cover severity, appeals, crisis, repeat-offender, content
policy, voice/avatar evaluations, and unified safety review. The privacy and
data-rights contracts cover consent controls, data export/deletion,
retention/residency/restore rules, and entitlements. Finally, the
retrieval-grounded research contracts define the grounded answer/report,
citation integrity, hallucination-risk, source sets, and unsupported-claim
detection schemas shared by Sophia, Veritas, Nisaba, and Metis.

---

## Event Schemas (`@oshun/contracts/events`)

All cross-domain events use a typed envelope. The envelope carries the metadata
needed for event routing, deduplication, and tracing, without the payload
knowing anything about the infrastructure it travels through. This separation
means a consumer can validate and route an event using only the envelope fields,
and only deserialize the payload once it has confirmed the event type is one it
handles.

### Event Envelope

The `EventEnvelopeSchema` wraps every event published on the event bus. The
fields below are present on every event regardless of domain:

- **`id`** — UUID v4 (`UUIDSchema`). Uniquely identifies the event for
  deduplication and idempotency checks.
- **`type`** — Dotted `domain.action` string (e.g. `isis.asset.generated`),
  validated against a regex. The primary dispatch key for subscribers.
- **`source`** — Source domain, one of 13 enum values (`tara`, `isis`, `sophia`,
  `hathor`, `bellona`, `yemaya`, `lilith`, `aphrodite`, `nyx`, `psyche`,
  `veritas`, `concordia`, `system`).
- **`timestamp`** — ISO 8601 creation timestamp.
- **`version`** — Semver schema-version string for the payload, defaulting to
  `1.0.0`, so consumers can handle multiple payload versions during rolling
  deployments.
- **`priority`** — Event priority (`low`/`normal`/`high`/`critical`, default
  `normal`).
- **`payload`** — The event-specific payload (`z.unknown()` on the base
  envelope; typed via `createEventSchema`).
- **`metadata`** — Optional `EventMetadataSchema` carrying `correlationId`,
  `causationId`, `traceId`, `spanId`, `userId`, `projectId`, `organizationId`,
  `sessionId`, `requestId`, `ipAddress`, `userAgent`, and a `custom` map.
  Correlation and causation IDs live here, not on the envelope root.
- **`aggregate`** — Optional `{ type, id, version }` block for event-sourced
  aggregates.

Typed per-event schemas are produced by
`createEventSchema(eventType, source, payloadSchema)`, which extends the base
envelope with a literal `type`/`source` and a typed `payload`. The envelope file
also defines publish/consume infrastructure contracts:
`EventPublishOptionsSchema`, `EventPublishResultSchema`,
`EventConsumerConfigSchema`, and `DeadLetterEventSchema`.

### Domain Event Types

`AllEventTypes` (in `events/index.ts`) is the central map of every event-type
string. It currently registers **181 event types across 12 domains**. Each
domain module defines, per event, a `*PayloadSchema`, a `*EventSchema`, and an
`*EventTypes` constant.

#### Isis Events (Generative Factory) — 10 types

These events drive the AI generation workflow from job submission through to
asset delivery. Payloads carry job IDs, a generation type (`image`/`video`/
`audio`/`model_3d`/`texture`/`animation`/`avatar`/`world`), workflow names,
output asset references, and cost/GPU metrics on completion. The 10 types are:
`isis.job.queued`, `isis.job.started`, `isis.job.progress`,
`isis.job.completed`, `isis.job.failed`, `isis.job.cancelled`,
`isis.asset.generated`, `isis.workflow.registered`, `isis.workflow.updated`,
`isis.model.loaded`.

#### Sophia Events (Knowledge Engine) — 9 types

`sophia.document.ingested`, `sophia.document.updated`,
`sophia.document.deleted`, `sophia.index.updated`, `sophia.index.rebuilt`,
`sophia.search.performed`, `sophia.entity.extracted`,
`sophia.relation.discovered`, `sophia.citation.created`.

#### Hathor Events (World Builder) — 7 types

`hathor.world.created`, `hathor.world.published`, `hathor.world.validated`,
`hathor.element.added`, `hathor.narrative.generated`,
`hathor.simulation.started`, `hathor.simulation.completed`.

#### Bellona Events (Engine/Build) — 8 types

`bellona.session.started`, `bellona.session.ended`, `bellona.build.started`,
`bellona.build.progress`, `bellona.build.completed`, `bellona.export.started`,
`bellona.export.ready`, `bellona.asset.synced`.

#### Yemaya Events (Creative Studio) — 12 types

Project lifecycle events (`created`/`updated`/`archived`), member events
(`joined`/`left`), asset events (`uploaded`/`processed`/`approved`/`rejected`),
comment events (`created`/`resolved`), and `yemaya.session.joined`.

#### Lilith Events — 10 types

Meditation events (`lilith.meditation.started`/`completed`/`generated`), journal
events (`created`/`updated`), session events (`started`/`ended`),
`lilith.progress.updated`, `lilith.teacher.interaction`,
`lilith.content.downloaded`.

#### Tara Events (Contemplative Practice) — 1 type

A single event, `tara.ritual.completed`. Its payload is deliberately rich: it
carries ritual identity, completion metrics, step accounting, reflection state,
and exactly three cross-domain completion handoffs (to `arete`, `nisaba`, and
`nyx`). The handoff count is enforced by schema (`.min(3).max(3)`), ensuring all
three downstream domains always receive the signal.

#### Aphrodite Events (Creator Economy) — 24 types

These 24 events span the full creator-economy lifecycle. Stream events cover
`stream.started`/`ended`, `stream.viewer_count_updated`, and
`stream.goal_reached`. Transaction events cover `transaction.tip_received`,
`tokens_purchased`, `subscription_created`/`cancelled`,
`payout_requested`/`completed`. User events cover
`user.registered`/`verified`/`followed`/`banned`. Device events cover
`device.connected`/`control_sent`/`state_updated`. Chat events cover
`chat.message_sent`/`user_muted`. Moderation events cover
`moderation.content_flagged`/`content_reviewed`. Content events cover
`content.recording_ended`/`vod_published`/`clip_created`.

#### Nyx Events (Cosmic Observatory) — 24 types

The 24 Nyx events are grouped by service area. Catalog events:
`nyx.object.viewed`, `nyx.observation.logged`/`updated`, `nyx.view.saved`,
`nyx.list.created`, `nyx.list.item.observed`, `nyx.achievement.unlocked`,
`nyx.tour.started`/`completed`. Compute events: `nyx.compute.ephemeris.updated`,
`nyx.compute.event.predicted`, `nyx.compute.eclipse.predicted`,
`nyx.compute.conjunction.predicted`, `nyx.compute.satellite.pass`. Render
events: `nyx.render.tile.generated`, `nyx.render.export.ready`,
`nyx.render.cache.invalidated`. Realtime events:
`nyx.realtime.satellite.visible`, `nyx.realtime.iss.pass`,
`nyx.realtime.meteor.peak`, `nyx.realtime.aurora.alert`,
`nyx.realtime.event.imminent`. Catalog-update events: `nyx.catalog.tle.updated`,
`nyx.catalog.orbital.updated`.

#### Psyche Events (AI Embodiment) — 37 types

Psyche's 37 events span every stage of an AI avatar interaction. Session
lifecycle events cover started/ended/paused/resumed. Avatar events cover state,
expression, animation, created, and trained. Voice events cover speaking,
listening, interim/final transcript, and response generated. Memory events cover
created/updated/retrieved/consolidated. Persona events cover
created/updated/activated/deactivated. Tool-execution events cover
started/completed/failed. Conferencing events cover participant joined/left,
speaker changed, screen-share, and room started/ended. Emotion events are
`psyche.emotion.detected` and `psyche.emotion.sentiment_analyzed`. An error
event completes the set.

#### Veritas Events (AI News Agency) — 27 types

Article lifecycle and processing events cover `created`/`updated`/`published`/
`unpublished`/`ingested`/`processed`/`enriched`/`clustered`. Claim and
fact-check events cover `claim.extracted`, `claim.verified`,
`factcheck.started`/`completed`. Additional events cover story clusters, feeds
(`feed.fetched`/`failed`), media generation (video/audio), alerts
(`alert.breaking_news`/`moderation`), analytics (`trending_updated`,
`engagement_recorded`), and NLP processing (sentiment, topics, keywords,
summary, entities).

#### Concordia Events (Cooperative Mediation) — 12 types

These 12 events track a mediation case from creation to resolution. The types
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`. Payloads carry
only identifiers and viewer-safe metadata — private party fields are never
included. The module also exports a `ConcordiaEventSchemaRegistry` keyed by
event type.

---

## Validation Utilities

A payload that is valid TypeScript at compile time can still fail at runtime if
it arrives as raw JSON from Kafka or an HTTP body — the types are erased. The
validation layer bridges this gap: every schema is also a Zod validator that can
be called at a service boundary to confirm the incoming data matches what the
types describe.

- **Zod Schema Exports** — Every entity type has a corresponding Zod schema
  (e.g. `UserSchema`, `AssetSchema`, `EventEnvelopeSchema`). Consumers call
  `.safeParse()` / `.parse()` directly at API boundaries, queue consumers, and
  event handlers.
- **Event Validation API** (`events/validation.ts`) — `validateEvent(event)`
  validates the envelope and, if the type is registered, the type-specific
  schema; `validatePayload(eventType, payload)` validates a payload alone.
  `validateEventOrThrow` / `validatePayloadOrThrow` throw an
  `EventValidationError`. Helpers `getEventSchema`, `getPayloadSchema`,
  `getRegisteredEventTypes`, `getEventTypesByDomain`, and
  `isEventTypeRegistered` query the `EventSchemaRegistry`.
- **Event Schema Registry** — `EventSchemaRegistry` is a `Map` of
  `EventSchemaEntry` records (`type`, `source`, `schema`, `payloadSchema`,
  `description`). It registers the Isis, Sophia, Hathor, Bellona, Yemaya,
  Lilith, and Tara event schemas. The registry is partial — not all 12 domains'
  events are registered.
- **Middleware Helpers** — `createValidationMiddleware` wraps event handlers and
  `createPublishValidator` wraps publishers, each in `strict` (throw) or
  non-strict (warn-and-continue) mode.
- **Schema Composition** — Complex entity schemas are composed from constituent
  schemas (e.g. `AssetSchema` embeds `AssetLicenseSchema` and
  `AssetProvenanceSchema`), so a base type's change propagates automatically.
- **Contract↔Prisma Alignment Tests** — `contract-prisma-alignment.test.ts` and
  `contract-prisma-migrations.test.ts` verify that contract types stay
  structurally consistent with the Prisma database schema and that new required
  fields have matching migrations.

---

## Additional Subpaths

Beyond `./common` and `./events`, `@oshun/contracts` exposes several further
per-domain canonical contract surfaces. These subpaths exist because some
domains have rich enough contract requirements to warrant their own organized
module, while still benefiting from living inside the zero-upstream contracts
package.

- **`@oshun/contracts/llm`** — The canonical LLM gateway contract: the
  `IsisLLMClient` interface plus request/response/streaming schemas, a typed
  error taxonomy, and pricing-unit primitives. A `./llm/test-utils` subpath
  provides a gateway test double.
- **`@oshun/contracts/aja`** — Motion-AI / embodied-instruction contracts:
  math/skeletal primitives, motion file formats (BVH/FBX/glTF/USD/Alembic/
  C3D/CSV), job lifecycle, and embodied-instruction request/response contracts.
- **`@oshun/contracts/arete`** — Habit and goal contracts (check-in status,
  habit cadence, goal timeframe/scope/status).
- **`@oshun/contracts/tara`** — Contemplative-practice taxonomies (mood, theme,
  modality) plus a `./tara/playback-rate` subpath.
- **`@oshun/contracts/nyx`** — Sky-event canonical contracts (event families and
  specific event types) — distinct from the `events/nyx.ts` module.
- **`@oshun/contracts/metis`** — Learning/tutoring contracts (course builds,
  grounding packs, assessment evidence, tutor persona/session memory).
- **`@oshun/contracts/nisaba`** — Manuscript/scholarship contracts (manuscripts,
  editions, lexicon and morphology entries, concept graphs, study plans).
- **`@oshun/contracts/veritas`** — Veritas fact-check canonical contracts
  (claims, sources, stories, timelines, retraction cascades) — distinct from the
  `events/veritas.ts` module.
- **`@oshun/contracts/v3`** — V3 Lilith/Tara/Saraswati contracts.
- **`@oshun/contracts/tts`** — TTS gateway client and provider adapters.
- The root barrel also re-exports the Living Scene score/technique contracts,
  the Iris memory entry/continuation contracts (`IrisContracts`), and the agent
  tool-catalog/grants contracts (`AgentContracts`).

---

## Sibling Contract Libraries

The directory `libs/contracts/` also hosts several **separate Nx libraries**
(each its own package), not subpaths of `@oshun/contracts`. The key distinction
is organizational: a sibling package like `@iris/contracts` can be versioned and
evolved independently, while still following the same zero-upstream-dependency
rule so it can be safely imported anywhere in the monorepo.

### `@iris/contracts` — Iris AI Assistant Contracts

API contracts and Zod schemas for the Iris AI Assistant. The library is
organized into four focused subpaths:

- **Conversation Contracts** — message content blocks (text, image, tool-use,
  tool-result), `MessageSchema`, `ConversationSchema`, and streaming events.
- **Tiered Memory Contracts** — a four-tier memory model: core memory blocks,
  working memory entries, archival memory (with search), and episodic memory
  (with query), plus memory operations and a full `MemoryState`.
- **Agent Contracts** — tool definitions, agent config/status, agent execution,
  and a built-in `MEMORY_TOOLS` catalog.

Subpaths: `./common`, `./conversation`, `./memory`, `./agent`.

### `@psyche/contracts` — Psyche AI Conferencing Contracts

Domain contracts for Psyche, the hyper-realistic AI virtual assistant platform
for video conferencing. Currently exports its `common/` schema module; avatar,
voice, behavior, perception, conferencing, knowledge, and persona modules are to
be added as services are migrated.

### `@concordia/contracts` — Cooperative Mediation Contracts

API contracts for Concordia cooperative mediation and negotiation — a large
library spanning ~100 feature directories (the case model, parties, issues,
agreements, the agreement DSL, preference/utility models, settlement lifecycle,
access/authority/consent, escalation, search, oversight, and cross-domain
integrations). Its barrel currently exports the use-case classification surface
(use-case classes, class profiles, eligibility helpers) and the hard-boundary
surface (boundary kinds, rules, violations); Phase 179 follow-on tasks extend
the exports.

### Industrial / Commerce Contract Libraries

These four packages provide the contract layer for the platform's physical and
commercial domains. Each depends only on `zod` and follows the zero-upstream
rule.

- **`@freya/contracts`** — Freya luxury-goods domain: product, order, customer,
  and manufacturing schemas.
- **`@contracts/brigid`** — Brigid industrial domain: events, API schemas, and
  cross-domain/integration contracts.
- **`@contracts/cybele`** — Cybele construction/infrastructure domain: API
  schemas and events.
- **`@contracts/saraswati`** — Saraswati cross-domain integration adapters
  connecting Saraswati to Brigid, Asase, Freya, Cybele, and Maat.
- **`@maat/contracts`** — A scaffold package that exports only the
  `MaatContractEnvelope` interface; its subdirectories currently hold only
  `.gitkeep` files, so the Maat contract surface is not yet implemented.

> `libs/contracts/veritas/` is an empty placeholder directory (only `.gitkeep`);
> the implemented Veritas canonical contracts are the `@oshun/contracts/veritas`
> subpath.

Contracts does not own product behavior. Product features remain in domain
feature files; Contracts owns the stable type and schema agreements those
features depend on.