# ADR-0074: Yemaya Study & Deconstruction Workspace Architecture **Status**: Accepted (YSD-0120 and YSD-0122 approved by @GreyChimp on 2026-07-18 — see `docs/proposals/yemaya-study-workspace/decisions/decision-log.json`) **Date**: 2026-07-18 **Authors**: Study & Deconstruction Workspace program (checklist YSD-1001) **Reviewers**: @GreyChimp (decision owner) **Supersedes**: N/A **Superseded by**: N/A ## Context and Problem Statement The Yemaya Study & Deconstruction Workspace proposal (`docs/proposals/YEMAYA_STUDY_AND_DECONSTRUCTION_WORKSPACE_PROPOSAL.md`) defines a creator-facing product for studying film, video, audio, images, documents, creator-owned 3D, and games down to frame/region/event granularity, with rights-governed sources, evidence-anchored analysis, notebooks, and learning loops. The repository holds strong primitives (Studio shell, Nisaba study substrate, Sophia evidence anchors, real ffmpeg encoding libs, Metis mastery/FSRS, Bellona bridges, Neith 3D importers) but no composed product, no shared media-study contracts, and four incompatible rights vocabularies (see `docs/proposals/yemaya-study-workspace/schema-inventory.md`). This ADR fixes the architecture within which the SOTA implementation checklist (1,305 items) is delivered. ## Decision ### Logical architecture Five planes, each with one canonical owner: 1. **Experience plane (Yemaya).** The composed workspace UI inside Oshun Studio plus workspace-native aggregates: StudyProject composition, InspirationCollection/Item, OriginalConcept, CreativeDecision, ProjectTransfer. Client-neutral use cases live in `libs/yemaya/study-workspace`; the service is `apps/yemaya/svc-study-workspace`. 2. **Study plane (Nisaba).** Durable study semantics: annotations (W3C selector union extended with media selectors), typed links, comparisons, notebooks/StudyCards, commentary. Canonical notebook identity is Nisaba's. 3. **Evidence plane (Sophia).** EvidenceAnchor, provenance, citations, retrieval, confidence-bearing claims, rights dependencies on evidence. Every machine output and human observation anchors here. 4. **Lens plane (domain owners).** Hathor, Aja, Euterpe, Aglaea, Bellona+product runtimes, Metis, Isis, Iris, Neith/Maya expose capabilities through one `libs//study-adapter` each, per the versioned adapter convention in `docs/proposals/yemaya-study-workspace/responsibility-contracts.md` (semver contract version, capability discovery, YSD-2007 response vocabulary, domain-native ID preservation). 5. **Platform plane (Oshun + shared).** Identity, tenancy, permissions, Studio navigation, Library continuity, canonical audit events + hash chain (`libs/contracts` + `libs/shared/audit-platform`), content signing (`libs/shared/content-signing`), media encoding (`libs/shared/encoding`, `libs/shared/live-media`). ### Domain boundaries and data authority - PostgreSQL is authoritative; projections (search/vector/graph) are rebuildable. The workspace writes its aggregates to the existing `yemaya` database; Nisaba-owned records to `nisaba`; Sophia-owned records to `sophia` (all already provisioned per the infrastructure inventory). - One canonical source of truth per domain (YSD-0014): the workspace maps domain-native IDs through mapping tables, never re-mints them. - The rights resolver (checklist Section 4.1) is the single decision point for every action; the live-media playback-grant flow is the pattern it generalizes. No client, BFF, adapter, worker, projection, or export path bypasses it (YSD-4015). - Epistemic identity (source fact / detection / observation / interpretation / craft hypothesis / creator statement / practice result) is a contract property, not a UI label; no layer may silently promote one to another (YSD-2108). ### Trust boundaries 1. **Untrusted bytes:** every uploaded/parsed source (media, subtitles, documents, images, 3D, archives) crosses a quarantine + malware-scan + sandboxed-parser boundary with resource limits (YSD-4093/4095) before any store or model sees it. 2. **Untrusted text:** transcripts, subtitles, imported metadata, and web content never join system prompts or model tool contexts (YSD-4096). 3. **Tenant boundary:** tenant/project scoping is enforced in Postgres (row-level scoping per YSD-3003), object storage prefixes, projections, and every signed URL decision (re-checked at issue time, YSD-3021). 4. **Model boundary:** all inference goes through the Isis gateway with AnalysisRun identity; providers are substitutable; study sources stay in region unless the grant allows otherwise (decision draft YSD-0131). 5. **Rollout boundary:** production deployment is gated by `tools/yemaya-study/check-decision-log.mjs --enforce-rollout` while blocking P0 decisions remain unresolved (YSD-0139). ### Route placement Canonical route `/studio/study` inside `apps/oshun/web` (decision draft YSD-0122, proposal §3.3), entered from a global **Study** navigation item. Yemaya-branded creator mode with explicit Nisaba notebook and Sophia evidence rails. Durable saves land in shared Library collections, Nisaba study projects, and project-scoped inspiration collections. ### Deployment topology - `apps/yemaya/svc-study-workspace` deploys as an ECS Fargate service (standard terraform modules: ecs-services, alb, sqs, s3), with health/ readiness endpoints, structured logging, tracing, and metrics (YSD-1003). - Jobs run on BullMQ/Redis (default) with SQS+DLQ available for prod fan-out; heavy/GPU analysis executes via Isis on RunPod endpoints — GPU-dependent lenses are capability-gated, never assumed local. - Object storage: MinIO (dev) / S3 (prod) with the Section 3.2 namespace and lifecycle policies (quarantine, proxies, thumbnails, exports, scratch). - Search/vector projections start on Postgres FTS + pgvector; Elasticsearch, Qdrant, and Neo4j are adopted only on measured need (decision draft YSD-0129) — dev profiles already exist for all three. ### Migration path from specialist apps - `apps/yemaya/studio-web` (AnimationLearningPage, DailiesReviewPage) and `apps/aja/svc-reference-video` remain specialist/internal surfaces during migration. Their interaction concepts inform the workspace; their fixture/simulated data paths are not migrated (reuse ledger dispositions: replace). - The Aja reference-video type vocabulary maps into the Section 2 shared contracts through the Aja study adapter (YSD-1007) — wrapped, never forked; simulated probe/scene-detection surfaces as `unsupported` until rewired to `libs/shared/encoding`. - When the workspace reaches feature parity for a specialist surface, that surface is retired behind a redirect; retirement decisions are recorded as supersessions of this ADR's migration appendix, not silent removals. ## Consequences - The walking skeleton (YSD-1030) is implementable without any new infrastructure: existing databases, MinIO, BullMQ, ffmpeg, Studio shell. - Domain teams own their adapters; the workspace cannot ship analyzers ahead of contracts (YSD-0016) or adapters ahead of conformance tests (YSD-0163/0164 enforce once code exists). - Nx tags/dependency constraints and CODEOWNERS encode these boundaries (YSD-0121) once YSD-0120 is approved; architecture tests (YSD-0164) reject cross-plane violations mechanically. - Everything upstream of the route decision (contracts, service, adapters) is route-agnostic; a late route change costs one redirect, not a re-architecture. ## Alternatives considered - **Hathor-owned workspace** — rejected (proposal §3.1): overfits narrative; leaves camera/motion/sound/costume/learning under-composed. - **Standalone app outside Oshun Studio** — rejected: duplicates shell, Library, tenancy, and navigation; contradicts ADR-0013's unified Studio direction. - **Polyglot storage from day one** — rejected (decision draft YSD-0129): no measured need; Postgres+pgvector suffices for the first phases and projections are rebuildable by design. - **Direct reuse of aja/yemaya specialist code paths** — rejected: verified simulated/fixture paths (schema inventory, reuse ledger) would fabricate results inside a product that exists to be evidence-honest.