# Shared — Systems Deep Dive

> 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.