The
libs/oshun/area: ~49 Nx libraries that make up the Oshun product platform — the cross-domain app shell, the canonical domain/substrate adapters, and the platform-wide foundations (auth, persistence, analytics, privacy, messaging, billing) that every Oshun surface composes.
What this area is#
Where libs/contracts/ owns the typed wire surface, libs/oshun/ owns the
product runtime that sits on top of it: the app shell a customer actually
uses, the adapters that normalize each backend domain into one stable
shell-facing interface, and the shared platform machinery (sessions,
persistence, analytics, notifications, payments) those surfaces lean on. Almost
every project carries the scope:oshun tag, and the layer: tag is the most
useful way to read the area — layer:domain for the per-domain and
per-substrate adapters,
layer:foundations/persistence/auth/analytics/privacy for the platform
spine, and layer:agentic for the content/creative-automation stack.
The product is organised around six customer domains — Tara (meditation /
practice), Veritas (story / fact-grounding), Nyx (sky / astronomy), Arete (goals
/ habits), Nisaba (study / primary texts), and Metis (learning) — and several
AI substrates that cut across them: Iris (memory), Sophia (evidence /
grounding), Isis (generation control), Lilith (persona policy / safety), Psyche
(real-time voice + avatar embodiment), and Aja (embodied instruction). Tara is
deliberately the experiential center; @oshun/design-language and
@oshun/navigation both encode a "Tara-centered" IA as a hard contract.
A recurring shape repeats across the domain packages: an *ApiAdapter contract,
a canonical *DomainAdapter (the shell-facing normalization), object models,
card-model builders for Home/Explore surfaces, deep-links/launch-actions
helpers, and canonical-adapter factories. Reading one domain package
(domain-tara, the largest at ~8.9K LOC) teaches you how to navigate them all.
A handful are thin facades by design — domain-metis is a 7-line re-export of
@metis/api-client — and the area is honest about that.
Sub-systems at a glance:
- App shell & presentation:
shell-core,shell-assistant,shell-achievements,shell-routines,shell-desktop,shell-wearable,navigation,ui,design-language,design-tokens,i18n,offline. - Customer domain adapters:
domain-arete,domain-metis,domain-nisaba,domain-nyx,domain-tara,domain-veritas,domain-registry. - AI substrate adapters:
memory-iris,evidence-sophia,generation-control-isis,persona-policy-lilith,persona-registry,embodiment-psyche,embodiment-aja. - Agentic / content stack:
agent-pipelines,agentic-studio,content-service,creative-orchestrator. - Platform foundations:
platform-foundations,persistence,analytics,privacy,trust-safety,auth(@oshun/auth-client),messaging-channels,render-farm. - Commerce, customer & operator surfaces:
billing-support,payments-bridge,customer-curation,customer-message-center,search-discovery,tenant-console,developer-portal,studio-authoring. - Integrations & cross-cutting:
concordia-integration,veritas-cascade-worker,color-science.
How it fits the wider system#
These libraries are the layer the apps (the web shell, mobile shell, admin
console) and the BFF import directly. The domain adapters consume the
libs/contracts/* Zod schemas and the per-domain API clients (@metis/...,
@iris/..., etc.) and present one normalized interface to the shell, so a shell
surface never talks to a raw backend. The platform packages — persistence
(Prisma over Postgres), auth-client, analytics, messaging-channels,
payments-bridge — are the shared substrate every domain and service leans on.
A few packages are explicitly scoped down or staged: search-discovery is
documented as retired from V1 scope until the live search candidates carry
real DiscoveryObject metadata, and agent-pipelines is a small grant/pipeline
skeleton. Walk the "used by" edges on any node below to see exactly who depends
on it.
Entity catalog (59)#
The 59 tracked Nx projects in oshun, each a code-linked entity node — package, type, source path, declared targets, and its internal dependency graph (depends-on / used-by, resolved from the package manifests, §6/§8), read from the project graph. Grouped by architectural layer; walk the dependency links to travel the system. 56 of these carry an authored deep-dive (what / why / how it fits); the rest are generated scaffolds awaiting one.
agentic (7)#
Oshun Agentic AI Studio cross-domain pipeline registry and grant resolver compatibility surface.
A small (~52 LOC) agentic skeleton: src/grants/resolver.ts (capability-grant
resolution) plus src/pipelines/index.ts, re-exported from src/index.ts. It
reserves the agent-pipeline + grant surface and is intentionally thin rather
than a full pipeline engine.
Oshun Agentic AI Studio (§18): registry, runs, plans, dashboard data, invocation, budgets, capabilities, feedback, modes, pipelines, tools, grants, hand-off
The operator-facing agentic studio (layer:agentic, ~6.9K LOC): a barrel over
twelve sub-modules — registry, runs, plans, invocation, budgets,
capabilities, feedback, modes, pipelines, grants, handoff,
dashboard (src/index.ts). It models agent runs, budgets, capability grants,
and a dashboard surface for governing autonomous agent invocations.
Cross-domain AI platform primitives for observability, reasoning, retrieval, governance, safety, efficiency, and training.
Phase 98 AI-platform completion layer (libs/oshun/ai-platform/src), a wide
single-package surface of 19 modules: agents (AgentPlanner,
MultiAgentDebate), rag (UnifiedRagPipeline, SemanticChunker,
QueryRouter), federated (AgentFederationGateway), plus compiler,
compliance, compression, efficiency, embeddings, integrations,
knowledge-graph, memory, model-security, multimodal, observability,
prompts, reasoning, safety, and simulations — the platform-side glue
above the Nous model runtime. AgentFederationGateway, A2ATaskManager, and
the webhook/SSE helpers are process-local prototypes, not a mounted or
conformant A2A client/server; ADR-0091 defers external A2A adoption.
Stands the agentic content stack (Iris-routed writer + Yemaya pipeline-runner quality loop + content-release-gates) up behind a real HTTP service with durable run persistence, retrieve/replay, and an operator dashboard surface (ledger §3.2)
An HTTP service (layer:agentic, ~1.1K LOC) that stands the agentic content
stack up behind a real server: ContentPipelineService, a
ContentStepDispatcher, durable run stores
(FileContentRunStore/InMemoryContentRunStore), and an HTTP router/server
(src/http-router.ts, http-server.ts). It composes existing
content-quality-judge / release-gate / Yemaya primitives rather than inventing a
new agent loop, and exposes replay + an operator dashboard surface.
ContentPipelineService12createDurableContentService12ContentServiceConfig12ContentStepDispatcher18PanelConfigError18ContentDispatcherConfig18ContentGrounding18ContentGroundingFactory18GenerationOutcome18FileCheckpointStore27FileContentRunStore27InMemoryContentRunStore27ContentRunStore27BRIEF_CEILINGS34 +14 moreAutonomous creative direction plane for the V1 Agentic AI Studio: opportunity sensing, idea synthesis + compellingness priors, Thompson-sampling portfolio selection under budget, a bounded-concurrency production loop over @oshun/creative-orchestrator, a Bradley-Terry variant tournament + calibrated publish gate, and a human review/steering/feedback surface that the preference learner feeds back into the next cycle. Fail-loud at every provider seam; never fabricates signals, ideas, artifacts, or scores.
The autonomous-creative plane (libs/oshun/creative-autonomy/src): a
director/ (director, producer, scheduler — the governor genuinely sleeps
between cycles), ideation/ with embedding-based novelty, portfolio/,
quality/, review/, signals/, steering/, and concurrency/ modules with
typed errors — surfaced over the BFF's /v1/agentic/autonomy/* routes.
V1_AGENT_RUN_FIELD_INVENTORY20V1_CYCLE_REPORT_FIELD_INVENTORY20V1_REVIEW_ITEM_FIELD_INVENTORY20adaptV1AgentRunToCommonRun20adaptV1CreativeCycleToCommonRun20adaptV1CreativeReviewToCommonRun20senseOpportunities28decayedStrength28normalizeTopic28sanitizeTopic28MAX_TOPIC_CHARS28SignalSource28SensedSignal28SenseOptions28 +207 moreAutonomous creative orchestrator (Phase 3): a real LLM planner (brief -> schema-validated CreativePlan DAG via @oshun/ai/agent-loop), a router that dispatches plan nodes to domain content generators under real governance (budget/kill-switch/throttle), and a critique->revise (Reflexion) loop around each generated artifact. Fails loud when no provider/generator is wired; never fabricates artifacts.
The autonomous creative orchestrator (layer:agentic, ~1.8K LOC): turns a brief
into produced content via decomposeBrief (schema-validated, acyclic
CreativePlan), governed routePlan dispatch, and a bounded reviseArtifact
critique→revise loop, built on @oshun/ai/agent-loop primitives. Includes a
BudgetGovernanceGate, DAG validation, and LLM-judge / metric critics;
documented as fail-loud (never fabricates a plan or artifact).
validateDagStructure21detectCycle21opologicalOrder21DagNode21DagStructureReport21CREATIVE_PLAN_SCHEMA28decomposeBrief29decomposeBriefBestOfN29bestOfNTemperature29PlannerOptions29CreativePlanResult29BestOfNOptions29BestOfNResult29PlanCandidateReport29 +56 moreCanonical cross-domain skill contracts, registry, discovery, governance, and interoperability runtime.
Phase 97 cross-domain skill system (libs/oshun/skill-system/src):
SkillRegistry (Postgres and in-memory stores), discovery/source-scanner,
semver-aware dependencies, composition and agent-tree execution,
governance with SkillQuotaManager, a ProcessSandboxExecutor with a
bubblewrapIsolationLauncher seam, plus evolution, generation, quality,
and training modules feeding skill telemetry back into the flywheel.
analytics (1)#
Typed analytics event APIs for OSHUN shells and domains
The platform's typed analytics layer (~43K LOC, the second-largest node): an
AnalyticsClient with context propagation and sink fan-out, plus the canonical
machine-readable event taxonomies (customer-taxonomy, admin-taxonomy,
assistant-taxonomy, flows-taxonomy) and a large body of V1/V3 readiness,
budget, and dashboard manifests (e.g. v3-web-first-load-budget,
v1-launch-readiness-manifest). src/README.md is authoritative.
auth (1)#
Client-side auth and session handling for OSHUN apps
The client-side auth/session library (libs/oshun/auth, project
@oshun/auth-client, ~9.7K LOC): the canonical single-customer auth model
(customer-auth-model.ts), AuthClient with login/logout/refresh and
single-flight refresh protection, pluggable AuthTransport/SessionStore,
secure-storage adapters, entitlements, SSO coordination, and feature-gating for
shell and Metis surfaces.
billing (1)#
Oshun Support, Entitlements, Billing (§23): entitlements, paywalls, dunning, self-serve refunds, tax/region billing, metered usage, support cases
The billing + support library (~1.6K LOC): a barrel over entitlements,
paywalls, dunning, self-serve, tax-billing, metered, and
support-cases, plus a billing-aje-bridge linking billing to the Aje payment
domain. Covers the subscription/metering/support-case surface, not the raw
payment rails (see payments-bridge).
customer (3)#
Oshun customer curation contracts (§17): notebooks, collections, study queues, ritual sets, reading lists, saved searches, sharing, share cards, annotations, bookmarks, version awareness
The customer save/share surface (~2.8K LOC): a barrel over collections,
sharing, share-cards, annotations, bookmarks, and version-awareness
(src/index.ts) — the cross-domain library/curation features a customer uses to
organize and share saved content.
Customer-visible message center (§20.7 line 2993): history, unread, deep links, delivery receipts, unsubscribe.
A focused in-app message-center module (~423 LOC): src/message-center.ts
re-exported from the barrel, modeling the customer-facing message/notification
inbox.
Oshun Living Scene viewer/creator social layer: contemplative appreciations, follows and premieres, audience analytics, counsel-gated tips, group practice sessions, score-editor history, and session recaps
Shared scene/social experience toolkit (libs/oshun/scene-experience/src):
group-sessions, reactions and appreciation aggregation
(recordAppreciation, buildCreatorAppreciationDigest), follows,
audience-analytics, and a scene-vocabulary shared across surfaces.
design (2)#
Tara-centered Oshun product language, IA, and experience-quality rules
The product's design-language contract (~3.4K LOC, layer:design): exported
const contracts such as TARA_CENTERED_PRODUCT_LANGUAGE, OSHUN_UNIFIED_IA,
OSHUN_VISUAL_THESES, and OSHUN_EXPERIENCE_QUALITY_RULES, plus
voice-and-tone, surface-language, responsive-system, scorecards,
AI-disclosure-copy, and failure-copy modules — the codified, test-backed rules
for how Oshun looks and speaks.
TARA_CENTERED_PRODUCT_LANGUAGE1OSHUN_UNIFIED_IA8OSHUN_VISUAL_THESES29OSHUN_EXPERIENCE_QUALITY_RULES36assertSurfaceUsesTaraLanguage58Core design tokens and semantic themes for OSHUN
Centralized design tokens (layer:design, ~2.6K LOC): a schema-first token
model (oshunTokenSchema) and the canonical oshun-v1-foundation bundle for
color, typography, spacing, elevation, and motion, plus behavior contracts for
domain-accent, grounded-evidence, disclosure/synthetic-indicator, and
persona-switching. src/index.ts re-exports ./tokens (ships a prebuilt
tokens.js alongside the TS source).
developer-portal (1)#
Oshun developer portal substrate (§20.6 line 2976): OpenAPI generation, code examples, sandbox tenant policy, integration certification, developer documentation registry
The developer-portal toolkit (~1.3K LOC, layer:developer-portal):
openapi-builder, code-example-generator, sandbox-tenant-policy,
certification-suite, and developer-docs-registry (src/index.ts) — the
machinery behind third-party developer docs, sandbox tenancy, and certification.
discovery (1)#
Canonical search, discovery, recommendation, and concept-graph contracts for OSHUN (V1 §15)
The discovery/ranking library (~4.1K LOC, layer:discovery) — explicitly
retired from V1 scope per the audit notice atop src/index.ts: its ranker
scores DiscoveryObject features (persona-tone fit, evidence integrity,
grounding state, per-object entitlement) the live /v1/search candidates do not
carry, so V1 does not adopt it rather than fabricate those signals. The modules
(catalog, signals, aggregation, candidates, ranker, experiments,
cold-start, concept-graph, evals) remain tested as the V1.x adoption
target.
domain (24)#
Production color-science foundations for OSHUN imaging workflows
A real color-management engine (~6.4K LOC, layer:domain): ACES 2065-1 / ACEScg
color-space definitions and conversion matrices, OCIO v2 config generation, HDR
mastering, gamut compression, camera IDTs, and display/look transforms
(src/lib/aces-2065-1.ts, acescg.ts, ocio-config-generation.ts, …) with
.spec.ts coverage. Domain-specific math, not CRUD.
ACES_2065_1_ENCODING_PRIMARIES1ACES_2065_1_PRIMARIES1ACES_2065_1_TO_XYZ_D60_MATRIX1ACES_2065_1_TRANSFER_FUNCTION1ACES_2065_1_WHITE_POINT1ACES_2065_1_WHITE_POINT_NAME1XYZ_D60_TO_ACES_2065_1_MATRIX1convertAces2065_1ToLinearSrgb1convertAces2065_1ToXyzD601convertLinearSrgbToAces2065_11convertXyzD60ToAces2065_11createAces2065_1ColorSpace1validateAces2065_1Triplet1Aces2065_1ColorSpaceDefinition1 +206 moreOshun platform-wide integration of Concordia: navigation, events, consent, telemetry (Phase 179.6).
A focused Phase-179.6 integration bridge (~159 LOC): Zod-validated nav-item,
event-subscription, telemetry-sink, and registration schemas plus
orderNavItems / subscriptionsForEventType helpers
(src/integration-hooks.ts) that wire the Concordia mediation domain into the
wider Oshun shell.
ConcordiaNavItemSchema8ConcordiaEventSubscriptionSchema8ConcordiaTelemetrySinkSchema8ConcordiaIntegrationRegistrationSchema8orderNavItems8subscriptionsForEventType8ConcordiaNavItem8ConcordiaEventSubscription8ConcordiaTelemetrySink8ConcordiaIntegrationRegistration8Arete domain adapter contracts and API client for the OSHUN shell
The canonical Arete (goals / habits) shell adapter (~8.3K LOC): object models
for habits/goals/routines/reviews, humane streak-recovery and friction-taxonomy
helpers, coaching-summary surfaces, accountability flows, and cross-domain
relationship helpers to Tara/Nisaba/Metis/Veritas, behind
createCanonicalAreteDomainAdapter. Follows the standard adapter shape
(src/index.ts, README.md).
Metis domain adapter facade for the OSHUN shell
A deliberately thin facade (~7 LOC): src/adapter.ts re-exports
@metis/api-client, aliasing createMetisAdapter to
createMetisDomainAdapter. The Metis (learning) domain's real logic lives in
@metis/*; this package just exposes it under the Oshun domain-adapter naming
convention.
Nisaba domain adapter contracts for the OSHUN shell
The canonical Nisaba (study / primary texts) shell adapter (~3.2K LOC):
NisabaApiAdapter/NisabaDomainAdapter contracts, passage/concept/reminder/
workspace/search models, createCanonicalNisabaDomainAdapter, card-model
builders, launch-action and deep-link helpers, and shared concept-graph linkages
carrying passages into Tara/Arete/Veritas/Nyx paths (src/index.ts,
README.md).
Nyx domain adapter contracts and API client for the OSHUN shell
The canonical Nyx (sky / astronomy) shell adapter (~10K LOC, one of the larger
domain packages): the standard adapter surface plus a substantial depth/
sub-package of real ephemeris computations — lunar-phase-calendar,
twilight-schedule, object-transit, equation-of-time, zodiac-position,
planetary-hours, solar-terms, chart-angles, and more (src/index.ts).
Domain-specific astronomy, not CRUD.
Domain metadata, boundary guards, and launch contracts for Tara, Veritas, Nyx, Arete, Nisaba, and Metis
The typed domain-metadata registry (~731 LOC): canonical metadata for Tara,
Veritas, Nyx, Arete, Nisaba, and Metis (name, tagline, accent, capabilities,
route, auth, analytics-id, channels), availability states, shell-narrative and
launch contracts, offline-fallback cards, and runtime guards (src/registry.ts,
guards.ts). The lookup table the whole shell keys domains by.
LILITH_CURRENT_RELEASE8PAYMENT_RAIL_IDS8V1_DEFERRED_DOMAIN_IDS8V1_DEFERRED_DOMAIN_REASON8V1_DEFERRED_DOMAIN_RELEASE8V1_DEFERRED_PAYMENT_RAIL_IDS8V1_DEFERRED_PAYMENT_RAIL_REASON8V1_DEFERRED_PAYMENT_RAIL_RELEASE8V1_SCOPED_DOMAIN_COUNT8V1_SCOPED_DOMAIN_IDS8V1_SCOPED_PAYMENT_RAIL_IDS8filterToV1ScopedDomainIds8filterToV1ScopedPaymentRails8filterToV1ScopedDomains8 +14 moreTara domain adapter contracts and API client for the OSHUN shell
The canonical Tara (meditation / practice) shell adapter and the largest domain
package (~8.9K LOC): ritual object models, ritual-assembly rules composing
meditation/breathwork/passage/journaling/Nyx-perspective steps, scheduling,
edit/skip/recover operations, completion events with downstream projections,
audio-session management, plus Lilith tone-review and crisis-handoff bindings
(src/index.ts, README.md). Tara is the product's experiential center.
Veritas domain adapter contracts and API client for the OSHUN shell
The canonical Veritas (story / fact-grounding) shell adapter (~12.3K LOC):
object models for stories/claims/explanations/timelines/counterclaims, and
namespaced sub-systems for source-quality, attestor workflow, counterclaim
balance, topic-hub composition, retraction-cascade UX, contradiction detection,
and an editorial state machine (src/index.ts). Includes Sophia-evidence and
Nisaba-lineage relationship helpers and trust-display rules.
Canonical Aja embodied-instruction adapter contracts for OSHUN and Metis
The Aja embodied-instruction adapter (~424 LOC): src/adapter.ts normalizes the
embodied-instruction contracts from @oshun/contracts/aja (demonstration,
coaching-overlay, session-handoff across fitness/yoga/dance domains) into a
versioned Oshun envelope, plus a canonical-adapter. A real adapter, smaller in
scope than Psyche.
Canonical Psyche embodiment adapter contracts for OSHUN real-time voice and avatar sessions
The canonical Psyche real-time embodiment adapter (~14.2K LOC): one normalized
embodiment-profile / live-session-state / disclosure / session-planning surface
over the fragmented Psyche orchestrator, persona-service, conferencing, and
translation/avatar-quality libraries. Covers voice orchestration, turn-taking,
backpressure, reconnect, provider-failover, latency/quality dashboards, emotion
modulation, and crisis-frame handling (src/index.ts, README.md).
Canonical Sophia evidence adapter contracts for OSHUN grounded flows
The canonical Sophia grounding/evidence adapter (~2.9K LOC): shared evidence,
citation, source-set, source-lifecycle, and grounded-answer DTOs plus
educational-claim-grounding, modeled as a cross-cutting substrate behind
Veritas claim inspection, Nisaba study grounding, assistant grounded answers,
and Studio research-integrity flows (src/index.ts, README.md) — not a peer
shell domain.
Canonical Isis generation control adapter contracts for OSHUN
The canonical Isis generation-control adapter (~9.7K LOC): one stable
control-plane contract over Isis's many surfaces — workflow-template and model
registries, provider-registry and RunPod/ComfyUI routing, environment promotion,
release gates, provenance-bundle schemas, Civitai intake/review, and ComfyUI
governance, fronted by a generation-dispatcher and dispatch-guard
(src/index.ts, README.md).
Canonical Iris memory adapter contracts for OSHUN assistant continuity and memory controls
The canonical Iris memory adapter and one of the largest nodes (~18.2K LOC): a
single tier/scope/consent model unifying the divergent @iris/contracts and
@iris/memory-core taxonomies, with assistant-identity, conversation/profile/
session/notebook memory, consent-ledger, data-rights, retention-compaction,
conflict-resolution, sensitive-context, admin-inspection, and
persistence/recall/ inference sub-packages (src/index.ts, README.md).
Canonical Lilith contemplative persona policy adapter contracts for OSHUN
The canonical Lilith persona-policy adapter (~21.4K LOC): one policy-pack /
safety-tone surface over Lilith's fragmented moderation, spiritual-guidance,
crisis-safety, and voice-safety services — contemplative-tone and
generation-gentleness-floor policies, spiritual-boundary and unsafe-claim
overlays, crisis-safety analyzer + recovery, operator-override governance,
tenant-policy constraints, and a battery of eval-* harnesses (src/index.ts,
README.md).
Canonical persona registry — contract layer for Tara/Arete/Veritas/Nyx/Nisaba personas and cross-domain copilots.
The canonical persona registry and contract layer (~26.6K LOC): an immutable
registry-snapshot record/aggregate shape with a deterministic fingerprint and
pure get/list/filter/validate operations, plus family taxonomy, mandatory
metadata, approval lifecycle, coverage, scorecards, disclosure-visibility
measurement, voice-provider abstraction, avatar packs, and impersonation/clone
red-team evals (src/index.ts). Dependency-free so any domain can consume it.
PersonaId39PERSONA_FAMILY_KINDS46PersonaFamilyKind57PERSONA_APPROVAL_STATUSES71PersonaApprovalStatus84PERSONA_APPROVAL_STATUSES_CANONICAL89PersonaApprovalStatusCanonical99PERSONA_APPROVAL_STATUS_ALIASES105canonicalizePersonaApprovalStatus121PERSONA_SURFACES132PersonaSurface147PersonaRecord158PERSONA_SCOPE_KINDS205PersonaScopeKind216 +22 moreUnified typed product-knowledge property graph — one node/edge/provenance model, kind-aware validator, index-backed traversal, and Merkle content addressing over every compiled product representation (curated catalog, e2e journeys, docs, TODOS, architecture docs, anchors, tours, invocation points, routes)
Cross-domain achievements + accountability (~3.4K LOC): achievement definitions
and an unlock/progress engine, social-accountability partnerships and check-ins,
and community challenge templates spanning Tara/Veritas/Nyx/Arete
(src/achievement-engine.ts, src/index.ts).
DEFAULT_CROSS_DOMAIN_STATS55DEFAULT_ACHIEVEMENT_ENGINE_CONFIG55LEVEL_DEFINITIONS55createAchievementId55createPartnershipId55createInviteId55createCheckInId55createMessageId55createChallengeId55createParticipationId55resolveLevelFromXp55xpToNextLevel55resolveTierFromPoints55valuateCondition55 +42 moreVoice-first cross-domain assistant for the OSHUN shell home — intent classification, domain action routing, and conversational AI orchestration across Tara, Veritas, Nyx, Arete, Nisaba, and Metis
The voice-first cross-domain assistant (~14.3K LOC): createAssistantEngine
orchestrates intent classification, domain action routing, conversational
response formatting, persona handoffs, safe fallbacks, cross-domain continuity,
and bridges to Iris memory and Psyche sessions across all six domains
(src/assistant-engine.ts, src/index.ts).
ALL_DOMAIN_IDS88DEFAULT_ASSISTANT_CONFIG88createSessionId88createTurnId88NYX_OBSERVATION_CONDITIONS88isNyxObservationConditions88TARA_INTENTS103VERITAS_INTENTS103NYX_INTENTS103ARETE_INTENTS103NISABA_INTENTS103METIS_INTENTS103CROSS_DOMAIN_INTENTS103CONVERSATIONAL_INTENTS103 +114 moreThe core app-shell library (~20.3K LOC, one of the largest): consumer-shell
entry-points and domain-navigation, home orchestration, library aggregator,
activity timeline, notification/message centers, command surface, calendar-sync
(with real execution), onboarding/feature education, feature experiments, public
profiles, account switcher, and route analytics (src/index.ts).
CONSUMER_SHELL_ENTRY_POINT_IDS13DEFAULT_CONSUMER_SHELL_ENTRY_POINT_ID13buildConsumerShellEntryPointHref13filterConsumerShellEntryPoints13getConsumerShellEntryPoint13getConsumerShellEntryPointRoute13isConsumerShellEntryPointId13listConsumerShellEntryPoints13CONSUMER_SHELL_DOMAIN_IDS34buildConsumerShellDomainHref34getConsumerShellDomainDefinition34getConsumerShellDomainRoute34isConsumerShellDomainId34listConsumerShellDomainDefinitions34 +225 moreA framework-agnostic desktop-shell surface (~3.5K LOC): window manager, system
tray + quick actions, global shortcuts, OS notifications, custom oshun://
protocol handler, auto-update manager, and sidebar widget engine
(src/desktop-engine.ts, src/index.ts).
DEFAULT_MAIN_WINDOW_CONFIG59DEFAULT_MINI_PLAYER_CONFIG59DEFAULT_QUICK_CAPTURE_CONFIG59DEFAULT_SETTINGS_CONFIG59WINDOW_CONFIGS59DEFAULT_TRAY_QUICK_ACTIONS59DEFAULT_SHORTCUTS59DEFAULT_NOTIFICATION_PREFERENCES59DEFAULT_UPDATE_PREFERENCES59DEFAULT_SIDEBAR_CONFIG59DEFAULT_DESKTOP_PREFERENCES59createDefaultDesktopStats59createWindowId59createNotificationId59 +34 moreThe cross-domain morning/evening routine system (~3.4K LOC): routine templates
spanning Tara (meditation/breathwork/body-scan) and Arete (review/planning/
journal/reflection/gratitude) steps, a step-execution engine, personalized
recommender, and analytics (src/routine-engine.ts, src/index.ts).
DEFAULT_ROUTINE_ENGINE_CONFIG50createRoutineId50createUserRoutineId50createExecutionId50createStepId50getStepDomain50MORNING_ROUTINE_TEMPLATES60EVENING_ROUTINE_TEMPLATES60ALL_ROUTINE_TEMPLATES60getRoutineTemplate60getTemplatesByType60getTemplatesByTags60getTemplatesByDuration60xecuteStep71 +14 moreThe wearable-companion system (~3.5K LOC): streak widgets, watch complications,
smart reminders with timing inference, daily/weekly summary companions, haptic
patterns, and notification payloads optimized for wearable surfaces
(src/wearable-engine.ts, src/index.ts).
DEFAULT_WEARABLE_PREFERENCES55STREAK_MILESTONES55createReminderId55createSummaryId55createNotificationId55createDeviceId55createDefaultStats55isWithinQuietHours55getNextMilestone55isStreakAtRisk55computeHabitCompletionRate55formatStreakText55formatMinutesShort55domainColor55 +100 moreEvent-bus worker that subscribes the Veritas retraction-cascade consumer to veritas.retraction.cascade.dispatched
A focused retraction-cascade worker (~285 LOC):
subscribeRetractionCascadeWorker plus event-bus and contract-persistence
ports, and persistence-backed Sophia re-grounders / Metis revalidators
(src/veritas-cascade-worker.ts, composition.ts,
persistence-regrounders.ts). It listens for Veritas retractions and re-grounds
downstream Sophia answers and Metis lessons.
subscribeRetractionCascadeWorker1RetractionCascadeWorkerOptions1createEventBusRetractionEventPort5createContractPersistenceRetractionPort5createPersistenceBackedSophiaReGrounder9utSophiaGroundedAnswer9loadSophiaReGroundingVerdict9SOPHIA_GROUNDED_ANSWER_STORE_KEY9SOPHIA_REGROUNDING_VERDICT_STORE_KEY9SophiaGroundedAnswerDocument9createPersistenceBackedMetisRevalidator9utMetisLessonSources9loadMetisRevalidationVerdict9METIS_LESSON_SOURCES_STORE_KEY9 +1 morefoundations (1)#
Oshun Platform Foundations (§27+§28): service discovery, public OAuth 2.1 API, typed contracts, canonical role model, step-up auth, secrets, validated configs, rollback plans, abuse controls
The platform-foundations spine (~2K LOC, layer:foundations): a barrel over
service-discovery, public-api, shared-contracts, role-model, step-up
(auth), secrets, configs, rollback, and abuse-controls (src/index.ts)
— the shared platform primitives services compose at the bottom of the stack.
i18n (1)#
Oshun locale catalog, formatting, fallback, and RTL metadata
The V1 locale catalog and formatting library (~721 LOC): the canonical
OSHUN_LAUNCH_LOCALES set (en-US, es-US, fr-FR, de-DE, ar, he, ja-JP, pt-BR),
the customer-message translation maps, Intl-based date/number/currency/region
formatting, the documented language-fallback chain, RTL direction metadata, and
text-expansion budgets for layout QA (src/index.ts).
OSHUN_LAUNCH_LOCALES26OshunLaunchLocale36OSHUN_DEFAULT_LAUNCH_LOCALE38OSHUN_LAUNCH_LANGUAGE_PREFERENCES40OshunLanguagePreference50LANGUAGE_PREFERENCE_TO_LAUNCH_LOCALE52LAUNCH_LOCALE_TO_LANGUAGE_PREFERENCE65LAUNCH_LOCALE_LABELS78LANGUAGE_PREFERENCE_LABELS89RTL_LOCALES99isOshunLaunchLocale101isOshunLanguagePreference105languagePreferenceToLaunchLocale109launchLocaleToLanguagePreference119 +17 moreinfrastructure (1)#
Shared render-farm scheduling primitives for job submission, worker dispatch, dependency execution, preemption, and checkpoint resume
Shared render-farm scheduling primitives (~2.5K LOC, scope:shared,
layer:infrastructure): priority queues, worker-node capability matching,
dependency execution, preemption, cost estimation, cloud-burst planning,
checkpoint/resume, frame previews, and dashboard snapshots
(src/render-farm.ts, types.ts, src/index.ts).
navigation (1)#
offline (1)#
Offline cache and sync queue helpers for OSHUN apps
Platform-agnostic offline helpers (~318 LOC, layer:offline): a TTL-backed
OfflineCache, a retry/backoff OfflineSyncQueue, computeBackoffDelay policy
helpers, and a canProcessQueue connectivity gate (src/index.ts, README.md)
for mobile/web/PWA shells.
payments (2)#
V1 fiat payment rail — Stripe Billing subscription lifecycle, Apple Pay / Google Pay wallet-token verification and decryption, and the fiat-side entitlement-bus emitter that gives crypto/fiat schema parity (§23).
Fiat payment rail (libs/oshun/fiat-payments/src): a stripe/ client with
webhook-verifier, event-normalizer, price-catalog,
subscription-lifecycle, and settlement-processor; wallets/ for Apple Pay
and Google Pay (including ec-spki key handling); and an entitlement-emitter
that turns settled payments into entitlement events. Fail-closed by design when
credentials are absent.
Bridge between Aje (libs/aje/) merchant invoice contracts and the V1 payment event/entitlement domain — §23.1 crypto settlement.
The payment-rails bridge (~4.6K LOC, layer:payments): a state-mapper,
trust-tier disclosure, and sub-modules for oracle-aggregator,
cold-spend-queue, receipt-signer, entitlement-bus, customer/admin
surfaces, and security-gates (src/index.ts) — the lower-level
payment/entitlement plumbing beneath billing-support.
persistence (1)#
Canonical OSHUN V1 contract persistence schema registry and drift checks
The persistence layer and by far the largest node (~174K LOC, but ~4.2K of that
hand-written — the bulk is the generated Prisma client under src/generated/):
a contract-persistence registry/service, contract-record repository, durable
memory/snapshot/audit stores, a gold-set-entry store, DSAR deletion-cascade and
erasure runtimes, tombstone semantics, migration plans, and Zod↔Prisma
introspection (src/index.ts). The Postgres-backed substrate for the platform.
privacy (1)#
Oshun Privacy/Consent/Residency/DSAR (§22): consent taxonomy, granularity & withdrawal, region routing, export/deletion/retention, privacy center, DSAR workflow, compliance
The privacy/compliance library (~1.9K LOC, layer:privacy): a barrel over
consent, residency, export-deletion, privacy-surface, dsar, and
compliance (src/index.ts) — the customer-facing and operational privacy
machinery (DSAR, residency, export/deletion) that complements the persistence
layer's erasure runtimes.
safety (1)#
Oshun Trust and Safety (§21): policy taxonomy, severity classes/SLAs, decisions/appeals, crisis handling, abuse-pattern detection, operator surfaces, evaluation gates
The trust & safety library (~2.2K LOC, layer:safety): a barrel over
policy-taxonomy, severity, decisions, crisis, abuse-patterns,
operator-surfaces, and evaluation (src/index.ts) — the policy/enforcement
model and operator review surfaces for safety decisions.
security (1)#
Standards-compliant C2PA manifest mint/verify for off-platform export — wraps the c2pa-node SDK behind a fail-loud configuration seam and maps Oshun provenance sidecars into interoperable Content Credentials.
C2PA content-credential export (libs/oshun/c2pa-export/src): mint builds the
manifest, signer signs it, verify round-trips the credential — the
provenance seam the media release gates call before anything ships publicly.
shared (2)#
Composition root: assembles the agentic runtime (provider + tools + memory + channels) into one runnable multi-channel assistant (Hermes-parity spine)
The agentic-runtime composition root (layer:shared, ~11K LOC across 52 source
files; barrel at libs/oshun/assistant/src/index.ts, 337 lines). The
package.json calls it the "Composition root: assembles the agentic runtime
(provider + tools + memory + channels) into one runnable multi-channel assistant
(Hermes-parity spine)". createAssistant() resolves a real @oshun/ai provider
(createAnthropicProvider/createOpenAIProvider/createGoogleProvider/…,
fail-loud ProviderConfigError when a cloud key is absent), mounts
builtinTools, and wires them through the governed AgentRunManager +
KillSwitchRegistry from @iris/agents-core into a single Assistant.ask()
any channel adapter can drive.
It composes engines rather than re-implementing the LLM loop — that loop and the
provider adapters live in iris and @oshun/ai — but the parts it owns are real
domain logic, not scaffolds. src/channels/ carries
Telegram/Slack/Discord/email-IMAP/Signal bridges sharing one crisis-safety net
(detectCrisis short-circuits before the model ever runs); src/scheduling/ a
deterministic, DST-safe NL grammar (parseNaturalSchedule,
zonedWallClockToEpoch) over cron with Postgres stores and a RedisLeaseGuard;
src/skills/ real TF-IDF (idfWeights, lexicalScore) and cosineSimilarity
ranking; src/subagents/ an isolated-delegation pipeline over governed child
runs; plus InMemory/PostgresConversationMemory. The Hermes-parity spine
wiring Oshun's previously-isolated agent infrastructure into one autonomous,
multi-channel assistant.
Assistant10DEFAULT_ASSISTANT_SYSTEM_PROMPT10AssistantConfig10AskParams10AskResult10createAssistant18CreateAssistantOptions18createAssistantProvider20ProviderConfigError20DEFAULT_MODELS20AssistantProviderName20ProviderFactoryConfig20ResolvedAssistantProvider20builtinTools29 +274 moreChannel abstraction + tier-aware dispatcher for messaging surfaces (§26.1)
The shared multi-channel messaging library (layer:shared, ~6.8K LOC): a
transport registry + dispatcher with real transports (HTTP/2 fetch, SMTP email,
web-push) and per-channel sub-modules for Telegram (bot, inline, payments,
publishing, STT, Sophia-grounder), WhatsApp, email, SMS, Discord, Slack, and
push, plus reminder producers/scheduler/worker and deliverability tracking
(src/index.ts).
studio (2)#
Oshun Studio authoring contracts (§16): creator roles, authoring blocks, editorial lifecycle, asset metadata, taxonomy curation, localization workflow, versioning, collaboration, templates
The Studio authoring toolkit (~5.4K LOC, layer:studio): a barrel over
creator-roles, authoring-blocks, editorial-lifecycle, asset-metadata,
taxonomy-curation, localization-workflow, versioning, collaboration, and
templates (src/index.ts) — the content-authoring/editorial machinery behind
the creator/Studio surfaces.
Tara Content Workbench domain logic: spark capture, concept maturity ladder, duration-typed script blocks, knowledge-grounding claims/sources, steering overlays, category registry merge, publish-manifest building (V1/TARA_CONTENT_WORKBENCH_DESIGN_2026-07-19.md)
tenant (1)#
Oshun Tenant Console + Operator Toolkit (§20): tenant model, identity/SSO/SCIM, custom roles, audit explorer, bulk ops, integrations, notifications, help center, status page
The tenant/operator console library (~6.2K LOC, layer:tenant): a barrel over
tenant-model, identity, roles, audit-explorer, bulk-ops,
integrations, notifications, help-center, and status-page
(src/index.ts) — the multi-tenant administration surface.
ui (1)#
Shared UI primitives and theme contracts for OSHUN surfaces
The shared UI primitives + theme library (~479 LOC, layer:ui): real React
components — layout (Box, Stack, Text), controls (Button, IconButton,
Card), data-display (ListRow, StatTile, Badge, Chip), feedback
(Toast, Banner, EmptyState, ErrorState), overlays (BottomSheet,
Modal, ActionSheet, CommandPalette), and navigation (BottomNav,
TopBar, DomainSwitcher) — plus motion helpers and a theme contract, with
Storybook stories (src/index.ts, README.md).
workbench-kit (1)#
Domain-neutral workbench UI shell, primitives, and the kit-owned invariants a domain plugin may not override (ADR-S1 layer:workbench-kit)
DEFAULT_KEY_BINDINGS18DESTRUCTIVE_COMMANDS18DROP_FRAME_RATES18END_CONVENTIONS18END_SEMANTICS18FIELD_SEMANTICS18FLICKS_PER_SECOND18ID_SOURCES18KEY_MAP_FAULTS18KEY_SCOPES18MAX_SAFE_FLICKS18MIN_FRAME_TARGET_PX18NAMED_FRAME_RATES18NARROW_CANVAS_PX18 +3092 more