Disciplines · Decisions (ADRs)

ADR-0074: Yemaya Study & Deconstruction Workspace Architecture

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 dow

Accepted · 2026-07-18
4sections5 minread
Markdown source
On this page

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