Eve library

Shared — Systems Deep Dive

Guide

Revision 1

On this page

The libs/shared/ area: ~47 cross-cutting Nx libraries (mostly @oshun/*) that every domain and app composes — the platform's substrate of auth, data access, observability, messaging, security, AI plumbing, and content-integrity primitives.

What this area is#

libs/shared/ is the bottom of the Oshun dependency graph for behaviour (where libs/contracts/ is the bottom for types). Each subdirectory is its own Nx project with its own project.json, package.json, and src/ barrel; almost all publish under the @oshun/* scope (two — shared-documentation and shared-release-management — keep an internal shared-* Nx name). Their Nx tags classify them mostly as layer:infra (e.g. @oshun/ai, @oshun/cache, @oshun/infrastructure), a few as layer:contracts (@oshun/types, @oshun/errors), and a handful as layer:domain (@oshun/audit-platform).

The area is not one coherent package but a catalogue of independently-versioned utilities. Reading the barrels, they cluster into a few sub-systems:

  • Foundations — @oshun/types (zero-dependency type spine), @oshun/errors, @oshun/config, @oshun/crypto.
  • Data & messaging — @oshun/database, @oshun/cache, @oshun/queue, @oshun/storage, @oshun/event-bus, @oshun/websocket, @oshun/migration, @oshun/deletion-fanout.
  • Service plumbing — @oshun/http-client, @oshun/service-discovery, @oshun/traefik-config, @oshun/health, @oshun/rate-limit, @oshun/inbound-integrations.
  • Observability — @oshun/logging, @oshun/metrics, @oshun/tracing, shared-documentation.
  • Identity & security — @oshun/auth, @oshun/auth-primitives, @oshun/identity, @oshun/security, @oshun/data-residency, @oshun/region-rules.
  • AI / GPU / ML — @oshun/ai, @oshun/ai-advanced, @oshun/ml, @oshun/gpu-dispatcher, @oshun/runpod-client, @oshun/vision-llm, @oshun/ocr, @oshun/layout-analyzer.
  • Content integrity & governance — @oshun/content-eval, @oshun/content-quality-judge, @oshun/content-release-gates, @oshun/content-security, @oshun/content-signing, @oshun/encoding, @oshun/audit-platform, @oshun/review-persistence, shared-release-management.
  • Misc / specialised — @oshun/infrastructure (Yemaya-origin), @oshun/tara-live-class-booking (a single-domain booking model that landed in shared), @oshun/testing.

How it fits the wider system#

These libraries are consumed by every app (apps/oshun/bff, admin, the web shells) and by the capability domains (Yemaya, Lilith, Isis, Sophia, Hathor, Bellona, …). The dependency direction is strictly downward: shared libs may depend on @oshun/contracts, @oshun/types, and third-party packages, but never on a domain's business logic — so a domain can swap implementations without the substrate changing. Several libraries are deliberately I/O-light and inject their side-effecting collaborators (e.g. @oshun/data-residency takes an audit publisher; @oshun/event-bus and @oshun/websocket take a Redis client), which keeps them testable and lets the same code run in the BFF, a worker, or a domain service. Walk the "used by" edges on any node below to see exactly who depends on it.

A note on honesty for the content/AI clusters: many of these libs follow the repo's "fail-loud seam" pattern — real deterministic logic plus typed boundaries that refuse to fabricate when a model/provider/credential is absent (e.g. @oshun/content-eval's model-metric seams, @oshun/ocr's "tiers do NOT silently fail over"). Where that is the case the blurb says so.

Entity reference#

@oshun/ai-advanced#

Advanced/experimental AI tooling layered above @oshun/ai: src/ ships an AdapterManager (modular LLM adapter registry), a BenchmarkManager with standard tasks, an automatic model-selector, an edge-manager (on-device inference orchestration), and a research-manager — a substantial ~3.8K-line package with branded IDs in types.ts.

@oshun/ai#

The platform AI integration layer (~18K lines). Real provider clients in src/providers/ (anthropic, openai, google, xai, ollama), a local-inference stack (local/model-manager, inference-engine, quantization), an agent-loop (loop + tool-registry + structured-output + reflexion + budget), prompt management (prompts/versioning, optimization), plus cache and a quality/ML router. Heavily implemented, not a facade.

@oshun/audit-platform#

The canonical platform-wide audit ingestion and immutable-storage domain (layer:domain, ~25K lines). Every event validates against CanonicalPlatformAuditEventSchema from @oshun/contracts (ADR-0023); the store is append-only (amend by re-ingesting with metadata.amends). Rich modules: hash-chain, member-timeline, provenance-badges, synthetic-media-labeling, training-data-source-evidence, mandatory-human-approval, retention, plus investigation/evidence export.

@oshun/auth-primitives#

Low-level auth building blocks (~4.6K lines): jwt, session, password (hashing), totp, api-key, oauth-client/oauth-revoke, token-refresh, token-audit, platform-roles, and tenant-isolation. These are the composable primitives the higher-level @oshun/auth and @oshun/identity build on.

@oshun/auth#

The unified authentication/authorization service (~3.1K lines): an AuthService (login/registration/token management), RBAC + permission checks, account lockout protection, and framework-agnostic middleware (requireRole, requirePermissions). Sits above @oshun/auth-primitives.

@oshun/cache#

Caching library (~3.9K lines): redis-client, memory-cache, a with-cache wrapper, distributed-lock, circuit-breaker, pubsub, invalidation, a key-builder, and metrics. Real Redis and in-memory implementations behind a common CacheClient type.

@oshun/config#

Configuration management: env reading/parsing (env.ts), Zod validation schemas.ts, typed loader (loadServiceConfig, loadDatabaseConfig), a large features.ts feature-flag surface, experiment-guardrails, and a legacy compatibility module. Note: the directory also contains checked-in .d.ts/dist artifacts alongside the .ts sources.

@oshun/content-eval#

Real, type-specific content-generation eval metrics (Phase 0.2). Deterministic metrics computed from first principles and golden-tested: image PSNR/SSIM, video temporal consistency, mesh topology (manifold/watertight/poly/UV), text citation P/R/F1, audio LUFS. Perceptual/model metrics (CLIP, aesthetic, VMAF, PESQ, NLI) are honest fail-loud seams via MetricModelNotConfiguredError — never fabricated.

@oshun/content-quality-judge#

The calibrated "taste signal" keystone (~6.6K lines, ~32 modules): versioned anchored rubrics, a judge engine + judge-panel, slop penalty + slop-maintenance, calibration, quality-gate, best-of-n/self-refine, reward-model, drift, arc-coherence/continuity, corpus-diversity, and a benchmark harness. (The barrel re-exports several modules — e.g. judge-engine, quality-gate — that sit alongside the ~23 files read here.)

@oshun/content-release-gates#

One unifying gate schema for the five disconnected quality systems the agentic-content audit found (Yemaya validators, Isis gates, V3/V6/V7 gates). A ReleaseGateService turns each check into a GateDefinition; content promotes only when every required gate passed plus (when demanded) a named human signoff. champion-challenger.ts ramps a new generator config only on a one-sided two-proportion z-test.

@oshun/content-security#

Content-protection plans and manifests (~2.7K lines): forensic watermarking (invisible image/audio/video/document plans + robustness evaluation + source identification), a large provenance module, and a drm module. These produce typed plans/manifests and capability descriptors rather than embedding pixels in-process.

@oshun/content-signing#

A single ~148-line Ed25519 + SHA-256 content signer (ledger §D.1) that de-duplicates the isis C2PA provenance signer and the V3 concert-track signer. Real node:crypto Ed25519 over canonical bytes + SHA-256 binding; exposes both an async byte-oriented ClaimSigner/ClaimVerifier and sync ed25519SignBase64/ed25519VerifyBase64 helpers. Small but real, not a stub.

@oshun/crypto#

The unified crypto facade (~5K lines) — the only entrypoint internal code should use. src/index.ts wraps audited noble primitives (@noble/hashes/curves/ ciphers): keccak256/sha256/sha512/blake3, secp256k1, ed25519, AES-GCM, KDFs, ECDH (zero in-house crypto). Plus pluggable secrets/ managers (local/AWS/GCP/ Azure) and keystore/ backends (local/AWS-KMS/GCP-KMS/Azure-KV).

@oshun/data-residency#

V1-PRIV-018 region/residency enforcement (~670 lines). The enforcer reads rule tables from @oshun/contracts and emits canonical audit events via an injected publisher — intentionally I/O-light; it only decides whether a proposed transfer is allowed. Also dsr-routing, traffic-shaping, and home-zone. Consumed by the BFF, admin, and @oshun/audit-platform.

@oshun/database#

Unified DB utilities (~6.2K lines): postgres-client, redis-client, a connection-pool (legacy-pool), transaction helpers, a query-builder, migration + legacy-migrations, connection-string parsing, health, and metrics. Checked-in .d.ts artifacts accompany the sources.

@oshun/deletion-fanout#

The shared account-deletion fan-out core (scope:shared so any domain can run its own deletion consumer). Holds the per-service eraser port, signed Ed25519 attestation primitives, an event-driven orchestrator + transport port, a Redis bus transport, domain consumer registration, an env-resolved signer, and a runner composition root. These fan-out primitives moved out of @oshun/privacy; consumers import them from @oshun/deletion-fanout directly.

shared-documentation#

A single architecture-documentation module (src/architecture/architecture.ts, ~454 lines): typed taxonomies for component diagrams and dependency graphs — ArchComponentType, DiagramFormat (mermaid/plantuml/d2/dot/ascii), ConnectionType. Narrow in scope (one file + its spec); models architecture documents, it does not render the docs site.

@oshun/encoding#

Video-encoding quality plumbing (~3K lines): real PSNR/SSIM/multi-scale-SSIM calculators, a Netflix-VMAF ffmpeg plan builder + JSON report parser (NETFLIX_VMAF_MODEL_REGISTRY), codec-support, imf-delivery, shot-optimization, a video-encoder, and quality-dashboard manifests.

@oshun/errors#

Standardized error handling (layer:contracts+layer:infra): base error classes with HTTP status codes (base.ts, http.ts), domain-specific errors (domain.ts), a codes.ts registry, and utilities (wrapError, etc.) with optional Sentry integration. Foundational and widely imported.

@oshun/event-bus#

Cross-domain event bus over Redis pub/sub (~4.1K lines): type-safe publish/ subscribe with wildcard patterns, retry with backoff, a dead-letter queue, event persistence/replay, and correlation/causation tracking. A large topic-registry.ts enumerates topics; outbound-delivery.ts and a webhook-simulator handle external delivery.

@oshun/traefik-config#

Unified API-gateway configuration generator (~2K lines): typed builders (ServiceBuilder, RouteBuilder, GatewayConfigBuilder, plus service/route/ gateway helpers), a traefik.ts config emitter, per-domains configuration, and a small cli.ts. Generates gateway config; it is not itself the running proxy.

@oshun/gpu-dispatcher#

GPU job dispatcher for RunPod Serverless (~7K lines): a dispatcher with queuing and endpoint routing by job type, plus production-grade retry, timeout, fallback, circuit-breaker, cost-tracker, metrics, tracing, validation, and a job-store. Composes @oshun/runpod-client.

@oshun/health#

Health-check utilities for microservices (~1.4K lines): a health-manager registry, liveness/readiness probes, and dependencies checks, with typed HealthStatus/HealthReport/ProbeType surfaces.

@oshun/http-client#

Resilient HTTP client (~6K lines incl. .d.ts): http-client core plus retry, timeout, circuit-breaker, interceptors, idempotency keys, tenant-context propagation, distributed tracing, and an ssrf-guard. Substantial, production-oriented outbound HTTP.

@oshun/identity#

Shared identity library used by every capability domain (validate tokens, read canonical claims, enforce role/permission decisions; issuance stays with the auth service). Ships JwtService, authenticate/authenticateService middleware, mtls, node-http helpers, and V2 modules (v2-account-binding, v2-entitlement-claims). Documented in README.md against ADR-0003/0004.

@oshun/inbound-integrations#

Large external-integration surface (~13K lines): LMS/LTI (lms, lti-verification), SCORM RTE (scorm-rte, scorm-2004-rte), oneroster, calendar (+ Google transport), payment, notification, byom/byom-model (bring-your-own-model), identity, health, and telemetry. Each is a sizable real module.

@oshun/infrastructure#

A Yemaya-origin infrastructure pack now under shared (~5.9K lines; its barrel docblock still reads @yemaya/infrastructure). Ships a performance-manager, security-manager, monitoring-manager, and calliope/calliope-operations (Calliope is a Yemaya sub-domain) over branded IDs in types.ts. Real and large, but domain-flavoured rather than fully platform-neutral.

@oshun/layout-analyzer#

Canonical document-layout analyser (V1-P2-0064/0066). OshunLayoutAnalyzer decomposes a rendered page into the PubLayNet region taxonomy (DOCUMENT_REGION_CLASSES) via the canonical vision-LLM client; map.ts computes mAP@0.5 as the verification metric. ~985 lines.

@oshun/logging#

Structured logging (~3K lines) on Pino: createLogger/log, multiple transports (console, file, http, elasticsearch, tcp), sampling strategies, a request-logger middleware (Express/Fastify/Koa), OpenTelemetry hooks, and PII redaction.

@oshun/metrics#

Prometheus-compatible metrics (~1.7K lines): a registry, typed Counter/Gauge/Histogram/Summary configs and interfaces, helpers, and a metrics server.

@oshun/migration#

Cross-domain data-migration utilities (~4.9K lines): a MigrationRunner + MigrationRegistry, checkpoint/id-mapping stores (file + memory), integrity/cross-domain-reference checks, and concrete scripts/ for real cutovers (yemaya-engine→bellona, yemaya-generation→isis, lilith-ingestion/rag→ sophia, lilith-sophia-cutover) plus the OSHUN-V1 shared-object plan generator.

@oshun/ml#

A compact (~890-line) ONNX inference runtime: loadModel/tensor over onnxruntime-node and onnxruntime-web adapters (plus a mock adapter for tests), SHA-256 model-integrity verification (expectedSha256), a provider preference list (webgpu/webnn/wasm), a model registry/loader, and a benchmark. Small but real, with an honest mock adapter at the dependency boundary.

@oshun/ocr#

Canonical OCR client facade (V1-P2-0060, ~516 lines): OshunOCRClient over three tiers — tier1_tesseract (Tesseract.js WASM, default, real TesseractOCRBackend), tier2_vision_llm, and tier3_cloud_ocr (Google Document AI / Azure) — which explicitly do NOT silently fail over.

@oshun/queue#

BullMQ-based job queue (~4.5K lines): a queue + worker, priorities, retries, a dead-letter-queue, a durable-queue, an sla-monitor, and a full memory-queue implementation for testing behind the same types.

@oshun/rate-limit#

Rate limiting / throttling (~5.2K lines): sliding-window, fixed-window, token-bucket, adaptive, graceful, and throttle limiters; quota, abuse-controls, exemptions, bypass middleware, Hono middleware, and a monitoring/alerts surface. Redis-backed for distributed limiting.

@oshun/region-rules#

A thin facade: src/index.ts is a one-line re-export of v2-regional-content-rules.ts (~405 lines), which holds the V2 regional content-rule tables. Effectively one real module behind a barrel.

shared-release-management#

Surface-scoped release safety (V1 §28.8, ~824 lines): RollbackPlan/RollbackStep schemas, a rehearsal engine, and canonical-plans for the six V1 surfaces (shell, admin, grounding, assistant, persona, generation). Internal Nx name is shared-release-management.

@oshun/review-persistence#

Canonical persistence for review packages (V1-GRC-001, ~4.2K lines): maps the @oshun/contracts Zod schemas and the isis ReviewPackage Prisma model into a typed, validated API. Guarantees schema validation on every row, deep-cloned returns, slug/id uniqueness, updatedAt refresh, and ADR-0029 stage/decision/ delegation invariants. Includes a stage-graph-repository, decision-lifecycle, delegation-policy, an in-memory store, and __fixtures__.

@oshun/runpod-client#

Type-safe RunPod Serverless API client (~1.7K lines): a client with runAndWait, status polling, typed errors, and retry logic. The lower-level transport that @oshun/gpu-dispatcher composes.

@oshun/security#

Security utilities (~4.6K lines): a database-backed audit-logger (with actor helpers and batching), a content/file scanner, a secret-manager with rotation, and ip-minimization. Distinct from @oshun/audit-platform (which is the canonical compliance audit domain); this is the per-service security toolkit.

@oshun/service-discovery#

Redis-backed service discovery (~1.5K lines): createServiceDiscovery with register/lookup, a ServiceNames catalogue, pluggable backends, a hash-ring for consistent hashing, and a health-probe.

@oshun/storage#

Object-storage utilities (~2.7K lines): an s3-client (S3/MinIO), a local-client (filesystem), presigned-URL generation, file-manifest types, and utils, behind a common StorageProvider/StorageConfig surface.

@oshun/tara-live-class-booking#

A single-domain booking model that lives in shared (one ~488-line src/index.ts): typed surfaces for Tara live yoga-class booking — lineage tags (iyengar/krishnamacharya/…), lineage citations/disclosures, and a lineage fund preference. Notably honest about trust signals: verifiedAtIso is "set only by a real Sophia verification read; null until one has actually run" (audit B15). Pure types/logic, no I/O.

@oshun/testing#

Comprehensive test-utility library (~4K lines): mock factories (createMockLogger/HttpClient/RedisClient/DatabaseClient/EventEmitter), fixture generators (createUser/createContent + a factory builder), assertion/ async helpers, Testcontainers wrappers (PostgresTestContainer/ RedisTestContainer), Vitest config builders, Playwright axe accessibility helpers, contract-testing (openapi-contract), and a fuzz/malicious-input corpora suite (§28.16). Mocks live at dependency boundaries by design.

@oshun/tracing#

OpenTelemetry distributed tracing (~3.8K lines): a tracer, context propagation, AWS xray exporter, span decorators, and middleware (generic + hono), over branded TraceId/SpanId/CorrelationId types.

@oshun/types#

The foundational, zero-external-dependency type spine (layer:contracts, ~6.4K lines). Base types (Result, BaseEntity, branded IDs), user, api, config, events, contracts, a large legacy module, and a rich creative/ namespace (agent/world/asset/storyboard/collaboration/generation/ script/character/schedule). Everything else can depend on it.

@oshun/vision-llm#

Canonical vision wrapper (V1-P2-0064, ~1.7K lines): OshunVisionLLMClient is a convenience layer over the isis LLM client for vision-locate tasks — it owns prompt-shape, image normalisation, structured-output parsing, and the VisionLocateResult envelope, while provider routing/retries/cost/quotas stay in the gateway.

@oshun/websocket#

Real-time WebSocket server (~5.4K lines): a server with channel-based subscribe/unsubscribe, a Redis redis-adapter for cross-server broadcasting, presence/state, rooms, JWT auth, per-connection ratelimit/limits, a delivery queue, and metrics.

oshun-feature-store#

ML feature-store layer (libs/shared/feature-store/src): a FeatureCatalog + FeatureComputationEngine (windowed aggregations like averageOverWindow) over two online-store backends — RedisOnlineFeatureStore and a Feast-compatible pair (FeastFeatureServerClient, FeastOnlineFeatureStoreAdapter) — plus an offline store for point-in-time training reads.

oshun-streaming#

Kafka streaming backbone (libs/shared/streaming/src): BackpressuredTypedKafkaPublisher and ExactlyOnceKafkaConsumer over a ConfluentSchemaRegistry/SchemaRegistrySerde pair, with TemporalAlignmentBuffer and CrossDomainSignalJoinEngine for cross-domain signal joins, latency-tier budgets, and TrainingDataPipelineMetrics observability for the flywheel pipelines that ride on it.