# Shared Domain — Features > **Shared** (package scope `@oshun/*`) is the infrastructure foundation layer > of the Oshun monorepo. It provides 42 libraries covering every cross-cutting > concern that domain teams must not implement themselves: authentication, > authorization, database access, caching, event messaging, logging, metrics, > distributed tracing, HTTP client, object storage, security, cryptography, > audit and compliance, AI integration, GPU dispatch, document/media processing, > service discovery, health checks, and development utilities. Domain code never > configures a database connection, formats a log line, or calls an LLM provider > directly — it imports from `@oshun/*` and stays focused on domain logic. This > is the single most important dependency in the entire platform. --- Each of the 42 packages under `libs/shared/` targets one well-defined cross-cutting concern. This document describes what each package does, why it exists, and the key design decisions behind it. For the exact exported API surface — every type, function, and constant — see `specifications.md`. --- ## Core Type System (`@oshun/types`) The zero-dependency type primitives that form the common vocabulary of the entire platform. Every other `@oshun/*` library imports from here, making this the most foundational library in the monorepo. Changes to these types have platform-wide impact. - **Branded ID Types** — `ID`, `UserID`, `ProjectID`, `OrganizationID`, `TeamID`, `SessionID`, `AssetID`, `ContentID`, `AgentID`, `RequestID`, `CorrelationID`. Branded types are nominal wrapper types in TypeScript: passing a `ProjectID` where a `UserID` is expected becomes a compile-time error, not a silent data corruption bug discovered at runtime. - **Timestamp and Date Types** — `Timestamp`, `ISODateTime`, `ISODate`. All date-time values across the platform use consistent ISO 8601 strings, eliminating timezone ambiguity when data is serialized across service boundaries. - **Result Type** — `Result`, `Success`, `Failure`, `AsyncResult`, `ApiErrorResult`, `ApiResult`. A functional error-handling pattern (inspired by Rust's `Result`) that encodes success and failure in the return type rather than through exceptions, making error handling visible at every call site. - **Pagination Types** — `Page`, `CursorPage`, `PaginationParams`, `OffsetPaginationParams`. Unified pagination contracts so every domain API responds with the same shape and clients never adapt their pagination logic per domain. - **API Envelope Types** — `ApiResponse`, `ApiError`, `PaginatedResponse`. A consistent outer wrapper for all REST responses; clients parse one shape regardless of which domain returned the data. - **Entity Mixins** — `BaseEntity` (id, createdAt, updatedAt), `SoftDeletable`, `Versioned`, `Auditable`, `Orderable`, `Taggable`. Database entity patterns that domain models compose rather than redefine in each service. - **Utility Types** — `DeepPartial`, `Nullable`, `NonEmptyArray`, `RequireAtLeastOne`, `RequireExactlyOne`. TypeScript utility types that eliminate boilerplate and enforce invariants at compile time. - **Common Literal-Union Types** — the `config` subpath exports `Environment` (`development` / `staging` / `production` / `test`), `LogLevel`, and `LogFormat`. Shared union types prevent each domain from defining its own string literals for the same concepts, which would produce incompatible serialization. - **Subpath Exports** — `@oshun/types/contracts` carries cross-domain contract versioning (`parseOshunContractVersion`, `versionOshunContractPayload`, compatibility-mode types); `@oshun/types/creative` carries `Asset`, `Script`, `Scene`, `Character`, and `Storyboard` types. --- ## Error Handling (`@oshun/errors`) A standardized error hierarchy so every service throws errors with consistent structure, HTTP status codes, and machine-readable codes. Without this shared hierarchy, each team invents different error shapes, client error handling breaks at domain boundaries, and logs become inconsistent. - **`OshunError` Base Class** — Every platform error extends `OshunError`, carrying a `code` (machine-readable string from the registry), a `statusCode` (HTTP status), a human-readable `message`, a structured `details` object, a `timestamp`, and `isOperational` / `expose` flags. Every error is both machine-parseable (for clients) and human-readable (for operators). `AppError` is a Lilith-compatibility alias of `OshunError`. - **Error Code Registry** — eight grouped constant objects (`GENERAL_ERRORS`, `VALIDATION_ERRORS`, `AUTH_ERRORS`, `AUTHZ_ERRORS`, `RESOURCE_ERRORS`, `EXTERNAL_ERRORS`, `BUSINESS_ERRORS`, `CONTENT_ERRORS`) merged into `ERROR_CODES`. Clients switch on error codes without parsing message strings, enabling localization and programmatic recovery. - **HTTP Error Classes** — one class per status: `BadRequestError` (400), `UnauthorizedError` (401), `PaymentRequiredError` (402), `ForbiddenError` (403), `NotFoundError` (404), `MethodNotAllowedError` (405), `ConflictError` (409), `GoneError` (410), `UnprocessableEntityError` (422), `TooManyRequestsError` (429), `InternalServerError` (500), `NotImplementedError` (501), `BadGatewayError` (502), `ServiceUnavailableError` (503), `GatewayTimeoutError` (504). - **Domain-Specific Subclasses** — semantic classes that extend an HTTP class: `ValidationError` (400, field-level detail), `AuthenticationError` / `TokenExpiredError` / `SessionError` (401), `AuthorizationError` (403), `ResourceNotFoundError` (404), `DuplicateError` / `VersionConflictError` (409), `RateLimitError` (429), `ExternalServiceError` / `AIServiceError` (502), `DatabaseError` / `CacheError` / `QueueError` / `GenerationError` (500), `InvalidStateError` / `PreconditionError` / `LimitExceededError` (400). - **Serialization** — `toJSON()` produces a `SerializedError` (name, code, message, statusCode, timestamp, plus details/stack/cause where available); `toResponse()` produces a client-safe API body that masks 5xx detail. - **`wrapError` Utility** — Wraps any caught unknown value into a typed `OshunError`, preventing raw `unknown` from propagating through the call stack after `catch(e)`. Companion guards (`isOshunError`, `isClientError`, `isServerError`) and helpers (`createSafeErrorResponse`, `formatErrorForLogging`, `getErrorChain`) round out the toolkit. - **HTTP Status Constants** — `HTTP_STATUS` map with named constants for all standard HTTP status codes, preventing magic numbers in domain service code. --- ## Configuration Management (`@oshun/config`) Centralized, type-safe configuration loading from environment variables. Services never call `process.env.XYZ` directly — they call `@oshun/config` functions that return fully-validated typed objects, failing fast at startup if required variables are missing rather than failing silently hours after deployment. - **Environment Detection** — `getEnvironment()`, `isProduction()`, `isDevelopment()`, `isTest()`. Single source of truth for the running environment, used to toggle debug logging, relaxed CORS policies, and test doubles. - **Typed Env Reading** — `getEnv`, `getEnvRequired`, `getEnvNumber`, `getEnvNumberRequired`, `getEnvBool`, `getEnvArray`, `getEnvJson`. Each helper coerces to the expected type and throws a clear startup error if a required variable is missing or malformed. - **Config Loaders** — eight typed loaders (`loadServiceConfig`, `loadServerConfig`, `loadDatabaseConfig`, `loadRedisConfig`, `loadStorageConfig`, `loadAuthConfig`, `loadLoggingConfig`, `loadAIConfig`), each validating against a Zod schema and returning a fully-typed config object. A `createConfigLoader` factory builds a loader for any custom schema. Domain-isolated databases all use `loadDatabaseConfig()` with the appropriate connection-string environment variable; there is no per-domain loader function. - **Zod Schemas** — exported schemas for every config shape (`serverConfigSchema`, `databaseConfigSchema`, `redisConfigSchema`, `storageConfigSchema`, `authConfigSchema`, `aiConfigSchema`, and provider sub-schemas), so services can compose validation rather than hand-rolling it. - **Feature Flags** — a `FeatureFlags` registry with `isFeatureEnabled`, `getFeatureValue`, and image-generation helpers (`getImageGenerationProvider`, `shouldUseRunPod`, `getRunPodConfig`). - **Experiment Guardrails** — `evaluateGuardrails`, `evaluateMetric`, `bundleIsGreen`, and `loadPolicyBundle` for experiment policy bundles. - **Log Level and Port Resolution** — `getLogLevel()` and `getPort(key, default?)` with environment-appropriate defaults. --- ## Structured Logging (`@oshun/logging`) High-performance structured JSON logging built on Pino. Producing machine-parseable logs from day one enables log aggregation, search, and alerting in production without a painful retrofitting effort later. - **Pino-Based Logger** — `createLogger({ service, version, level })` returns a Pino logger. Pino is 5–10× faster than Winston or Bunyan because it defers string formatting to a separate transport process, keeping the request hot path free of I/O. - **Request-Scoped Context** — Every log record automatically includes `requestId`, `userId`, `domain`, `traceId`, and `spanId` from async context — all log lines for a single request are correlated without the developer manually threading a logger. - **Child Loggers** — `logger.child({ component: 'payment-service' })` creates a logger that inherits parent context and adds new fields, enabling module-level context without polluting the parent. - **PII Redaction** — Configurable field redaction (e.g. `password`, `creditCard`, `ssn`, `email`) scrubs sensitive data before log records leave the process, preventing PII from appearing in Datadog or Elasticsearch. - **Multiple Transports** — File transport with rotation, Elasticsearch transport, and HTTP transport for any log aggregation endpoint. Transports are composable and can run simultaneously. - **Log Sampling** — Configurable sampling for high-volume scenarios (e.g. log 1% of successful health checks, 100% of errors), preventing logging from becoming a cost centre. - **OpenTelemetry Integration** — Log records include W3C Trace Context (`traceId`, `spanId`) so logs and traces can be correlated in Jaeger or Grafana Tempo. - **Development Mode** — Pretty-printed, color-coded, human-readable output when `isDevelopment()` is true; JSON in all other environments. - **Request Logging Middleware** — `honoRequestLogger` — drop-in Hono middleware that logs request start/end with method, path, status, and duration. --- ## Metrics Collection (`@oshun/metrics`) Prometheus-compatible metrics for domain services. Metrics are the primary signal for capacity planning and SLA compliance monitoring; this library provides all four Prometheus instrument types with consistent naming conventions. - **Core Metric Types** — `Counter` (total requests), `Gauge` (active connections), `Histogram` (latency distribution), `Summary` (quantile-based latency). All four Prometheus data types with correct semantics. - **Histogram Bucket Presets** — `HISTOGRAM_BUCKETS` for fast API, slow API, and batch job workloads. Correct bucket edges are critical — wrong edges make latency histograms useless for understanding percentile behavior. - **Standard Metric Names** — `HTTP_METRICS`, `DB_METRICS`, `CACHE_METRICS`, `AI_METRICS`, `QUEUE_METRICS` following the `oshun___` convention so Prometheus dashboards and alert rules are portable across all services. - **MetricsRegistry** — `OshunMetricsRegistry`, `createRegistry`, `getRegistry`, `initializeRegistry`. Prevents double-registration errors and provides clean teardown for test isolation. - **MetricsServer** — Exposes `GET /metrics` in Prometheus text format. Services attach this to their HTTP server to participate in platform-wide Prometheus scraping. - **OpenTelemetry Export** — Metrics can be shipped via OTLP to any OpenTelemetry-compatible backend (Grafana Cloud, Honeycomb, Datadog) in addition to Prometheus. - **Label Support** — All metric types accept label maps for multi-dimensional breakdowns (e.g. by HTTP method, route, status code). --- ## Distributed Tracing (`@oshun/tracing`) OpenTelemetry-based distributed tracing so a single user request can be followed across every microservice that handled it. Without tracing, diagnosing latency in a distributed system is guesswork; with tracing, the full call tree with per-service timings is visible in Jaeger or Grafana Tempo. - **W3C Trace Context Propagation** — Every outbound HTTP request and event carries `traceparent` and `tracestate` headers. Incoming requests extract and continue the trace automatically, creating an unbroken chain of spans across all service boundaries. - **Span Creation API** — `tracer.startSpan(name)`, `tracer.withSpan(name, fn)`. Helper types `SpanAttributes`, `SpanEvent`, `SpanLink` provide typed metadata conforming to OpenTelemetry semantic conventions. - **Branded Trace IDs** — `TraceId`, `SpanId`, `CorrelationId` as branded types prevent passing a `SpanId` where a `TraceId` is expected. - **Semantic Convention Attribute Shapes** — `HttpSpanAttributes`, `DbSpanAttributes`, `RpcSpanAttributes`. Standard OpenTelemetry shapes ensure Jaeger and Tempo can display correct service maps and identify bottlenecks by operation type. - **Sampling Strategy** — Configurable sampler: 100% in development, configurable rate in production. Errors are always sampled regardless of the sampling rate. - **Exporter Support** — AWS X-Ray, Jaeger, and OTLP for any OpenTelemetry collector — backend flexibility without changing instrumentation. - **HTTP Middleware** — `TracingMiddlewareConfig` for automatically creating spans for HTTP requests with standard attributes and correct span lifecycle. --- ## Database Access (`@oshun/database`) Unified PostgreSQL and Redis client utilities with connection pooling, transaction helpers, a typed query builder, health checks, and migration support. Domain teams connect through this layer rather than configuring `pg` and `ioredis` themselves. - **PostgreSQL Connection Pooling** — `PostgresConfig`, `PostgresPoolStats`. Configurable min/max pool, connection timeout, and idle timeout. Reusing connections eliminates the TCP and TLS handshake overhead of fresh connections per query. - **PgBouncer Integration** — `PgBouncerAdminConfig`, `PgBouncerAutoScalerConfig`. Connection pooler management for high-concurrency deployments where direct connections become the bottleneck. PgBouncer multiplexes many service connections onto fewer database connections. - **Transaction Helpers** — `TransactionOptions`, `TransactionIsolationLevel`. Wrappers that automatically roll back on exception, preventing partial writes that leave data inconsistent. - **Query Builder Types** — `WhereCondition`, `OrderByClause`, `ParameterizedQuery`. Typed building blocks for safe parameterized queries, eliminating SQL injection via string interpolation. - **Redis Client** — `RedisClient`, `RedisClusterClient`, with `RedisConfig`, `RedisClusterConfig`, `RedisHealthInfo`. Standalone and cluster Redis with cluster-aware command routing. - **Query Builder** — A `sql` tagged template plus `buildWhereClause`, `buildOrderByClause`, `buildPaginationClause`, and insert/update/delete statement builders, with identifier sanitisation and `LIKE`-pattern escaping. - **Health Checks** — `checkPostgresHealth`, `checkRedisHealth`, `checkAllDatabasesHealth`, and a `HealthMonitor` with a result cache. - **Connection-String Utilities** — Parse, build, and mask PostgreSQL and Redis connection strings; `detectDatabaseType`, `validateConnectionString`. - **Migration Runner** — `MigrationRunner` with `createSqlMigration` for schema migrations. (The cross-domain migration framework is the separate `@oshun/migration` package.) - **Multi-Database Routing** — Each domain has its own isolated PostgreSQL database (`yemaya`, `lilith`, `isis`, `sophia`, `hathor`, `bellona`, plus others). Domain services load their own config; no shared connection allows cross-domain data access. - **DatabaseError** — Wraps low-level `pg` errors into typed errors (`DatabaseError`, `DatabaseErrorCodes`) with structured metadata. - **Metrics** — `instrumentPostgresClient`, `PoolStatsMonitor`, and `DatabaseStatsTracker` expose pool and query statistics to `@oshun/metrics`. - **Retry Logic** — `RetryConfig` for automatic retry of transient connection errors with configurable count, backoff multiplier, and retriable error codes; `DEFAULT_RETRY_CONFIG` ships sensible defaults. --- ## Caching (`@oshun/cache`) Redis-backed and in-memory caching with distributed locking, pub/sub, circuit breaker protection, and stampede prevention. Every domain that caches results uses this library rather than managing Redis connections, serialization, and locking themselves. - **CacheClient Interface** — `CacheClient`, `CacheConfig`. The uniform interface domain code programs against, independent of whether the backing store is Redis or in-memory. Backends are swappable for testing. - **Redis and In-Memory Backends** — Full Redis implementation and an LRU-based in-memory cache (`MemoryCache`) for use as a first-level local cache in front of Redis, reducing Redis traffic for hot keys. - **TTL Constants** — `TTL`, `DOMAIN_TTL` provide semantic named values (`TTL.FIVE_MINUTES`, `DOMAIN_TTL.SESSION`) so services don't scatter raw second counts through code. - **Cache-Aside Helper** — `getOrSet(key, loader, ttl)` implements the cache-aside pattern: check cache, call loader on miss, write result. Eliminates boilerplate in every caching call site. - **Tag-Based Invalidation** — `InvalidationManager`. Invalidate all cache entries tagged with a logical group (e.g. all entries tagged `project:123` when a project is updated). This solves the distributed cache invalidation problem in a principled way. - **Distributed Lock** — `Lock`, `LockManager`. Redis-based distributed lock using the Redlock algorithm for coordinating exclusive access across multiple service pods. Prevents duplicate processing when multiple pods pick up the same work. - **Circuit Breaker** — `CircuitBreaker`. When Redis is unavailable, the circuit breaker opens and cache operations fall through to the origin — degraded but functional. Prevents Redis unavailability from cascading into a service outage. - **Cache Stampede Protection** — Single-flight mechanism ensuring many concurrent cache misses for the same key result in only one origin call, not N parallel calls during traffic spikes. - **Pub/Sub Client** — `PubSubClient`, `PUBSUB_CHANNELS`. Redis pub/sub for real-time event notification between service pods, used by `@oshun/websocket` for cross-pod message delivery. --- ## Job Queue (`@oshun/queue`) BullMQ-backed job queue with five priority levels, retry policies, dead-letter queues, and in-memory test implementations. Background processing (image processing, email, reports) happens here rather than in HTTP request handlers, keeping API response times fast. - **Job Envelope** — `JobEnvelope`, `JobOptions`, `JobResult`, `JobError`, `JobProgress`. All jobs are typed at the payload level. Job options cover priority, delay, maximum attempts, and backoff per job. - **Priority Queue** — Five `JobPriority` levels (`critical`, `high`, `normal`, `low`, `background`), with `PRIORITY_VALUES` mapping each to a numeric weight. Higher-priority jobs are dequeued first regardless of submission order, ensuring user-facing work preempts bulk background processing. - **Queue and Worker Interfaces** — A `Queue` interface for submission and a `Worker` interface for consumption with configurable concurrency and stall detection. - **Dead Letter Queue** — `DeadLetterQueue`. Jobs exhausting their retry budget move to the DLQ with full failure history. Operators inspect, retry, or discard DLQ entries without losing information about what went wrong. - **Standard Queue Names** — `QUEUE_NAMES` with canonical names for platform queues (`email`, `push-notification`, `content-processing`, `moderation`, `analytics`, `exports`, `imports`, `webhooks`, `scheduled`, `oshun-editorial-jobs`) to prevent typo-created orphaned queues. - **Durable Queue Substrate** — `DurableQueueSubstrate` with durable job classes and a `DurableQueueSlaMonitor` that evaluates SLA policies and emits alerts. - **In-Memory Implementation** — `MemoryQueue`, `MemoryWorker`, and `MemoryDeadLetterQueue` for unit tests, avoiding Redis and BullMQ in CI. - **BullMQ Implementations** — `BullMQQueue`, `BullMQWorker`, and `RedisDeadLetterQueue` for Redis-backed durable job processing. --- ## Rate Limiting (`@oshun/rate-limit`) Redis-backed distributed rate limiting with three algorithm implementations, throttling, graceful Redis-failure degradation, and Hono middleware integration. - **Sliding Window** — `SlidingWindowRateLimiter`. The most accurate algorithm: tracks individual request timestamps so there are no burst spikes at window boundaries. Best for user-facing APIs. - **Fixed Window** — `FixedWindowRateLimiter`. Simpler and cheaper (single Redis counter per window). Acceptable for background jobs and internal service calls. - **Token Bucket** — `TokenBucketRateLimiter`. Allows controlled bursting: a client that hasn't used their quota accumulates tokens and can burst above the sustained rate. Ideal for mobile clients that send requests in batches. - **Request Throttler** — `RequestThrottler`. Delays over-limit requests and processes them at the allowed rate, smoothing traffic spikes without returning errors. - **Graceful Degradation** — `GracefulRateLimiter`. Falls back to in-memory rate limiting when Redis is unavailable, maintaining protection during infrastructure incidents. - **Rate Limit Result** — `RateLimitResult`, `RateLimitInfo`. Every check returns `allowed`, current count, limit, and reset time for setting standard `X-RateLimit-*` response headers. - **Hono Middleware** — `createRateLimitMiddleware`. Drop-in middleware applying a limiter to a route group, setting headers and returning 429 with `Retry-After` when the limit is exceeded. --- ## HTTP Client (`@oshun/http-client`) Type-safe HTTP client with circuit breaker, retry with jitter, timeout enforcement, and OpenTelemetry trace propagation built in. Service-to-service calls go through this client rather than raw `fetch`, ensuring resiliency and observability are consistent. - **HttpClient** — `HttpClient`, `createHttpClient`, `createResilientHttpClient`. GET, POST, PUT, PATCH, DELETE with TypeScript generics for request and response body types. - **Circuit Breaker** — `CircuitBreakerConfig`, `CircuitState` (CLOSED, OPEN, HALF-OPEN). When a downstream service starts failing, the circuit opens and requests fail immediately without waiting for a timeout, preventing thread pool exhaustion and giving the downstream service time to recover. - **Retry with Exponential Backoff and Jitter** — `RetryConfig` covering max attempts, initial delay, multiplier, jitter, and retriable status codes. Full jitter prevents thundering-herd retry storms. - **Timeout Enforcement** — Per-request connect and read timeouts. Slow upstream services cannot consume all connection pool slots. - **OpenTelemetry Propagation** — Outbound requests carry `traceparent` and `tracestate` headers from the active span automatically, enabling traces to cross service boundaries. - **Request/Response Interceptors** — Middleware hooks for auth headers, logging, metric recording, response transformation, and request signing. - **Connection Pooling** — `ConnectionPoolConfig`. Reuses TCP connections across requests to the same host for significant throughput improvement on high-volume inter-service calls. --- ## Object Storage (`@oshun/storage`) S3-compatible object storage client for MinIO (local dev) and AWS S3 (production) behind a unified interface. Domain services store files through this library rather than embedding S3 SDK calls directly. - **StorageClient Interface** — `StorageClient`, `StorageProvider`. Uniform interface over S3 and local filesystem backends; domain code does not know which backend is active and tests use a local filesystem store. - **S3 and MinIO Clients** — `createS3Client(config)` for production; `createMinioClient(config)` for development — same interface, different backing store. - **LocalStorageClient** — Filesystem-based implementation for integration tests and development environments without MinIO. - **Multipart Upload** — For files above the configurable threshold, parallel multipart upload dramatically improves throughput for large assets (video, 3D models). `DEFAULT_PART_SIZE`, `MIN_PART_SIZE`, `MAX_PARTS` define the boundaries. - **Pre-Signed URL Generation** — `SignedUrlOptions`, `SignedPostPolicy`. Time-limited pre-signed URLs so clients upload directly to S3 without routing through the application server, eliminating server bandwidth costs. - **File Metadata** — `FileMetadata`, `FileManifest`. Typed metadata including content type, size, ETag, last-modified, and custom user-defined headers. - **Key Generation** — `GenerateKeyOptions`. Utilities for generating consistent, unique, path-safe storage keys from domain, resource type, and ID. --- ## Authentication and Authorization (`@oshun/auth`, `@oshun/auth-primitives`, `@oshun/identity`) Three complementary libraries covering the complete authentication stack. The split into three packages reflects three distinct use cases: raw JWT primitives for services that need fine-grained control, a full-featured auth service with role-based access control for services that issue tokens, and a lighter-weight verify-only library for API gateways that check tokens without issuing them. ### Full Auth Service (`@oshun/auth`) The primary authentication service used by any service that owns user sessions and issues tokens. - **AuthService** — Registration, login, token management, account lockout, and RBAC in a single storage-agnostic service (user repository, token repository, audit repository are injected). - **JWT Configuration** — `JwtConfig`: algorithm (HS256/RS256), issuer, access token TTL (default 15 minutes), refresh token TTL (default 7 days). Short-lived access tokens limit damage when a token is leaked. - **Account Lockout** — Configurable lockout after N failed attempts, preventing brute-force attacks. - **Role-Based Access Control (RBAC)** — `requireRole(role)`, `requirePermissions(permissions[])`. Hono middleware that checks JWT claims for required roles/permissions and returns 403 if the check fails. - **OAuth2 Integration** — `OAuthProvider` helpers for Google, GitHub, Discord, and Apple, handling the authorization code flow and mapping provider identities to platform users. ### Authentication Primitives (`@oshun/auth-primitives`) The lower-level building blocks used by `@oshun/auth` and by any service that needs direct access to JWT, session, TOTP, or API key primitives. - **JwtService** — Sign and verify JWTs with HS256, RS256, or ES256. Returns `DecodedToken` with full `JwtClaims`, `JwtPayload`, and `JwtHeader` breakdown. - **JWKS Support** — JSON Web Key Set management for public key distribution to downstream services verifying tokens offline. - **Session Management** — `Session`, `DeviceInfo`, `SessionStore`. Session storage with device fingerprinting, expiration management, and sliding windows. - **API Key Management** — `ApiKey`, `ApiKeyStore`. Create, hash, and verify API keys; actual key values are never stored in plaintext. - **Password Policy** — `PasswordPolicy`, `PasswordValidationResult`. Configurable strength rules with structured feedback suitable for surfacing in UI. ### Gateway Identity (`@oshun/identity`) A minimal verify-only library for API gateways and edge services that need to check tokens issued by the central auth service, without the overhead of the full `@oshun/auth` package. - **JWT Verify-Only Service** — `JwtService`, `createJwtService`. Simpler verify-only service for API gateways that check tokens issued by the central auth service. - **Authentication Middleware** — `authenticate`, `authenticateService`. Extracts Bearer tokens and API keys, then attaches decoded identity to request context. - **Role and Permission Helpers** — `hasRole`, `hasPermissions`, `hasAnyPermission`, `getPermissionsForRole`. Pure functions usable both in middleware and in business logic. --- ## WebSocket Server (`@oshun/websocket`) Scalable WebSocket server with Redis pub/sub backend for multi-pod deployments and JWT authentication on the upgrade request. Real-time features use this rather than raw `ws`, getting cross-pod delivery for free. The cross-pod boundary is the key design point: without the Redis pub/sub backend, a message sent by a client on pod A would never reach a client connected to pod B. `@oshun/websocket` solves this transparently. - **WSServer** — Attaches to an existing Node.js HTTP server at a configurable path. Manages connection lifecycle, authentication, heartbeats, and cleanup. - **JWT Authentication on Upgrade** — The auth handler receives the Bearer token from the upgrade request and returns an authenticated user or `null` to reject unauthenticated connections before they are established. - **Channel-Based Pub/Sub** — `subscribeToChannel`, `unsubscribeFromChannel`, `broadcastToChannel`. Clients subscribe to named channels (e.g. `project:123`) and receive only messages for their channels. - **Redis Pub/Sub Backend** — Messages are relayed between pods via Redis pub/sub, solving multi-instance WebSocket scaling without sticky sessions. - **Presence Tracking** — Live map of connected users for online/offline indicators and active collaborator lists. - **Heartbeat / Keepalive** — Configurable ping-pong detects and cleans up zombie connections that drop silently without a close frame. --- ## Event Bus (`@oshun/event-bus`) A Redis pub/sub-backed cross-domain event bus for real-time event-driven communication. When Isis generates an asset, it publishes an event; Sophia, Yemaya, and the shell react without any direct coupling between services. Events fan out to subscribers over Redis pub/sub; a TTL-bounded Redis key holds a durable copy of each event as the replay source. The transport is Redis `ioredis` connections — not Kafka and not Redis Streams. - **EventBus / `createEventBus`** — Initialized with a Redis connection URL and `sourceDomain` identifier. Reconnects automatically on connection failures. - **Type-Safe Publishing** — `bus.publish(EventTypes.ISIS_ASSET_GENERATED, payload)`. Payload type is inferred from the event type constant; incorrect payload shapes are rejected at compile time. - **Pattern-Based Subscriptions** — `bus.subscribe('isis.asset.*', handler)`. Wildcard subscriptions receive broad event categories without enumerating every type. - **Event Envelope** — `EventEnvelope` wraps every event with `id` (ULID — globally unique and time-sortable), `type`, `version`, `domain`, `source`, `timestamp`, `correlationId`, and `causationId`. These fields enable event replay, audit trails, and cross-service correlation. - **Consumer Groups** — A subscription that declares a `group` competes with other group members for each event via an atomic Redis claim (`SET NX EX`) — only one member runs the handler. Without a group, every matching subscription runs (broadcast). - **Retry and Dead Letter Queue** — Handlers retry with exponential, linear, or fixed backoff. Events that exhaust their retry budget move to a dead-letter list/index with full failure history, queryable via `getDeadLetters` and replayable via `replayDeadLetter`. - **Durable Scheduling** — Delayed publishes and `nack(delay)` reschedules go through a Redis sorted set drained by a scheduler loop, so retry state survives a process restart. - **Event Persistence and Replay** — Each published event is stored under a TTL-bounded Redis key (default 24 h). `replayUnacked()`, called on boot, redelivers persisted events that no active subscription has acked — recovering work lost to a crash between publish and ack. - **Versioned Topic Registry** — `EventTopicRegistry` resolves topics to schema versions with lifecycle (`active`/`deprecated`/`retired`) and compatibility metadata; in `enforced` mode, unregistered or retired topics are rejected at publish time. - **Outbound Webhook Delivery** — `OutboundEventDispatcher` and a signing key ring deliver events to external tenant webhooks with HMAC/asymmetric signatures and retry backoff; a `TenantWebhookSimulator` supports local webhook testing. --- ## API Gateway (`@oshun/traefik-config`) TypeScript-based Traefik configuration builders. Instead of writing gateway routing YAML by hand (which drifts from reality), domain teams declare services and routes in TypeScript and the library generates the correct Traefik v3 config. Note that `@oshun/traefik-config` is **not a runtime HTTP server** — it is a configuration-generation tool. It produces YAML for Traefik to consume. - **Service Builder** — `ServiceBuilder`, `service()`. Fluent API for declaring a backend service with name, domain, URL, health check endpoint, load balancing strategy, and circuit breaker settings. - **Route Builder** — `RouteBuilder`, `route()`. Declares a route: path pattern, HTTP methods, target service, authentication requirement, rate limit, CORS policy, and middleware chain. - **Gateway Config Builder** — `GatewayConfigBuilder`. Combines service and route declarations into a complete, validated gateway configuration document. - **Domain Route Registries** — Pre-built registries for all domains (`YEMAYA_SERVICES`, `ISIS_SERVICES`, etc.). `getAllServices()` and `getAllRoutes()` aggregate all domains into a single registry. - **Traefik Config Generation** — `generateStaticConfig()`, `generateDynamicConfig()`. Produces Traefik v3 YAML from TypeScript declarations, ensuring the gateway always matches what the code declares. --- ## Service Discovery (`@oshun/service-discovery`) Redis-based service registry for dynamic microservice topology. Services announce themselves on startup and query the registry to find each other, enabling zero-downtime rolling deployments and elastic scaling. - **ServiceDiscovery** — Redis-backed registry with configurable registration TTL. Services re-register periodically as a keepalive; if a service dies, its registration expires automatically. - **Registration** — `discovery.register({ name, domain, host, port, protocol, version, tags })`. Returns an `instanceId`. The registration heartbeats its TTL to stay alive. - **Service Lookup** — `discovery.getServiceUrl(ServiceNames.ISIS_WORKER)`. Returns the URL of a healthy instance using the configured load balancing strategy. - **Load Balancing Strategies** — Round-robin, random, least-connections, weighted. The strategy is configurable per service without changing calling code. - **Watch for Changes** — `discovery.watch(serviceName, handler)`. Subscribe to service availability changes for reactive client reconfiguration. - **ServiceNames Registry** — `ServiceNames` constant with canonical identifiers for all Oshun services, preventing typo-based discovery failures. --- ## Health Checks (`@oshun/health`) Standardized health check system compatible with Kubernetes liveness and readiness probes. Consistent health endpoints enable platform-wide observability and automatic pod restarts without per-service boilerplate. - **HealthManager** — Orchestrates multiple health checks and aggregates results into an overall `HealthReport`. Configurable cache duration prevents repeated Kubernetes probes from hammering dependencies. - **Health Check Registration** — `healthManager.register(name, checkFn, config)`. Register any async function returning `HealthCheckResult` — a database ping, Redis ping, or external API reachability check. - **Health Report** — `HealthReport` covering overall `HealthStatus` (healthy, degraded, unhealthy), build info (version, commit, build date), and per-check results with latency and error detail. - **Kubernetes Probes** — `ProbeManager`. Separate liveness (is the process alive?) and readiness (can it handle traffic?) endpoints. Readiness fails if any critical dependency is down; liveness fails only on total process failure. - **Configurable Thresholds** — `DEFAULT_FAILURE_THRESHOLD`, `DEFAULT_RECOVERY_THRESHOLD`. N consecutive failures to mark unhealthy; N consecutive successes to recover. Prevents flapping health status that would trigger unnecessary pod restarts. --- ## Security Utilities (`@oshun/security`) Audit logging, content scanning, and secret management. Security concerns are handled centrally so every domain gets consistent, auditable behavior without each team building its own security primitives. ### Audit Logging Audit logging captures who did what, when, from where, and with what outcome. This structure is what GDPR and SOC 2 audits require, and it is non-negotiable for compliance. The `@oshun/security` audit logger is distinct from the platform-wide canonical audit platform (`@oshun/audit-platform`): this one is a per-service utility logger, while `audit-platform` is the central ingest and storage system. - **OshunAuditLogger** — Tamper-evident audit trail for compliance-relevant actions, backed by either `MemoryAuditStore` (tests) or `DatabaseAuditStore`. Batched writes (`batchingEnabled`, `batchSize`, `batchFlushInterval`) for high-throughput scenarios. - **Typed Logging Methods** — `logAuth`, `logAuthz`, `logResource`, and `logSecurity` each record who did what, when, from where, and with what outcome — the structure GDPR and SOC 2 compliance require. - **Actor Model** — `userActor`, `serviceActor`, `systemActor`, `anonymousActor`, and `auditTarget`. Structured actor metadata enables queries like "all actions by user X" or "all admin actions in the last 24 hours." - **Query Interface** — Retrieve audit entries by actor, target, time range, or event type for compliance reporting and incident investigation. ### Content Scanning Content submitted by users must be checked for secrets, injection patterns, and malware before it is processed or stored. The content scanner runs as part of any upload or ingestion flow. - **SecurityScanner** — `BuiltinSecurityScanner` and `ClamAVScanner` (`createBuiltinScanner` / `createSecurityScanner`). `scanFile(path)` and `scanText(content)` detect threats including secrets (API keys, private keys, passwords), injection patterns (`xss`, `sql_injection`, `command_injection`), and malware classes (`malware`, `virus`, `trojan`, `ransomware`, `spyware`, `rootkit`, …). - **Scan Result** — Per-threat details including severity, location in content, and a remediation hint. Severity levels determine whether a violation is blocking or a warning. ### Secret Management Application secrets (database passwords, API keys, signing keys) must be managed outside source code, rotated without downtime, and fully audited. - **OshunSecretManager** — `getSecret(name)` with transparent caching; `createSecret(...)`, `updateSecret(...)`, and list operations. - **Zero-Downtime Rotation** — `rotateSecret(name, config?)` rotates a secret, optionally auto-generating the new value; auto-rotation runs on a configured interval. - **Store Implementations** — `MemorySecretStore` for tests and `DatabaseSecretStore` for persistence (both with `create*Store` factories). - **Access Audit** — Every secret access and rotation emits an `admin.secret.access` / `admin.secret.rotate` audit event, creating a complete access trail for compliance and security review. --- ## AI Integration (`@oshun/ai`) LLM provider abstraction, intelligent model routing, prompt template management, response caching, usage tracking, and batch processing. Every domain that uses LLMs imports this library rather than embedding provider SDKs, ensuring cost control and observability are consistent. - **Provider Abstraction** — `AnthropicProvider`, `OpenAIProvider`, `GoogleProvider`, `XAIProvider`, `OllamaProvider`. All implement the same `ChatCompletionRequest` / `ChatCompletionResponse` interface. Switching providers requires one line of configuration, not domain refactoring. - **Tool Calling** — `ToolDefinition`, `ToolCall`, `JsonSchema`. Standardized tool/function calling that maps to each provider's native mechanism, so domain code defines tools once and they work across providers. - **Streaming** — `StreamEvent`, `StreamCallback`. Async streaming with delta events for token-by-token delivery. - **Model Routing** — `ModelRouter` for rule-based routing; `QualityRouter` for task-type/cost/speed weighted selection; `MLRouter` that learns from historical performance. `MODEL_PROFILES` and `TASK_TYPE_PROFILES` drive data-driven selection. - **Prompt Templates** — `PromptTemplate`, `TemplateLibrary`. Named templates with typed variable slots eliminate prompt string duplication. `createDefaultTemplateLibrary` provides `CREATIVE_TEMPLATES` and `TECHNICAL_TEMPLATES`. - **Response Cache** — `ResponseCache`, `CachedProvider`. LLM responses cached by a hash of the full request. Identical requests return cached results, reducing costs substantially for repetitive queries. - **Usage Tracking** — `UsageTracker`, `UsageSummary`, `BudgetConfig`. Token consumption and cost tracked per provider, model, and calling domain. Budget limits throw when exceeded, preventing runaway AI costs. - **Batch Processor** — `BatchProcessor`. Accumulates individual requests and dispatches them in batches to provider batch APIs (e.g. OpenAI Batch API), reducing cost for non-latency-sensitive workflows. - **Prompt Compressor** — `PromptCompressor`. Reduces prompt token count by removing redundant whitespace, compressing history, and summarizing older turns. --- ## Advanced AI (`@oshun/ai-advanced`) Specialized AI tooling beyond core LLM integration: pluggable adapters, model benchmarking, automatic model selection, on-device inference, and research tooling. - **Adapter Manager** — `AdapterManager`. Pluggable adapters for specialized AI providers that don't fit the generic LLM interface (e.g. domain-specific classifiers). Adapters are registered by name and discovered at runtime. - **Benchmark Manager** — `BenchmarkManager`. Runs standardized benchmarks (MMLU, HumanEval, custom domain tasks) against registered models to build performance profiles that inform routing decisions. - **Automatic Model Selection** — `ModelSelector`. Uses benchmark results and usage history to recommend the best model for a given task type and quality/cost constraint. - **On-Device AI / Edge** — `EdgeManager`, `OnnxRuntimeProvider`. Runs ONNX models locally via ONNX Runtime in the browser or Node.js. Enables private inference (data never leaves the device) and offline operation for mobile and desktop clients. - **Research Tools** — `ResearchManager`, `ArxivApiProvider`, `HuggingFaceApiProvider`. Integrates with arXiv and HuggingFace for fetching research papers and datasets, used by Sophia for academic knowledge acquisition. --- ## GPU Dispatch (`@oshun/gpu-dispatcher`) Manages GPU job dispatch to RunPod Serverless for computationally intensive workloads: image generation, video processing, and 3D rendering. Provides a queue-backed abstraction over RunPod so domain services don't manage RunPod API calls directly. - **GpuDispatcher** — Configured with a RunPod API key and endpoint registrations (each mapping to a RunPod serverless endpoint with associated job types). Manages queuing, prioritization, and job lifecycle. - **Job Creation** — `dispatcher.createJob({ type, input, priority })`. The job `type` is matched against endpoint type lists to select the correct RunPod endpoint automatically. - **Completion Polling** — `dispatcher.waitForJob(jobId)`. Polls with configurable intervals and returns the completed result. - **Event-Driven Processing** — `dispatcher.on('job:completed', handler)`. Event callbacks for background queue processing. - **Priority Management** — High-priority user-triggered jobs preempt background batch jobs, keeping interactive features responsive. ### RunPod Client (`@oshun/runpod-client`) Low-level type-safe wrapper over the RunPod Serverless REST API, consumed internally by `@oshun/gpu-dispatcher`. Most consumers should use the dispatcher rather than this client directly. - **Async Job** — `client.runAsync(endpointId, input)` submits and returns immediately with a job ID. - **Run-and-Wait** — `client.runAndWait(endpointId, { input, maxWaitTime })` submits and polls until completion or timeout. - **Synchronous Mode** — `client.runSync(endpointId, { input, timeout })` for short-lived jobs completing within the HTTP timeout window. - **Status Polling** — `client.getJobStatus(endpointId, jobId)` returns typed `JobStatus` (IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED, CANCELLED, TIMED_OUT). - **Webhook Support** — `WebhookConfig` for RunPod to call back when a job completes, eliminating polling in event-driven deployments. --- ## Testing Utilities (`@oshun/testing`) Comprehensive test helpers: mock factories, fixture generators, async utilities, test containers, and a Vitest configuration factory. Consistent test infrastructure prevents each team from reinventing database setup, mock patterns, and async helpers. - **Mock Logger / HTTP Client / Redis / Database** — In-memory implementations of every infrastructure interface for unit testing without real external services. Configurable response fixtures and call recording for assertions. - **Mock Event Emitter** — `MockEventEmitter`. Records emitted events for assertion in tests involving event-driven logic. - **Mock Timers** — `MockTimers`. Controllable clock for testing time-dependent logic (TTLs, timeouts, scheduled tasks) without real-time delays. - **Fixture Factory** — `FixtureFactory`. Generates realistic test data with configurable overrides and deterministic seeding for reproducible runs. - **Database Test Context** — `TestDatabaseContext`. Transaction-wrapped database tests that roll back after each test, leaving the database clean without re-running migrations. - **Async Utilities** — `waitFor(condition, options)` for polling-based async assertions; `Deferred` for manually controlling promise resolution. - **Test Containers** — `TestContainer`. Docker container lifecycle management for integration tests needing real external services (PostgreSQL, Redis) without a full local environment. - **Vitest Config Factory** — `VitestConfigOptions`, `CoverageThresholds`. Creates consistent Vitest configurations across all monorepo packages with enforced coverage thresholds. --- ## Infrastructure Primitives (`@oshun/infrastructure`) Performance optimization, security, and observability type primitives shared across the platform. Originally designed for Yemaya; now consumed by all domains needing shared types for performance and monitoring concepts. - **Lazy Loading and LOD Types** — `LazyLoadConfig`, `LoadPriority`, `LoadStatus`, `LODConfig`, `LODLevel`. Types for deferring asset loading and switching between quality levels based on distance or device capability. - **Memory Budget System** — `MemoryBudget`, `MemoryUsage`, `MemoryPressure`. Track memory per subsystem and receive pressure notifications when limits are approached. - **Background Task and GPU Compute Schedulers** — `BackgroundTask`, `TaskPriority`, `GPUComputeJob`, `GPUJobType`. Types for scheduling and monitoring background and GPU workloads with priority-based ordering. - **Security Primitives** — `EncryptionAlgorithm`, `EncryptedData`, `Vulnerability`, `VulnerabilitySeverity`, `SecurityScanResult`. Shared types for encryption configuration and vulnerability tracking. - **Observability Types** — `Trace`, `Span`, `SpanKind`, `Metric`, `MetricType`, `Alert`, `AlertSeverity`, `Dashboard`, `DashboardPanel`. Structured types for the full observability data model used by monitoring dashboards and alerting systems. --- ## Data Migration (`@oshun/migration`) Cross-domain data migration framework for safely moving data between schema versions, platform generations, or storage systems across distributed services. - **MigrationRegistry / MigrationRunner** — Register named migration scripts and execute them in sequence. The runner tracks completion and resumes from the last checkpoint, enabling safe restart after failures without re-running completed migrations. - **Checkpoint Stores** — `FileCheckpointStore` (persists progress to disk) and `MemoryCheckpointStore` (for testing). Prevents double-migration after crashes. - **ID Mapping Stores** — `FileIdMappingStore`, `MemoryIdMappingStore`. When migrating across systems, old IDs are mapped to new IDs durably across restarts. - **Oshun V1 Migration Plan** — `buildOshunV1SharedObjectMigrationPlan`, `createOshunV1SharedObjectMigrationRegistry`. Pre-built migration plan for the shared object layer with global verification gates and step-by-step execution. --- ## Documentation Tooling (`@oshun/documentation`) Typed models for representing system architecture as data. - **Architecture Documentation Models** — Structured types for architecture components (`ArchComponent`), connections (`ArchConnection`), and system overviews, with enums for component type (`service`, `library`, `database`, `queue`, `gateway`, `cache`, `external`, `ui`), diagram format (`mermaid`, `plantuml`, `d2`, `dot`, `ascii`), and connection type (`sync`, `async`, `event`, `stream`, `grpc`, `rest`, `graphql`, `websocket`). - _(Planned)_ — API-reference generation, an interactive tutorial system, and training/certification materials are described in the package metadata but are not present in the source today. --- ## Release Management (`@oshun/release-management`) Surface-scoped release safety: rollback-plan schemas, a rehearsal engine, and canonical rollback plans for the six v1 surfaces (V1/TODOS.md §28.8). - **Rollback Plan Schemas** — Zod schemas (`ReleaseSchema`, `RollbackPlanSchema`, `RollbackStepSchema`, `SemverSchema`) and enums (`ReleaseSurface`, `RollbackMechanism`) that define a validated rollback plan for a release. - **Plan Validation and Coverage** — `assertReleaseHasValidPlan`, `loadAndValidatePlan`, and `checkCoverage` verify that a release ships a well-formed rollback plan with adequate coverage. - **Rehearsal Engine** — `planExecutionGraph` builds an executable graph of a rollback plan and `runRehearsal` exercises it through injected step executors, surfacing failures before a real rollback is needed. - **Canonical Plans** — Pre-built rollback plans for the shell, admin, grounding, assistant, persona, and generation surfaces (`SHELL_ROLLBACK_PLAN`, `ADMIN_ROLLBACK_PLAN`, …), aggregated in `CANONICAL_ROLLBACK_PLANS`. - _(Not in scope)_ — semantic-version bumping, changelog generation, beta-cohort management, and app-store submission are not implemented by this package. --- ## Cryptography (`@oshun/crypto`) A single, audited crypto facade so internal Oshun code never re-implements primitives per domain. Every operation delegates to a published, KAT-verified library (`@noble/hashes`, `@noble/curves`, `@noble/ciphers`) — zero in-house crypto. `Uint8Array` is the canonical buffer type. - **Hashing** — `sha256`, `sha512`, `keccak256` (Ethereum-style, not FIPS-202), and `blake3` (variable-length output). - **Signing** — secp256k1 sign/verify/recover and ed25519 sign/verify. - **Authenticated Encryption** — AES-GCM and ChaCha20-Poly1305 encrypt/decrypt. - **Key Derivation** — `hkdf`, `pbkdf2`, `scrypt`, and `argon2id`. - **Key Agreement and Randomness** — ECDH and `randomBytes`. Keystore and secret submodules build on these primitives. --- ## Audit Platform (`@oshun/audit-platform`) Canonical platform-wide audit event ingestion, immutable storage, and investigation queries (ADR-0023, V1-GRC-009). This is the central audit infrastructure for the entire platform — distinct from the per-service audit logger in `@oshun/security`. All service-level audit entries eventually flow here for storage and query. - **Schema-Enforced Ingestion** — Every ingested event is validated against `CanonicalPlatformAuditEventSchema` from `@oshun/contracts`, which requires actor, action, outcome, reason, trace ID, target, and severity. - **Append-Only Storage** — The store exposes no update or delete operation; the only way to amend a past event is to ingest a new event referencing the original via `metadata.amends`. - **Investigation Queries** — Filter events by actor, action, outcome, severity, domain, resource, policy, retention tag, trace/request/session ID, time window, and free-text search. - **Agent-Tool and Retention Hooks** — Helpers for auditing agent tool calls and enforcing retention-tag policy (V1-GRC-013), plus V2 audit-publication request builders. --- ## Data Residency (`@oshun/data-residency`) Region and data-residency enforcement (V1-PRIV-018). The enforcer is I/O-light: it reads rule tables from `@oshun/contracts` and emits canonical audit events through an injected publisher; storage placement decisions belong upstream. The boundary between this library and `@oshun/region-rules` is: `data-residency` enforces transfer rules and routes DSR (data subject requests) to the correct regional queue; `region-rules` encodes which content is permitted per region. They are complementary, not overlapping. - **Residency Enforcement** — `ResidencyEnforcementService` decides whether a proposed cross-zone data transfer is permitted, given home zone, target zone, and transfer mechanism. - **DSR Routing** — `createDsrResidencyRoutingDecision` routes data-subject requests (the `DsrResidencyRequestKind` set) to the correct regional queue. - **Home-Zone Resolution** — `resolveHomeZoneFromClaim` derives a user's home zone from identity claims. - **Routing Headers and Context** — Residency routing headers and an async-context carrier (`runWithResidencyRoutingContext`) propagate zone metadata through request handling. --- ## Region Rules (`@oshun/region-rules`) V2 regional content rules — the `v2-regional-content-rules` module encoding which content is permitted in which regions. Consumed by enforcement logic in `@oshun/data-residency` and by domain content pipelines that need to check regional eligibility before publishing. --- ## Review Persistence (`@oshun/review-persistence`) The canonical persistence layer for Oshun review packages, mapping the Zod contracts in `@oshun/contracts` and the `ReviewPackage` Prisma model into a typed, validated API (ADR-0023, ADR-0029, V1-GRC-001). This library lives in `shared` because the review-package workflow spans multiple domains — content, moderation, and compliance all read and write review packages. A single persistence layer with schema enforcement ensures all domains operate on consistent, valid data. - **Validated Persistence** — Every persisted row validates against `ReviewPackageSchema`; every caller-visible return is a deep clone of stored state; `slug` and `id` uniqueness is enforced and `updatedAt` is refreshed on every mutation. - **Review Package Repository** — `InMemoryReviewPackageRepository` with `assembleReviewPackage`, filtering, sorting, and child-collection mutations (stages, decisions, delegations) that preserve schema invariants. - **Stage Graph Persistence** — A separate `InMemoryReviewStageGraphRepository` with `assembleStageGraph` and transition validation for review stage graphs. - **Template Registry** — A registry of review-package templates. --- ## Document and Media Processing A cluster of `@oshun/*` packages handles document understanding and media processing. They are domain-shaped (consumed primarily by Isis and other document-handling domains) but live in `shared` because multiple domains and apps depend on them. ### Vision LLM (`@oshun/vision-llm`) Convenience wrapper around the canonical `IsisLLMClient` for vision-locate tasks (V1-P2-0064). The wrapper owns prompt shaping, image normalisation, structured-output parsing, and the `VisionLocateResult` envelope; provider routing, retries, cost accounting, and quotas live in the gateway. Exports `OshunVisionLLMClient` and the `Vision*` type family (regions, grids, UI elements, text answers). ### Layout Analyzer (`@oshun/layout-analyzer`) Decomposes a rendered document page into the PubLayNet region taxonomy (`DOCUMENT_REGION_CLASSES`) via the canonical vision LLM (V1-P2-0064/0066). `OshunLayoutAnalyzer` produces a typed `LayoutAnalysisResult`; mAP@0.5 is the verification metric (`computeMeanAveragePrecision`, `iou`). ### OCR (`@oshun/ocr`) The canonical OCR client (V1-P2-0060) with three explicit tiers: `tier1_tesseract` (Tesseract.js WASM, the default), `tier2_vision_llm` (vision LLM via `IsisLLMClient`), and `tier3_cloud_ocr` (cloud Document AI). Tiers do **not** silently fail over — the caller chooses the tier explicitly. Exports `OshunOCRClient` and `TesseractOCRBackend`. ### ML Runtime (`@oshun/ml`) `OshunMLRuntime` — a single import surface for ONNX inference. `loadModel` fetches model bytes, verifies them against an expected SHA-256, and selects an execution provider by preference order (`webgpu`/`webnn`/`wasm`). `tensor` constructs typed tensors; `benchmark` measures inference speed. A `RuntimeAdapter` abstraction allows the underlying runtime to be swapped. ### Native Libraries (`@oshun/native-libs`) Thin typed wrappers plus acceptance tests over the audio/video/image native dependencies pinned by V1-P2-0110..0121 (`sharp`, `ffmpeg-static`, `fft.js`, `pdf-parse`, `mammoth`, `cheerio`, `pixelmatch`, `pdf-lib`, `imghash`, `pako`, `protobufjs`, `@peculiar/x509`). Each helper gives consumers one typed entry point per dependency so version drift is caught in one place: PNG re-encode, FFT power spectrum, PDF/DOCX text extraction, HTML parsing, pixel diff, perceptual hash, gzip, protobuf varints, X.509 parsing, FFmpeg path resolution. ### Media Encoding (`@oshun/encoding`) The professional encoding and delivery library from Phase 70.8 (`libs/shared/encoding`). Modules cover the FFmpeg-backed video encoder, codec-support negotiation, objective quality metrics (PSNR/SSIM/VMAF-class scoring), IMF delivery packaging, timeline assembly, shot optimization, and audio analysis — the mezzanine/delivery layer that Yemaya post-production and Isis generation outputs feed into. ### Content Security (`@oshun/content-security`) The content protection layer from Phase 70.9 (`libs/shared/content-security`): DRM policy and license handling, content provenance records, and forensic and visible watermarking, applied to generated and distributed media across domains. Complements the Themis originality shields (which judge similarity) by protecting content Oshun itself distributes. --- ## Inbound Integrations (`@oshun/inbound-integrations`) Typed adapters for inbound external systems so domains integrate against one shape per system: LMS, OneRoster, identity, calendar, payment, telemetry, BYOM (bring-your-own-model and BYOM model registration), notification, and health modules. The boundary here is intentional: domain code imports from `@oshun/inbound-integrations` and programs against a typed adapter interface. When a vendor changes their API, only this library changes — domain code is insulated. --- ## Tara Live Class Booking (`@oshun/tara-live-class-booking`) Shared booking primitives for Tara live yoga classes, consumed by Lilith and Oshun web/mobile surfaces. Defines `TaraLiveClassListing`, `TaraLiveClassBookingInput`, and `TaraLiveClassPaymentReceipt`, plus lineage disclosure types — `TaraLiveClassLineageDisclosure` carries a verified citation trail (`TaraLiveClassLineageCitation`) and an instructor lineage-fund contribution preference. This library lives in `shared` because both the Lilith commerce domain and the web/mobile surfaces need to read and display the same booking data structures. The single source of truth prevents format divergence between the booking flow and the receipt display. --- ## Sovereignty Closure Infrastructure Dependencies (Phases 139, 142, 145-152) Shared remains the home for reusable platform primitives under `libs/shared/*`, while Neith owns the new sovereign product implementations listed in TODO Phases 139, 142, and 145-152. The Shared domain must interoperate with these systems rather than duplicating them: - **Office and collaboration suite (Phase 139)**: Shared document, storage, auth, and collaboration primitives interoperate with the `@neith/docs-core` office substrate (writer/sheets/slides/notes/mail/calendar/PDF/knowledge-AI) rather than duplicating a document stack. - **Product analytics (Phase 142)**: Shared telemetry and consent primitives feed the `@neith/metron-*` analytics platform (event ingestion, identity, warehouse, replay, experimentation, attribution, surveys) instead of a parallel analytics pipeline. - **CI/CD and supply chain (Phase 145)**: Shared build, release, testing, artifact, provenance, and deployment helpers integrate with `@neith/ci-dsl`, `@neith/ci-runner`, `@neith/ci-actions`, `@neith/ci-cache`, `@neith/ci-artifact`, `@neith/ci-secrets`, `@neith/ci-env`, `@neith/ci-triggers`, `@neith/ci-insights`, `@neith/ci-security`, `@neith/ci-testing`, and `@neith/ci-governance`. - **Identity provider (Phase 146)**: Shared auth, JWT, mTLS, service identity, gateway, and middleware packages consume `@neith/idp-*` capabilities for directory, authentication protocols, authorization policy, federation, SCIM, MFA, CIAM, workload identity, and privileged-access management. - **Crash analytics (Phase 149)**: Shared logging, tracing, metrics, and observability primitives emit structured crash context into `@neith/crash-*` ingestion, symbolication, grouping, release-health, session, alerting, security, AI-triage, and dashboard workflows. - **Secrets and vault (Phase 150)**: Shared configuration, deployment, service discovery, and runtime packages integrate with `@neith/vault-*` for zero-knowledge items, dynamic secrets, leases, rotation, transit encryption, password/TOTP/passkey generation, autofill, CLI/SDK, sync, PAM, SSO, SCIM, policy, and audit. - **Endpoint security (Phase 151)**: Shared infrastructure hardening and deployment standards consume `@neith/edr-*` endpoint-agent, sensor, behavioral detection, response, threat-intel, forensics, vulnerability, malware-analysis, network, identity-threat, XDR, compliance, and operator console capabilities. - **Incident management (Phase 152)**: Shared alerting, SLO, runbook, deployment, and observability surfaces integrate with `@neith/incident-*`, `@neith/oncall`, `@neith/escalation`, `@neith/alert-ingest`, `@neith/notify`, `@neith/noise`, `@neith/war-room`, `@neith/status`, `@neith/runbook`, `@neith/slo`, `@neith/postmortem`, `@neith/intel`, `@neith/customer-incident`, and `@neith/gameday`. --- ## Concordia Platform Infrastructure (Phase 179) Shared owns the reusable infrastructure required by the Concordia substrate: identity verification hooks, party/representative/counsel role plumbing, tenant-scoped RBAC/ABAC, audit ledgers, consent ledgers, evidence custody, retention/legal-hold workflows, KMS/HSM integration, rate limits, abuse throttles, suspicious-access alerts, queue backpressure, feature flags, kill switches, observability, traces, metrics, and security test helpers. Concordia owns the bargaining flow; Shared owns the platform primitives that make that flow secure, observable, and compliant.