# Oshun V1 — Dependency Registry > **Scope:** Dependencies that the Oshun V1 launch relies on — third-party APIs, > SDKs, infrastructure services, language runtimes, and internal packages that > sit on the V1 critical path. Out-of-scope domains (Yemaya, Maya, Iris coding > assistant, Maat, Cybele, Saraswati, Brigid, etc.) are cataloged in the > whole-monorepo [`/DEPENDENCIES.md`](../DEPENDENCIES.md). **Companion docs:** > [`V1/features.md`](./features.md), [`V1/TODOS.md`](./TODOS.md), > [`V1/ARCHITECTURE.md`](./ARCHITECTURE.md). **Date:** 2026-05-11 ## Purpose This file is the V1-scoped dependency contract. For each dependency it answers three questions a reviewer needs before launch: 1. **What is it** — one sentence on the dependency itself. 2. **Where does V1 use it** — the V1 features or TODOS sections that need it. 3. **How is it wired** — env vars, package paths, ports, version source. Pinned versions live in `pnpm-workspace.yaml` (TypeScript), each service's `pyproject.toml` (Python), and `docker/docker-compose.dev.yml` plus the per-domain compose files (containers). This document references those sources of truth rather than duplicating them. ## Table of Contents 1. [Internal Packages — Foundations](#1-internal-packages--foundations) 2. [Internal Packages — V1 Domains and Substrates](#2-internal-packages--v1-domains-and-substrates) 3. [Application Runtimes](#3-application-runtimes) 4. [Backend Frameworks](#4-backend-frameworks) 5. [Frontend Stack](#5-frontend-stack) 6. [Mobile Stack](#6-mobile-stack) 7. [Data Stores](#7-data-stores) 8. [AI / ML Providers](#8-ai--ml-providers) 9. [Generation Providers (Isis)](#9-generation-providers-isis) 10. [Inbound Integrations](#10-inbound-integrations) 11. [Outbound Messaging Channels](#11-outbound-messaging-channels) 12. [Identity, Auth, and Provisioning](#12-identity-auth-and-provisioning) 13. [Payment and Billing](#13-payment-and-billing) 14. [Observability and Telemetry](#14-observability-and-telemetry) 15. [Object Storage and CDN](#15-object-storage-and-cdn) 16. [Search and Vector Stores](#16-search-and-vector-stores) 17. [Concept and Knowledge Graph](#17-concept-and-knowledge-graph) 18. [Domain-Specific External APIs](#18-domain-specific-external-apis) 19. [Provenance and Synthetic-Content Verification](#19-provenance-and-synthetic-content-verification) 20. [Cloud Providers](#20-cloud-providers) 21. [Containerization and Local Development](#21-containerization-and-local-development) 22. [CI/CD and Build Tooling](#22-cicd-and-build-tooling) 23. [Testing Tooling](#23-testing-tooling) 24. [Security and Secrets](#24-security-and-secrets) --- ## 1. Internal Packages — Foundations Foundational packages that every V1 surface depends on. | Package | Path | What V1 uses it for | | ------------------------------ | ----------------------------------- | -------------------------------------------------------------------------------------------------------- | | `@oshun/contracts` | `libs/contracts/` | Zod contracts for every V1 object class (TODOS § 1.2). Drives OpenAPI specs. | | `libs/openapi` | `libs/openapi/` | Generated OpenAPI 3.1 specs and per-domain clients (TODOS § 1.5). Specs at `src/specs/`. | | `libs/proto` | `libs/proto/` | Protocol Buffers for gRPC service-to-service traffic (Psyche, Isis, Sophia). | | `@oshun/persistence` | `libs/oshun/persistence/` | Prisma renderer, zod→Prisma introspection, contract-persistence drift tests (TODOS § 1.4). | | `@oshun/event-bus` | `libs/shared/event-bus/` | Topic registry with schema versioning, outbound signing/retry/DLQ, webhook simulator (TODOS § 1.9). | | `@oshun/queue` | `libs/shared/queue/` | Durable BullMQ-style queue, DLQ, SLA monitor (TODOS § 1.8). | | `@oshun/http-client` | `libs/shared/http-client/` | Idempotency-key middleware, retry, partial-failure envelope (TODOS § 1.6). | | `@oshun/data-residency` | `libs/shared/data-residency/` | Residency enforcer, traffic shaping, home-zone (TODOS § 1.7 + V1 residency policy). | | `@oshun/inbound-integrations` | `libs/shared/inbound-integrations/` | LMS/OneRoster/Identity/Calendar/Payment/Telemetry/BYOM/Notification connector frameworks (TODOS § 1.10). | | `@oshun/audit-platform` | `libs/shared/audit-platform/` | Append-only audit substrate for Iris admin inspection, DSAR, deletion, review packages. | | `@oshun/identity` | `libs/shared/identity/` | RBAC, permission checks. | | `@oshun/auth-primitives` | `libs/shared/auth-primitives/` | JWT and session primitives. | | `@oshun/auth-client` | `libs/oshun/auth/` | Workspace-side identity/session client used by every Oshun app. | | `@oshun/design-tokens` | `libs/oshun/design-tokens/` | Design tokens for cream-paper + terracotta canonical + tone variants. | | `@oshun/ui` | `libs/oshun/ui/` | Shared React component library. | | `@oshun/navigation` | `libs/oshun/navigation/` | Deep links, current-domain persistence, command-surface registration. | | `@oshun/analytics` | `libs/oshun/analytics/` | Route-level analytics, experiment scoping, feature flags. | | `@oshun/testing` | `libs/shared/testing/` | Test utilities shared across apps. | | `@oshun/offline` | `libs/oshun/offline/` | Offline shell, retry, recent-content fallback. | | `@oshun/concordia-integration` | `libs/oshun/concordia-integration/` | Concordia (cross-tenant federation) integration adapter where required. | Not on the V1 critical path but used by Isis post-processing (image/video generation): `@oshun/color-science` (`libs/oshun/color-science/`) provides color-science foundations for OSHUN imaging workflows. V1 consumes it transitively through the Isis generation pipelines rather than from any customer/admin surface. --- ## 2. Internal Packages — V1 Domains and Substrates ### Customer-facing domains | Domain | Adapter package | Contracts namespace | Service apps (where applicable) | | ------- | ------------------------------------------------- | ---------------------------------------- | ------------------------------------------------ | | Tara | `@oshun/domain-tara` | `libs/contracts/src/tara/` | `apps/tara/*` | | Arete | `@oshun/domain-arete` | `libs/contracts/src/arete/` | `apps/arete/*` | | Veritas | `@oshun/domain-veritas` | `libs/contracts/src/veritas/` (+ pkg) | `apps/veritas/*` | | Nyx | `@oshun/domain-nyx` | `libs/contracts/src/nyx/` | `apps/nyx/*` | | Nisaba | `@oshun/domain-nisaba` | `libs/contracts/src/nisaba/` (namespace) | (BFF-backed; Sefaria/CDLI/IIIF connectors below) | | Metis | `libs/metis/api-client` (→ `@oshun/domain-metis`) | `libs/contracts/src/metis/` (namespace) | `apps/metis/{web,admin,api-gateway,worker}` | ### Platform substrates | Substrate | Adapter package | Service apps / libs | | --------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Sophia | `@oshun/evidence-sophia` | `apps/sophia/*`, `libs/sophia/{client,database,ingestion,indexing,evaluation}` | | Iris | `@oshun/memory-iris` | (memory and identity; not the Iris coding agent) | | Psyche | `@oshun/embodiment-psyche` | `apps/psyche/*`, `services/psyche/*`, `libs/psyche/*`, `libs/contracts/psyche/` | | Lilith | `@oshun/persona-policy-lilith` | (policy adapter; tone/safety surface) | | Isis | `@oshun/generation-control-isis` | `apps/isis/*`, `libs/isis/{client,database,workflows,comfyui-nodes,ai-providers/*,3d-generation,ai-video,audio-generation,outputs,gaussian-splatting}` | | Aje | (consumed directly; no Oshun adapter) | `libs/aje/{core,chains,bitcoin,wallets,payments,oracles,nodes,privacy,settlement-escrow,identity,account-abstraction,contracts,sdk,...}` — V1 crypto payment substrate. See [§ 13 Payment and Billing](#13-payment-and-billing). | ### Cross-domain support | Subsystem | Adapter / Library | V1 role | | --------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | Aja | `@oshun/embodiment-aja` | Embodied-instruction hook for Metis (movement/practice). | | Yemaya | `libs/yemaya/sdk` | Rendering substrate for media surfaces. | | Themis | `libs/themis/*` | Academic-integrity adjudication for Metis assessments. | | Bellona | `libs/bellona/*` (bridge-core, unity/unreal/godot/blender/davinci, openusd, interchange, build) | Studio-only engine-bridge and build/export substrate (Studio routes only). | | Hathor | `libs/hathor/*` (characters, world, quests, narrative, simulation, validation) | Studio-only narrative/world/lore-authoring substrate (Studio routes only). | | Neith | `apps/oshun/web/src/app/studio/neith/` (inverse-modeling workspace) | Studio-only inverse modeling: image-to-parameter estimation for asset pipelines. | ### Shared shell | Package | Path | V1 role | | --------------------------- | -------------------------------- | ----------------------------------------------------------------------- | | `@oshun/shell-core` | `libs/oshun/shell-core/` | Home/explore/activity/library/notifications/profile/settings/assistant. | | `@oshun/shell-assistant` | `libs/oshun/shell-assistant/` | Collapsible assistant dock; context handoff. | | `@oshun/shell-routines` | `libs/oshun/shell-routines/` | Routine and continuation cards. | | `@oshun/shell-desktop` | `libs/oshun/shell-desktop/` | Desktop multi-panel workspace primitives. | | `@oshun/shell-wearable` | `libs/oshun/shell-wearable/` | Watch + widget + Live-Activity surface. | | `@oshun/shell-achievements` | `libs/oshun/shell-achievements/` | Achievements + recognition surfaces. | | `@oshun/domain-registry` | `libs/oshun/domain-registry/` | Single source of truth for V1 domains (TODOS § 1.1). | | `@oshun/persona-registry` | `libs/oshun/persona-registry/` | Persona, avatar, voice-pack registry. | --- ## 3. Application Runtimes | Runtime | Version source | V1 use | | ---------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | Node.js | `engines.node` in app `package.json`; target `node22` for BFF | All TypeScript apps and services. | | Python | per-service `pyproject.toml` | Sophia ingestion, Isis worker tasks, Metis research/quality libs where needed. | | Rust | per-crate `Cargo.toml` | Yemaya/Maya/Uzume protocol engines — not on the V1 critical path beyond what V1 surfaces consume from `libs/yemaya/sdk`. | | TypeScript | `typescript` in `pnpm-workspace.yaml` | Whole TS surface. | --- ## 4. Backend Frameworks | Framework | Version source (pnpm catalog) | V1 use | | --------- | -------------------------------------------- | ----------------------------------------------------------------------------------------- | | Fastify | `fastify: ^4.28.1` | Oshun BFF (`apps/oshun/bff`), Metis api-gateway (where applicable). | | Hono | `hono: ^4.0.0` + `@hono/*` | Lightweight service routers, OpenAPI/Zod validation, Swagger UI in Studio admin surfaces. | | Prisma | `prisma: ^5.20.0`, `@prisma/client: ^5.20.0` | Per-domain ORM; schemas generated by `@oshun/persistence` from Zod. | | Zod | `zod` (pinned through `@hono/zod-openapi`) | All contracts; OpenAPI generation; runtime guards. | --- ## 5. Frontend Stack | Library | Version source | V1 use | | ----------------------- | -------------------------------------- | ------------------------------------------------------------- | | Next.js | `next: ^14.2.21` | `apps/oshun/web`, `apps/oshun/admin`, `apps/metis/web/admin`. | | `next-intl` | `^3.26.3` | i18n in customer + admin web. | | `next-pwa` | `^5.6.0` | PWA install/update/relaunch, offline shell. | | React | `react: ^18.3.1`, `react-dom: ^18.3.1` | All web surfaces. | | `@tanstack/react-query` | `^5.90.16` | BFF data fetching, optimistic updates, offline caches. | Design system grounding: cream-paper + terracotta canonical, with the Lilith register variants applied at the persona-policy boundary (`@oshun/persona-policy-lilith`). Routes referenced in V1 features include `/`, `/landing`, `/tara…/nisaba`, `/operator/*`, `/system`. Lighthouse budgets live at `apps/oshun/web/lighthouse-budget.json` (LCP ≤ 2.5s, INP ≤ 200ms, CLS ≤ 0.1). **Hosting:** all Next.js front-ends (`apps/oshun/{web,admin,tenant-admin,telegram-miniapp}`, `apps/metis/{web,admin}`) run as **containers on the single Hetzner box** (SSR standalone + static, both via `docker/Dockerfile.web`) behind the Caddy TLS edge, host-routed on `.` — the same single hosting plane as every backend service. Defined by `deploy/v1/hetzner/docker-compose.yml` and released by `.github/workflows/deploy-hetzner.yml`. History: Vercel → Amplify → Fargate (2026-07-04 single-plane consolidation, `V1/planning/IAC_CICD_AUDIT_2026-07-04.md`) → Hetzner single box (2026-07-09, `V1/planning/HETZNER_SINGLE_BOX_2026-07-09.md`). --- ## 6. Mobile Stack | Library | Version (mobile `package.json`) | V1 use | | ------------------------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------ | | Expo | `~51.0.0` | `apps/oshun/mobile` runtime + tooling. | | React Native | `0.74.5` | Mobile UI runtime. | | `expo-router` | `~3.5.0` | Deep-link routing across all top-level domains. | | `expo-haptics` | `~13.0.0` | Haptic + motion + transition behavior for major flows. | | `expo-secure-store` | `~13.0.2` | Credential storage for `@oshun/auth-client`. | | `expo-linking` | `~6.3.0` | Universal Links / Android App Links. | | `expo-constants` / `expo-dev-client` | `~16.0.0` / `~4.0.29` | App identity + dev client for internal builds. | | `expo-font` / `expo-splash-screen` / `expo-status-bar` / `expo-system-ui` | (see `apps/oshun/mobile/package.json`) | Visual chrome. | | `@react-navigation/native` | `^6.1.0` | Navigation primitives. | | `@react-native-community/netinfo` | `11.3.1` | Online/offline detection for `@oshun/offline`. | | `react-native-gesture-handler` | `~2.16.0` | Gesture-driven IA. | | `react-native-reanimated` | `~3.10.0` | Performant animations. | | `react-native-safe-area-context` | `4.10.1` | Notch/dynamic-island layout. | Admin mobile (`apps/oshun/admin-mobile`) shares the same Expo/RN baseline. **Launch-readiness gap:** V1 features.md calls for push routing (domain/persona/quiet-hours/sensitivity), audio playback for Tara meditations and Living Scenes narration, offline media caching, and camera/microphone capture. The mobile `package.json` does **not** yet pin `expo-notifications`, `expo-av`, `expo-image`, `expo-camera`, or `expo-file-system`. Either these must be added before launch or the supporting Expo plugins / native modules must be declared in the prebuild config. --- ## 7. Data Stores | Store | Local image (dev compose) | V1 role | | ----------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | PostgreSQL + pgvector | `pgvector/pgvector:pg16` | OLTP for every V1 domain. Per-domain databases: `oshun_dev`, `tara`, `arete`, `veritas`, `nyx`, `nisaba`, `metis`, `lilith`, `isis`, `sophia`. pgvector for embeddings (Sophia, Nisaba, recommendations). | | PgBouncer | bundled in compose | Connection pooling in front of every production database. | | Redis | dev container | Event bus (`@oshun/event-bus`: Redis pub/sub with TTL-keyed replay — not native Streams), job queue (`@oshun/queue`), tenant-scoped cache, rate limiting, sessions. | | MinIO | dev container; S3 in prod | Media (generated artifacts, Living Scenes renders, source ingestion, exports). Bucket per domain. | | Elasticsearch | dev container (search profile) | Universal search backbone across rituals/passages/claims/sources/notebooks/etc. | | Qdrant | dev container (vectors profile) | High-cardinality vector similarity (Sophia retrieval beyond pgvector capacity, lineage search). | | Neo4j | dev container (graph profile) | Concept graph (Nisaba), Metis knowledge graph, lineage chains. | | Kafka | dev container (streaming profile) | High-volume cross-domain events overflow from the Redis event bus. | | Mailpit | dev container (core) | Local email capture (1025/8025). | | Prometheus / Grafana / Jaeger | dev containers (observability profile) | Metrics, dashboards, distributed tracing. | Profiles documented in `CLAUDE.md` § "Local Development". --- ## 8. AI / ML Providers | Provider | SDK / catalog version | V1 use | | -------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------- | | Anthropic | `@anthropic-ai/sdk: ^0.30.0` | Primary LLM for assistant, Sophia synthesis, Metis tutoring, Lilith policy guards, agentic AI. | | OpenAI | `openai: ^4.0.0` | Alternate LLM endpoint; speech APIs where authorized. | | Google Generative AI | `@google/generative-ai: ^0.21.0` | Supplemental model (Vertex AI in production for TPU-hosted variants). | | MCP | `@modelcontextprotocol/sdk: ^1.11.0` | Model Context Protocol tool grants for agentic AI surfaces (TODOS § 18). | All provider calls flow through: - **Isis control plane** for generation jobs and provenance bundles. - **Lilith persona policy** for tone/crisis/audacity gating. - **Iris memory** for consent scoping and admin inspection trails. --- ## 9. Generation Providers (Isis) V1 generation surfaces fan out behind `@oshun/generation-control-isis`. Raw provider access is **operator-only** (TODOS § 24, features.md § Generation Audience Tiers). | Provider | What it is | V1 use | | --------------------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **RunPod** | GPU cloud (A100/H100/RTX 4090). | Hosts ComfyUI, SDXL, Flux, and custom inference endpoints. `RUNPOD_API_KEY` in Secrets Manager; endpoint IDs per generation surface. Compose blueprints at `docker/runpod/`. | | **ComfyUI** | Node-based workflow runtime. | Image/video generation pipelines wrapped in `libs/isis/workflows/`. Custom nodes in `libs/isis/comfyui-nodes/`. | | **Civitai** | External model intake. | Operator-only intake review queue (`civitai-intake-spec.ts`, `civitai-review-pipeline.ts`). Customer/studio surfaces never see raw Civitai listings. | | **Stable Diffusion (SDXL)** | Image generation model. | Backing model for Living Scenes visual outputs, explanatory visuals. | | **Flux** | Image generation model. | Alternate image model where tone/style favors Flux over SDXL. | | **ElevenLabs (voice)** | Voice synthesis provider. | Voice generation for Tara teachers, Metis tutors, Living Scenes narration. Provider adapter at `libs/isis/ai-providers/src/providers/tts/elevenlabs-provider.ts`; audio-side client at `libs/isis/audio-generation/src/voice/elevenlabs-client.ts`. Voice-provider abstraction (`libs/oshun/persona-registry/src/voice-provider-abstraction.ts`) keeps additional providers swappable. Strict voice-quality and voice-abuse policy (Lilith). **Decision (2026-07-06, closes TODOS §35):** the direct HTTP client IS the supported V1 path — it is a deep, tested integration (~5.1k-line client with spec + ~1.4k-line provider adapter), and pinning the official `elevenlabs` SDK would duplicate it for no capability gain. Revisit only if ElevenLabs ships an API surface the direct client cannot reach. | | **Suno (music)** | Music generation provider. | Music beds for Living Scenes Domain Templates. Adapter at `libs/isis/audio-generation/src/generation/suno-provider.ts`. | | **Udio (music)** | Alternate music generation provider. | Music beds where Udio tonality fits a domain template. Adapter at `libs/isis/audio-generation/src/generation/udio-provider.ts`. | | **Self-hosted audio** | In-house music/SFX runtime. | Fallback music + sound-effects path under sanction. Adapter at `libs/isis/audio-generation/src/generation/self-hosted.ts`; SFX at `libs/isis/audio-generation/src/generation/sfx-provider.ts`. | | **3D generation** | Gaussian splatting and adjacent pipelines (`libs/isis/gaussian-splatting`, `libs/isis/3d-generation`). | Optional 3D outputs in operator/creator surfaces. | Every generation produces a `ProvenanceBundle` (consent ID, prompt, model, watermark hash, timestamp, invoking user, tenant) recorded against the audit platform and used by takedown cascades. --- ## 10. Inbound Integrations All inbound integrations are implemented by `@oshun/inbound-integrations` (`libs/shared/inbound-integrations/src/`). Each module exposes a connector framework with health probes, circuit breakers, version pinning, and upgrade pathways (TODOS § 1.10). ### LMS / Standards | Standard | Module | V1 use | | ----------------------- | -------------- | ------------------------------------------------------------------------------- | | LTI 1.3 / LTI Advantage | `lms.ts` | Metis tool launch, deep linking, names-and-roles, assignment-and-grade service. | | SCORM | `lms.ts` | Legacy LMS fallback for Metis institutions without LTI/xAPI. | | OneRoster | `oneroster.ts` | Rostering sync with conflict reporting and dry-run. | | xAPI / cmi5 | `telemetry.ts` | Per-statement learner activity export. | | Caliper | `telemetry.ts` | Alternate learner-activity export. | ### Calendars | Provider | Module | V1 use | | -------- | ------------- | --------------------------------------------------------------------------- | | Google | `calendar.ts` | Two-way sync for Tara rituals, Arete reminders, Nyx events, Metis sessions. | | Apple | `calendar.ts` | iOS-native calendar bridge for the same surfaces. | | Outlook | `calendar.ts` | Tenant/enterprise calendar bridge. | ### BYOM (bring-your-own-model) | Module | V1 use | | --------- | ---------------------------------------------------------------------------- | | `byom.ts` | Tenant-provided model endpoints for Metis study and tenant agent invocation. | ### Payments and Notifications Documented in [§13 Payment](#13-payment-and-billing) and [§11 Outbound Messaging](#11-outbound-messaging-channels). --- ## 11. Outbound Messaging Channels | Channel | V1 use | Wiring | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | **Email** | Transactional + lifecycle notifications. | Mailpit in dev (`docker-compose.dev.yml`); SES/Postmark-class in prod. | | **Push (FCM/APNs)** | Per-domain/persona/quiet-hours/sensitivity push routing for customer + admin mobile. | Firebase Admin (`firebase-admin: ^13.0.0`); APNs cert in Secrets Manager. | | **SMS** | Optional V1 channel for re-engagement and high-priority alerts (where consented). | Provider adapter (Twilio-class). | | **Telegram Bot** | Delivery and light assistant; entitlement-aware command routing. | Bot token; webhook endpoint behind BFF. | | **Telegram Mini Apps** | Curated Studio surfaces in chat. | `initData` signature verification at BFF. | | **Telegram Channels** | Editorial publishing target with provenance preserved. | Channel admin token. | | **Telegram Inline** | Save, share, attribution. | Bot token. | | **Telegram Payments** | V1.x optional fiat rail. Bot may also surface a crypto invoice (BOLT11 / Monero subaddress / Solana Pay URL / TON @wallet deep link) from the V1 primary rail. | Provider tokens; payment connector framework; `@aje/payments` + `libs/oshun/payments-bridge/` for the crypto surface. | | **WhatsApp Business** | Transactional template messaging. | Cloud API or BSP integration. | | **Discord** | Community surface. | Bot + webhook integrations. | | **Slack** | Institutional notification sink; tenant ops. | Slack app + webhook integrations. | Boundary, residency, retention, consent, and audit are enforced uniformly through `@oshun/audit-platform` and Iris consent records. --- ## 12. Identity, Auth, and Provisioning | Standard / Service | Module / Library | V1 use | | ---------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------- | | OIDC | `@oshun/inbound-integrations/identity` | Tenant SSO with claim mapping, just-in-time provisioning. | | SAML 2.0 | `@oshun/inbound-integrations/identity` | Enterprise SSO for institutional tenants. | | SCIM 2.0 | `@oshun/inbound-integrations/identity` | User/group provisioning: create/update/deactivate/suspend. | | JWT / sessions | `@oshun/auth-primitives` + `@oshun/auth-client` | App-side identity and session management. | | RBAC | `@oshun/identity` | Permission checks across BFF and admin. | | Federation / multi-tenant identity | `@oshun/concordia-integration` | Cross-tenant federation where required. | | Step-up auth | Domain registry `DomainAuthPolicy.stepUpActions` | High-privilege actions: data deletion, admin inspection, persona publish. | --- ## 13. Payment and Billing V1 settlement is **non-custodial crypto-first**. The primary rail uses self-hosted nodes, watch-only or view-only wallets on the application server, and an air-gapped signing station for refunds and sweeps. Fiat (Stripe-class) is V1.x optional and slots into the same entitlement, receipt, and dunning machinery. ### V1 primary — non-custodial crypto (Aje `libs/aje/` + V1 bridge) V1 settlement consumes the **Aje** domain (Yoruba orisha of wealth and commerce) — the monorepo's existing library-only blockchain and Web3 infrastructure. Aje contributes the chain modules, wallet management, merchant payments, stablecoins, oracles, and nodes. V1 adds five new chain modules to Aje (Monero, Litecoin, TON, Ergo, Tron) plus a thin bridge library (`libs/oshun/payments-bridge/`) that maps Aje's invoice contracts onto the V1 entitlement event bus. The combined rail covers the top-10 payment cryptos by real-world volume plus Cardano and Ergo. Per-chain decentralization tier (A / B / C) and per-asset issuer-trust class are documented in features.md § Crypto Payments — Non-Custodial Entitlement Settlement and enforced at the invoice-disclosure layer. #### Aje library packages consumed by V1 | Aje library | Path | V1 use | | -------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `@aje/core` | `libs/aje/core/` | Address types, hex utilities, audited `@noble` / `@scure` crypto primitives. Foundation of the Aje stack. | | `@aje/chains` | `libs/aje/chains/` | Ethereum L1, Arbitrum, Optimism (Base via OP Stack), zkSync, Polygon (PoS / zkEVM / Linea / Scroll), Avalanche, Cardano, Solana. `abstraction/` exposes `UnifiedProvider` + `ChainRegistry`. | | `@aje/bitcoin` | `libs/aje/bitcoin/` | Lightning (LND / CLN / Phoenixd), LSP, BitVM, sBTC, Stacks, Ordinals, Runes, RGB. | | `@aje/wallets` | `libs/aje/wallets/` | HD wallet, hardware wallet (Trezor / Ledger / Coldcard), MPC, key management, account abstraction, paymaster, session keys, social login, WalletConnect. | | `@aje/payments` | `libs/aje/payments/` | `merchant/` (invoices, refunds, recurring, escrow, milestones, links, QR, receipts), `stablecoins/` (USDC, USDT, DAI, FRAX, GHO + risk/swap/aggregation), `streaming/`, `circle/`, `fiat-ramps/`, `cbdc/`. | | `@aje/oracles` | `libs/aje/oracles/` | Chainlink, Pyth, RedStone, API3 — used by V1 fiat-rate aggregation. | | `@aje/nodes` | `libs/aje/nodes/` | Full-node runner abstractions, light client, validator, RPC client primitives. | | `@aje/privacy` | `libs/aje/privacy/` | Privacy pools + advanced privacy. Available to tenants who want pre-settlement privacy routing. | | `@aje/settlement-escrow` | `libs/aje/settlement-escrow/` | Escrow deposits, milestone payouts. Reused by V1 refundable-flow invoices. | | `@aje/identity` | `libs/aje/identity/` | DID, ENS, Lens, Farcaster — used for ENS refund-address resolution. | | `@aje/account-abstraction` | `libs/aje/account-abstraction/` | ERC-4337, EIP-7702, ERC-7579 — future paywall UX (V1.x). | | `@aje/sdk` | `libs/aje/sdk/` | Unified developer entry point. | #### V1 contribution to Aje: five new chain modules Each follows Aje's existing `@aje/chains//` module pattern and preserves the "TypeScript throughout" design principle by isolating non-TS cryptography to upstream node processes (the TypeScript module owns only the JSON-RPC client; the wallet daemon is a separate process; spend keys live on the air-gapped signing station behind `@aje/wallets/hardware-wallet`). #### Tier A — credibly decentralized, self-hosted full node mandatory | Asset / rail | Catalog version / tooling | V1 use | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Bitcoin on-chain** | Bitcoin Core `^28.0` (self-hosted); BTCPay Server `^2.0` (self-hosted); `bitcoinjs-lib: ^7.0.0`; `bip32: ^5.0.0` | BIP84 xpub-derived per-invoice addresses; watch-only on app server; RBF fee-bump detection. | | **Litecoin (LTC)** | Litecoin Core `^0.21.3` (self-hosted); reuses `bitcoinjs-lib` + `bip32` with the LTC network params | BIP84 (`m/84'/2'/0'/0/*`) xpub-derived per-invoice addresses; 1 / 3 / 6 confirmation tiers (≈2.5 min/block). | | **Monero (XMR)** | `monerod` `^0.18.3` (self-hosted full node); `monero-wallet-rpc` `^0.18.3` (view-only mode, cold spend key) | Per-invoice subaddresses (account index `0`); 10-block unlock window; `(txid, tx_key)` payment proofs on receipts; refunds require user-supplied destination address. | | **Ethereum L1** | self-hosted Erigon `^2.60` plus public RPC fallbacks (Alchemy, Infura, Ankr); `ethers: ^6.13.0`; `viem: ^2.21.0` | Native ETH, USDC, USDT, DAI on Ethereum L1; BIP44 xpub-derived per-invoice addresses; multi-RPC N-of-M consensus; ENS refund-address resolution. | | **Cardano (ADA)** | `cardano-node` `^9.2` (self-hosted, Haskell); `cardano-wallet` `^2024.11.18` HTTP service (watch-only); `@cardano-sdk/core: ^0.36.0` | CIP-1852 (`m/1852'/1815'/0'/0/`) per-invoice payment addresses; 15 / 30 confirmation tiers; UTXO-set polling; ADA only (native multi-asset disabled for V1). | | **Ergo (ERG)** | `ergo-node` `^5.0` (self-hosted, Scala) plus `ergo-wallet-api` watch-only; `@ergoplatform/ergo-lib-wasm-nodejs: ^0.28.0` | BIP44 (`m/44'/429'/0'/0/`) per-invoice P2PK addresses; 5 / 10 / 30 confirmation tiers; NIPoPoW-friendly receipt format. | #### Tier B — decentralized with documented caveats; self-hosted where practical + multi-RPC consensus | Asset / rail | Catalog version / tooling | V1 use | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | **Bitcoin Lightning** | LND `^0.18` / Core Lightning `^24.11` / Phoenixd `^0.5` (operator picks one self-hosted backend behind BTCPay Server) | BOLT11 invoices; hold-invoices for refundable flows; AMP/keysend for metered streaming. | | **Base** | `viem: ^2.21.0`; self-hosted op-geth + op-node OR multi-RPC consensus across Alchemy + Infura + Ankr; canonical USDC + USDT + DAI contract registry | Native ETH + USDC + USDT + DAI on Base; rollup-safe-head reorg depth (`~150` blocks). | | **Arbitrum** | `viem: ^2.21.0`; self-hosted Nitro node OR multi-RPC consensus; canonical USDC + USDT + DAI contract registry | Native ETH + USDC + USDT + DAI on Arbitrum; reorg depth (`~50` blocks). | | **Optimism** | `viem: ^2.21.0`; self-hosted op-geth + op-node OR multi-RPC consensus; canonical USDC + USDT + DAI contract registry | Native ETH + USDC + USDT + DAI on Optimism; reorg depth (`~120` blocks). | | **Polygon PoS** | `viem: ^2.21.0`; self-hosted bor + heimdall OR multi-RPC consensus across Alchemy + Infura + Ankr; canonical USDC + USDT + DAI contract registry | Native MATIC + USDC + USDT + DAI on Polygon; heimdall-checkpoint finality (`~256` blocks). | | **Solana** | `@solana/web3.js: ^1.95.0`; `@solana/spl-token: ^0.4.0`; self-hosted Solana RPC node (`solana-cli ^1.18`) plus multi-RPC consensus across Helius / QuickNode / Triton; Solana Pay (`@solana/pay: ^0.2.0`) | Native SOL + USDC-SOL + USDT-SOL; per-invoice ed25519 derivation; `confirmed` / `finalized` tier policy. | #### Tier C — centralized trust required; accepted with explicit invoice disclosure | Asset / rail | Catalog version / tooling | V1 use | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Tron** | `java-tron: ^4.7` (self-hosted) plus multi-RPC consensus across TronGrid + GetBlock; `tronweb: ^6.0.0` | USDT-TRC20 only at V1 (the dominant USDT rail by global volume). 19-block confirmation policy (≈1 min). Per-invoice address derivation; Tier-C disclosure mandatory on every invoice. | | **TON** | `mytonctrl` (self-hosted) + `ton-http-api: ^4.4` plus multi-RPC consensus across `tonapi.io` + `toncenter.com`; `@ton/ton: ^15.0.0`; `@ton/crypto: ^3.3.0` | Native TON + USDT-TON (jetton); `v4r2` per-invoice wallet contract derivation; Telegram @wallet deep-link integration. | #### Stablecoin accept-list (per chain) | Stablecoin | Issuer / trust class | Chains accepted at V1 | | ---------- | --------------------------------------- | ----------------------------------------------------------------------------------- | | USDC | Circle (central, freeze authority) | Ethereum L1, Base, Arbitrum, Optimism, Polygon, Solana | | USDT | Tether Ltd. (central, freeze authority) | Ethereum L1, Base, Arbitrum, Optimism, Polygon, Tron (TRC-20), Solana, TON (jetton) | | DAI | MakerDAO (decentralized, no freeze) | Ethereum L1, Base, Arbitrum, Optimism, Polygon | #### Cross-cutting tooling | Concern | Catalog version / tooling | V1 use | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Cold-spend signing | Trezor Suite Lite / Ledger Live / Coldcard Q via PSBT (BTC + LTC); Safe `{Core,Wallet}` (every EVM chain); Monero CLI multisig MMS; Solana SPL multisig; TON multisig contract; Cardano Plutus-script multisig; Ergo P2S multisig; Tron multisig contract | Air-gapped signing station for refunds and sweeps; 2-of-3 multisig vault per chain family above sweep threshold. | | Price oracle | Kraken REST + CoinGecko REST + Uniswap v3 TWAP (`@uniswap/v3-sdk: ^3.13.0`); Tor egress via `socks-proxy-agent: ^8.0.0` | Fiat-rate aggregation with median selection; invoice-time rate lock; spread captured for fraud analysis. Non-EVM natives (XMR, ADA, ERG, SOL, TON, LTC, TRX) use Kraken + CoinGecko only. | | Test substrate | `bitcoind -regtest`; `litecoind -regtest`; Anvil (`foundry: ^1.0`) per EVM chain; `monero-stagenet` Docker image; Solana `solana-test-validator`; TON sandbox via `@ton/sandbox: ^0.27.0`; Cardano `preview` testnet; Ergo testnet; Tron Nile testnet | End-to-end test substrate including induced reorgs and outage simulation. | | Trust-tier registry | `libs/oshun/payments-bridge/src/trust-tier-disclosure/` | Per-rail decentralization tier (A / B / C) and per-asset issuer-trust class drive invoice-surface disclosures and tenant policy gating. | | V1 entitlement bridge | `libs/oshun/payments-bridge/` | Maps Aje merchant invoices onto V1 entitlement events; oracle aggregation across `@aje/oracles` + off-chain sources; cold-spend queue; receipt signing; Telegram @wallet handoff; crisis-state suppression. | Aje libraries run inside `libs/aje/` and the V1 bridge runs inside `libs/oshun/payments-bridge/`. The bridge emits entitlement-grant and refund events through `libs/shared/event-bus` topics shared with the fiat adapter, keeping downstream consumers rail-agnostic. ### V1.x optional — fiat rails | Provider | Catalog version | V1.x optional use | | --------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | Stripe | `stripe: ^17.0.0` | Subscriptions, entitlement upgrades, billing portal entry from profile/settings. | | Telegram Payments | (V1.x optional) | Entitlement upgrade flows in Telegram channel; gated by `@oshun/inbound-integrations/payment`. May also surface a crypto invoice via bot. | | Payment connector framework | `libs/shared/inbound-integrations/src/payment.ts` | Tenant-provided fiat processors. | Billing-action reversal, entitlement suspension, trial-expiry behavior, payment-method update reminders (fiat), and renewal-invoice reminders (crypto) are all documented in features.md § Support, Entitlements, Billing and § Crypto Payments — Non-Custodial Entitlement Settlement, and tracked in TODOS § 23 and § 23.1. Aje's own feature catalog lives in [`DOMAINS/aje/features.md`](../docs/domains/aje/deep-dive/features.md) and architecture in [`DOMAINS/aje/architecture.md`](../docs/domains/aje/deep-dive/architecture.md). --- ## 14. Observability and Telemetry | Stack | Catalog/version | V1 use | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | OpenTelemetry | `@opentelemetry/api: ^1.9.0`, `core: ^1.28.0`, `resources: ^1.28.0`, `exporter-trace-otlp-http: ^0.55.0`, `context-async-hooks: ^1.28.0`, `propagator-aws-xray: ^2.2.0` | Structured tracing across shell, BFF, Sophia, Iris, Psyche, Lilith, Isis, and domain services. | | Sentry | `@sentry/node: ^8.0.0` | Error capture for backend services and mobile crash reporting. | | Pino | (via `@oshun/logging`) | Structured logging. | | Prometheus | dev compose image | Metrics scraping. | | Grafana | dev compose image | Dashboards for V1 SLOs. | | Jaeger | dev compose image; `OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4318/v1/traces` | Trace UI in dev; production exporter swappable. | Per-channel SLA monitor (`libs/shared/queue/src/sla-monitor.ts`) feeds the launch-readiness dashboards. --- ## 15. Object Storage and CDN | Service | V1 use | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | MinIO (dev) | Buckets for Tara content (`TARA_CONTENT_BUCKET=tara-content`, `TARA_CDN_URL=http://localhost:9000/tara-content`), Isis outputs, Living Scenes renders, source ingestion, exports. | | AWS S3 (prod) | Same role as MinIO at production scale. | | CloudFront / CDN | Static asset delivery and generated media to global users. | | AWS SDK packages | `@aws-sdk/client-s3 ^3.600.0`, `@aws-sdk/lib-storage ^3.600.0`, `@aws-sdk/s3-request-presigner ^3.600.0`. | --- ## 16. Search and Vector Stores | Store | V1 use | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Elasticsearch | Universal search across rituals/practices/concepts/passages/claims/sources/notebooks/collections/programs/sky-events/courses/lessons/learning-artifacts. SDK: `@elastic/elasticsearch ^8.17.0`. | | pgvector | Primary embedding store for Sophia, Nisaba concept graph, recommendations. | | Qdrant | Secondary vector store when pgvector cardinality is exceeded. | --- ## 17. Concept and Knowledge Graph | Store | V1 use | | ---------- | ------------------------------------------------------------------------------------------------------------------------ | | Neo4j | Nisaba concept graph (nodes + edges, lexicon, morphology), Metis knowledge-graph promotion, cross-domain lineage chains. | | PostgreSQL | Authoritative references for concept-graph nodes/edges (Zod-backed) with Neo4j as the read-optimized graph view. | --- ## 18. Domain-Specific External APIs ### Nyx — sky predictions | Source | Where it's used | | --------- | ------------------------------------------------------ | | NASA JPL | Orbital data for conjunctions, occultations, transits. | | IMO | Meteor shower predictions. | | IERS | Earth-orientation parameters; precise event timing. | | NOAA SWPC | Space-weather (aurora) predictions. | | Weather | Cloud cover and observation quality bands. | | Bortle | Sky-darkness data for observation-quality bands. | All sources are declared in the `PredictionSourceRef` contract so customers inspecting a sky event see exactly which external authority predicted it. No NYX-specific HTTP base URLs are pinned in `.env.example` yet; pre-launch work should add `NYX_*_URL` entries alongside the per-source API keys. ### Nisaba — scholarly sources | Source / endpoint | Env var | V1 use | | ----------------- | ------------------------ | ------------------------------------------------- | | Sefaria API | `NISABA_SEFARIA_API_URL` | Passage retrieval, translation alignment. | | CDLI API | `NISABA_CDLI_API_URL` | Cuneiform digital library. | | IIIF | `NISABA_IIIF_BASE_URL` | Manuscript image delivery (operator-side import). | ### Veritas — source quality and counterclaim feeds External feeds are operator-curated (peer-reviewed databases, retraction watch sources, fact-check syndications). Veritas requires a `SourceKind` declaration on every source and a per-source reviewer attestation. --- ## 19. Provenance and Synthetic-Content Verification | Standard / library | V1 use | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **C2PA** | Contract-level fields (`c2paManifestPresent`, `c2paManifestIssuedAtUnixSeconds`) on watermark/provenance bundles in `libs/oshun/persona-registry/src/watermark-provenance.ts`, **plus a shipped mint/verify path (2026-07-06, closes the §19 launch gap)**: `c2pa-node ^0.5.26` is pinned in the pnpm catalog and wrapped by `@oshun/c2pa-export` (`libs/oshun/c2pa-export`) — fail-loud signer resolution from `OSHUN_C2PA_EXPORT_*` env, standards-compliant JUMBF/COSE embed, typed verify — wired into the Living Scene share/export route with production fail-closed behavior. SDK quirk to know: the 0.5.x native binding timestamps every signature, so signing requires egress to the configured TSA (default DigiCert). References: `https://opensource.contentauthenticity.org/docs/durable-content-credentials` (cited in `libs/calliope/compliance/src/services/deepfake-prevention-guard.ts`). | | **Watermarking** | Per-render watermark hash recorded in `ProvenanceBundle`; visual + audio watermarks on customer-tier outputs. Realism / impersonation thresholds at `libs/oshun/persona-registry/src/realism-impersonation-thresholds.ts` evaluate `requireC2paManifest` at release-gate time. | | **Audit platform** | `@oshun/audit-platform` records every consent change, deletion, persona publish, generation bundle. | --- ## 20. Cloud Providers (Production deployment; dev runs entirely in compose.) | Provider | V1 role | | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Hetzner | **Primary hosting: the entire V1 platform runs on ONE Hetzner Cloud box (CCX23)** as docker-compose stacks — Oshun + Metis + Psyche backends AND the Next.js front-ends behind a Caddy TLS edge (host-routed on `.`), with on-box Postgres (pgvector/pg16), Redis 7, and MinIO (S3 API at `s3.`, presigned-URL compatible via `OSHUN_ASSET_STORE_ENDPOINT` path-style). Images on **GHCR** (`ghcr.io/greychimp/oshun/`). One deploy path: `.github/workflows/deploy-hetzner.yml` (build → SSH → `deploy/v1/hetzner/scripts/deploy.sh`: pull, Prisma schema apply, roll, health-gate, smoke). Staging auto-deploys from `main` (affected services only); production deploys from `v*` tags/releases behind the `production-approval` environment gate. Runbook: `deploy/v1/hetzner/README.md`; decision record: `V1/planning/HETZNER_SINGLE_BOX_2026-07-09.md`. | | AWS | **Dormant/standby** since 2026-07-09 (superseded by the Hetzner single box). The full ECS Fargate stack remains applyable — `infrastructure/terraform/` (single root module: Fargate cluster + shared ALB + Cloud Map, RDS pgvector, ElastiCache, S3, ECR) and the dispatch-only `.github/workflows/deploy-ecs.yml` — for a deliberate return to AWS at scale. The pnpm catalog still pins the S3-family SDKs (`@aws-sdk/client-s3`, `@aws-sdk/lib-storage`, `@aws-sdk/s3-request-presigner` `^3.600.0`) and `@aws-sdk/client-cloudwatch ^3.600.0`; the S3 clients now speak to MinIO through the same interface. Cost model of the retired stack: `V1/planning/IAC_CICD_AUDIT_2026-07-04.md`. | | RunPod | GPU cloud for Isis/ComfyUI/SDXL/Flux/custom inference endpoints. `RUNPOD_API_KEY` in Secrets Manager; endpoint IDs stored alongside. | | GCP | Firebase Cloud Messaging (push), Vertex AI (supplemental models). | | Azure | Optional Azure OpenAI endpoint (swap-in for the OpenAI SDK). | --- ## 21. Containerization and Local Development Per `CLAUDE.md` § "Local Development": ```bash docker compose -f docker/docker-compose.dev.yml up -d docker compose -f docker/docker-compose.dev.yml ps pnpm install ``` Core services (always on): `postgres` (pgvector/pgvector:pg16, port 5432), `pgbouncer`, `redis` (6379), `minio` (9000/9001), `mailpit` (1025/8025). Optional profiles: | Profile | Services | | --------------- | ---------------------------------- | | `search` | Elasticsearch | | `vectors` | Qdrant | | `streaming` | Kafka + Zookeeper | | `graph` | Neo4j | | `observability` | Prometheus + Grafana + Jaeger | | `tools` | redis-commander, pgadmin, kafka-ui | | `all` | All of the above | Per-domain compose files exist for `brigid`, `cybele`, `freya`, `iris`, `lakshmi`, `maat`, `saraswati` (out-of-V1 domains; runnable independently). V1 domain databases pinned in `.env.example` today: `TARA_DATABASE_URL`, `TARA_REDIS_PREFIX`, `TARA_CONTENT_BUCKET`, `TARA_CDN_URL`, `NISABA_DATABASE_URL`, `NISABA_REDIS_PREFIX`, plus the shared `oshun_dev` database used by services without a dedicated per-domain database. **Gap:** `ARETE_DATABASE_URL`, `VERITAS_DATABASE_URL`, `NYX_DATABASE_URL`, and `METIS_DATABASE_URL` are **not yet documented in `.env.example`**. Either: (a) those domains run against the shared `oshun_dev` database for V1 launch, in which case `.env.example` should declare that explicitly, or (b) they need per-domain database URLs added before launch. Metis runs inside `apps/metis/{web,admin,api-gateway,worker}` against its own per-service database URLs. --- ## 22. CI/CD and Build Tooling | Tool | V1 use | | -------------------------- | --------------------------------------------------------------------------------------------------------- | | pnpm + workspaces | Dependency management; catalog references in `pnpm-workspace.yaml`. | | Nx | Project graph and task running. (Note: `CLAUDE.md` documents Nx-bypass workflows for worktree conflicts.) | | TypeScript | Type-check via `tsc --noEmit` or per-project (`tsc -p tsconfig.typecheck.json`). | | ESBuild | BFF and most service bundles (`esbuild ... --platform=node --format=esm --target=node22`). | | esbuild + SWC | Web and admin app builds (via Next.js). | | Husky | Pre-commit hooks; lint-staged. | | ESLint | Lint at commit + CI (project-wide config `eslint.config.js`). | | Prettier | Format at commit (config `prettier.config.js`). | | GitHub Actions | CI pipelines under `.github/workflows/` (lint/test/build/deploy/RunPod endpoints). | | OpenAPI spec drift | CI gate: runtime-vs-spec drift fails the build (TODOS § 1.5). | | Contract-persistence drift | CI gate: Zod vs. Prisma drift fails the build (TODOS § 1.4). | --- ## 23. Testing Tooling | Tool | V1 use | | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | Vitest | Unit and integration tests (`@vitest/coverage-v8: ^1.6.1`). Run `npx vitest run path/to/test.ts` to bypass Nx. | | Playwright | E2E across customer web/admin web; accessibility (`@axe-core/playwright: ^4.11.0`); visual regression. | | Claude in Chrome (browser automation MCP) | Frontend visual + functional testing per CLAUDE.md. | | Tenant isolation | `tests/security/tenant-isolation/` — launch-gating cross-tenant leakage suite. | | Adversarial stub scan | Mandatory pre-commit grep across changed source (CLAUDE.md § Adversarial Verification Pass). | | Eval sets | Per-surface evaluation harnesses for assistant, generation, Living Scenes, search, recommendations. | --- ## 24. Security and Secrets | Layer | V1 use | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | AWS Secrets Manager | RunPod endpoint IDs, provider API keys, JWT secrets in production. | | AWS KMS | Customer-managed encryption keys for Secrets Manager, S3 buckets, RDS at rest. | | `.env` files | Local dev only. `.env.example` documents every required variable. | | Step-up auth | Required for data export, data deletion, admin inspection, persona publish, generation governance changes. | | Provenance + watermark | Required on every customer-exported artifact (C2PA + watermark hash). | | Audit log | `@oshun/audit-platform` — append-only; queried by admin web review/incident/DSAR/deletion workflows. | | Synthetic-content indicators | Surfaced on every public profile, share, and embed. | | Residency enforcer | Blocks cross-region access without explicit consent (`@oshun/data-residency`). | | Tenant isolation | Cache keys, feature flags, experiments, search results all tenant-scoped. Launch-gating tests in `tests/security/tenant-isolation/`. | --- ## Cross-References - Product surface and feature scope — [`V1/features.md`](./features.md). - Implementation source of truth — [`V1/TODOS.md`](./TODOS.md). - V1 runtime architecture — [`V1/ARCHITECTURE.md`](./ARCHITECTURE.md). - Whole-monorepo dependency registry (out-of-V1 domains) — [`/DEPENDENCIES.md`](../DEPENDENCIES.md). - Whole-monorepo architecture — [`/ARCHITECTURE.md`](../ARCHITECTURE.md). - Domain reference — [`/DOMAINS.md`](../DOMAINS.md). - Project conventions — [`/CLAUDE.md`](../CLAUDE.md).