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.