# Yemaya Study & Deconstruction Workspace Proposal > A comprehensive, evidence-grounded workspace for learning filmmaking and game > development by deconstructing existing works, connecting references from > whole-work structure down to frames and regions, and transforming organized > inspiration into original worlds, concepts, and craft decisions. | Field | Value | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Date | 2026-07-18 | | Decision status | Proposed | | Primary product owner | Yemaya | | Study and notebook substrate | Nisaba | | Evidence and provenance substrate | Sophia | | Canonical product shell | Oshun Studio | | Scope | Film, television, animation, cinematics, gameplay footage, instrumented game sessions, still images and concept art, scripts, storyboards, documents, paratexts, and creator-owned project assets | | Audience | Product, design, film, game, learning, ML, data, platform, safety, legal, and domain engineering teams | | Implementation status | Product and architecture proposal; it does not claim that the end-to-end workspace is currently shipped | --- ## Table of Contents 1. [The Short Answer](#1-the-short-answer) 2. [Executive Summary](#2-executive-summary) 3. [Ownership Decision](#3-ownership-decision) 4. [Product Thesis, Goals, and Boundaries](#4-product-thesis-goals-and-boundaries) 5. [What Exists Today](#5-what-exists-today) 6. [Primary Users and Jobs](#6-primary-users-and-jobs) 7. [Core User Journeys](#7-core-user-journeys) 8. [Workspace Information Architecture](#8-workspace-information-architecture) 9. [The Granularity and Evidence Model](#9-the-granularity-and-evidence-model) 10. [Comprehensive Feature Set](#10-comprehensive-feature-set) 11. [The Emotion and Performance Atlas](#11-the-emotion-and-performance-atlas) 12. [Film-Specific Analysis](#12-film-specific-analysis) 13. [Game-Specific Analysis](#13-game-specific-analysis) 14. [Search, Comparison, Inspiration, and Synthesis](#14-search-comparison-inspiration-and-synthesis) 15. [Learning and Practice System](#15-learning-and-practice-system) 16. [Data and Knowledge Model](#16-data-and-knowledge-model) 17. [Proposed System Architecture](#17-proposed-system-architecture) 18. [Ingestion and Analysis Pipeline](#18-ingestion-and-analysis-pipeline) 19. [Contracts, APIs, and Events](#19-contracts-apis-and-events) 20. [Rights, Privacy, Safety, and Epistemic Integrity](#20-rights-privacy-safety-and-epistemic-integrity) 21. [Accessibility and Internationalization](#21-accessibility-and-internationalization) 22. [Non-Functional Requirements](#22-non-functional-requirements) 23. [Evaluation and Release Gates](#23-evaluation-and-release-gates) 24. [Delivery Roadmap](#24-delivery-roadmap) 25. [Second-Pass Gap Audit](#25-second-pass-gap-audit) 26. [Decisions Required Before Build](#26-decisions-required-before-build) 27. [Definition of Done](#27-definition-of-done) 28. [Prior Art and Competitive Positioning](#28-prior-art-and-competitive-positioning) 29. [Repository Evidence](#29-repository-evidence) --- ## 1. The Short Answer The repository has many of the necessary components, but it does **not** currently have one coherent, production-ready workspace that can ingest a movie or game reference, decompose it at every useful scale, compare examples across a corpus, connect pictures and ideas through typed relationships, organize project-specific inspiration, teach the underlying craft, and preserve the work as a reusable study notebook that can inform an original film, game, or world. This capability should not belong entirely to Yemaya, Hathor, or any other single domain. - **Yemaya should own the creator-facing product experience** because the purpose is to improve film and game creation, not merely archive media or analyze narrative. - **Nisaba should own the durable study model**: source-grounded comparison, annotation, commentary, notebooks, and research continuity. - **Sophia should own evidence, citations, provenance, retrieval, and confidence-bearing claims.** - **Hathor should own narrative, character, dramatic, game-design-theory, and directorial interpretation lenses.** - **Aja should own motion, pose, action, animation, and reference-video analysis.** - **Euterpe should own voice, music, sound, rhythm, and listening lenses.** - **Aglaea should own costume, garment, fabric, accessory, and fashion-history lenses.** - **Bellona and the game runtimes should own instrumented gameplay, engine traces, replay, state, and mechanic telemetry.** - **Metis should own curricula, exercises, assessment, mastery, and learning progression.** - **Isis should supply approved multimodal inference and generation capabilities without becoming the system of record.** The canonical experience should live in the unified Oshun Studio shell established by [ADR-0013](../adr/ADR-0013-oshun-studio-information-architecture.md), with a proposed route such as `/studio/study`. Yemaya provides the creator-facing composition; Nisaba and Sophia provide the research spine behind it. --- ## 2. Executive Summary ### 2.1 Product concept The Study & Deconstruction Workspace is a synchronized media laboratory, research notebook, and practice studio. A learner can bring an authorized source, navigate from the entire work down to an individual frame or gameplay event, apply one or more craft lenses, compare examples, record interpretations with evidence, connect exact images or regions to concepts across many works, and turn observations into exercises and traceable decisions for their own projects. The workspace must support questions such as: - How is this character communicated through silhouette, color, costume, gesture, dialogue, framing, and story function? - What precise camera, lens, blocking, lighting, edit, sound, and performance choices make this scene feel angry, intimate, unstable, grand, or restrained? - How does an animation move from anticipation through contact, overshoot, settle, and recovery? - How does a game teach a mechanic, shape player attention, tune risk and reward, and transition between systemic states? - What changes across several performances of anger, and which observations are visible facts versus interpretations? - Which images, scenes, mechanics, sounds, and historical references are linked by a shared function even when they do not look alike? - How can references from many unrelated works be organized into coherent rules for an original film, game, character system, or world without collapsing into a derivative mood board? - How can the learner reproduce a principle in an original exercise without copying protected expression? ### 2.2 Core product promise > Every interpretation can be traced to an exact source moment; every source > moment, image, or region can be connected through explicit, inspectable > relationships; every useful insight can become a deliberate practice exercise > or an original project decision. ### 2.3 What makes the workspace different It is not just a video player with comments, an AI summary tool, a mood board, a film database, a game telemetry dashboard, or a course platform. It joins six modes that are usually separated: 1. **Observe** — frame-accurate, source-bound inspection. 2. **Deconstruct** — multimodal craft analysis at multiple scales. 3. **Compare** — align examples by moment, beat, motion, emotion, or design function. 4. **Connect** — organize typed, evidence-backed relationships among works, frames, regions, entities, motifs, principles, and original project concepts. 5. **Learn** — turn findings into concepts, exercises, feedback, and mastery. 6. **Transfer** — send principles and references into an original Yemaya or game project with provenance and anti-copying safeguards. ### 2.4 Current maturity conclusion The codebase is rich in domain primitives but fragmented in product integration. The strongest existing pieces are: - Aja's reference-video entity model and annotation/search concepts. - Yemaya's performance, directorial, facial, vocal, timing, subtext, and comparative-take agents. - Hathor's narrative, MDA, cinematography, storyboarding, and character theory. - Nisaba's source-grounded study and notebook semantics. - Sophia's timestamp-anchored transcript ingestion and provenance-oriented retrieval. - Metis's assessment, adaptive learning, knowledge tracing, and mastery models. - Aglaea's fashion, fabric, garment, and accessory knowledge. - Bellona and game-specific replay, telemetry, and runtime systems. The largest missing piece is a governed shared product and data model that makes those capabilities behave as one honest end-to-end workflow. --- ## 3. Ownership Decision ### 3.1 Normative decision The product should be described as the **Yemaya Study & Deconstruction Workspace, powered by Nisaba and Sophia**, inside Oshun Studio. Yemaya is the experience owner because the primary outcome is improved creative judgment and production. Nisaba is the study substrate because the durable artifacts are source-grounded annotations, comparisons, commentary, and notebooks. Sophia is the evidence substrate because analysis must remain tied to sources, rights, provenance, and confidence. Hathor is a first-class contributor, but making Hathor the sole owner would overfit the workspace to narrative and game design. It would leave camera, motion, sound, costume, art direction, performance, learning, and evidence under-composed. ### 3.2 Domain responsibility matrix | Concern | Accountable owner | Contributing domains | Boundary | | ------------------------------------------------------------- | ---------------------------- | --------------------------- | --------------------------------------------------------------- | | Creator-facing workspace and project transfer | Yemaya | Oshun, Isis | Owns the composed experience, not every analysis model | | Inspiration canvas, original concept maps, creative decisions | Yemaya | Nisaba, Sophia, lens owners | Owns project composition; source evidence remains domain-backed | | Study projects, notebooks, comparative research, typed links | Nisaba | Sophia, Metis, Yemaya | Owns durable study semantics, not media production | | Evidence anchors, retrieval, citations, provenance | Sophia | Nisaba, Isis | Owns traceability and grounded claims | | Narrative, character, dramatic structure, directing, MDA | Hathor | Yemaya, Bellona | Provides lenses; does not own the whole workspace | | Motion, pose, action, animation reference | Aja | Hathor, Bellona | Owns motion analysis and reference-video primitives | | Voice, dialogue sound, score, rhythm, sound design | Euterpe | Yemaya, Hathor | Owns auditory analysis | | Costume, fabric, accessory, fashion history | Aglaea | Yemaya, Hathor | Owns garment and styling semantics | | Gameplay state, input, replay, engine, mechanics telemetry | Bellona and product runtimes | Hathor, Aja | Owns trustworthy instrumented runtime data | | Curriculum, practice, feedback, assessment, mastery | Metis | Yemaya, Nisaba | Owns learning progression, not source interpretation | | Multimodal inference and approved generation | Isis | All lens owners | Supplies models; never becomes the canonical evidence store | | Identity, permissions, shell navigation, Library continuity | Oshun | Yemaya, Nisaba | Owns shared platform behavior | | Accessibility policy and assistive adaptations | Iris | Oshun, Metis | Cross-cuts every learner-facing surface | ### 3.3 Product and route placement The preferred placement is: - **Entry:** Oshun Studio global navigation, `Study`. - **Canonical route:** `/studio/study`. - **Domain context:** Yemaya-branded creator mode with explicit Nisaba notebook and Sophia evidence rails. - **Durable saves:** shared Library collections, Nisaba study projects, and project-specific inspiration collections. - **Project handoff:** Yemaya production projects or instrumented game projects. This follows the unified Studio direction rather than creating another isolated application. Existing standalone Yemaya and Aja applications can remain specialist or internal surfaces during migration. --- ## 4. Product Thesis, Goals, and Boundaries ### 4.1 Goals 1. Make film and game craft inspectable from whole-work scale to frame, object, performance signal, or runtime event. 2. Keep every observation and interpretation attached to precise evidence. 3. Let learners compare many examples across media, genres, cultures, eras, and performance styles. 4. Connect works, moments, images, regions, entities, motifs, and concepts with typed, explainable, versioned relationships. 5. Organize broad inspiration into original movie, game, character, environment, and world-system decisions without copying source-specific expression. 6. Separate observable facts, model detections, human interpretations, and craft hypotheses. 7. Convert study into deliberate practice and original creative decisions. 8. Reuse domain capabilities without copying their data models into Yemaya. 9. Respect copyright, license terms, privacy, consent, and performer dignity. 10. Work well for manual study before advanced automation is available. 11. Support film-only, video-only game analysis, and deeper instrumented game analysis. 12. Produce exportable, durable, versioned research artifacts. ### 4.2 Non-goals The workspace is not: - a tool for bypassing DRM, downloading restricted streams, or ripping game assets; - a system that declares one objectively "true" emotional performance; - a biometric identity or face-recognition product; - an automatic plagiarism or style-cloning pipeline; - an automatic mood-board generator that hides why a reference was selected or presents similarity as creative truth; - a replacement for film, acting, animation, sound, fashion, or game-design teachers; - a universal factual authority on authorial intent or cultural meaning; - a requirement that every source be uploaded or permanently copied; - a production editor, full DCC, or game engine in the first release; - a promise that all existing analysis classes are connected to real media processing today. ### 4.3 Product principles - **Evidence before interpretation.** A conclusion without an anchor is a note, not a grounded analysis. - **Observe, infer, hypothesize.** The UI must visibly distinguish those epistemic levels. - **Human disagreement is data.** Multiple interpretations can coexist and show reviewer context. - **Context matters.** Emotion, gesture, clothing, camera, and mechanics cannot be read reliably without story, culture, genre, and production context. - **Manual work is first-class.** Automation accelerates annotation; it does not make the product useful by itself. - **Transform, do not imitate.** Project transfer carries principles and constraints, not extractable protected expression. - **Every connection explains itself.** A relationship states its type, endpoints, author or model, evidence, confidence, direction, and limitations. - **Many references, one accountable decision.** Original project choices may synthesize multiple sources, but retain a reviewable path through principles to the exact evidence that informed them. - **One source of truth per domain.** The workspace composes domain outputs through contracts instead of duplicating engines. - **Progressive depth.** A learner can begin with a simple question and reveal expert-level detail only when needed. --- ## 5. What Exists Today ### 5.1 Status legend | Status | Meaning | | --------------------- | ----------------------------------------------------------------------------------------------------------------- | | Implemented primitive | Working code or an established shared contract that can be reused | | Partial | Useful types or logic exist, but persistence, media execution, integration, or production hardening is incomplete | | Fixture-backed | The UI or analysis path demonstrates behavior using static or simulated data | | Planned | Described in documentation, but not represented as a dependable end-to-end implementation | | Missing | No coherent repository capability was found for this product requirement | ### 5.2 Current capability assessment | Capability | Status | Repository evidence | Assessment | | --------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | | Unified Studio shell and domain composition | Implemented primitive | [Studio IA ADR](../adr/ADR-0013-oshun-studio-information-architecture.md), [`apps/oshun/web`](../../apps/oshun/web) | Correct canonical host for a composed workspace | | Source-grounded study and notebook continuity | Implemented primitive / partial | [Nisaba first-class ADR](../adr/ADR-0054-oshun-nisaba-first-class-customer-domain.md), [research-to-practice ADR](../adr/ADR-0059-oshun-research-to-practice-journey-model.md), [`libs/nisaba`](../../libs/nisaba) | Strong ownership semantics; not yet a multimodal creator deconstruction product | | Reference-video entities, clips, segments, annotations, workspaces, reviews, search, and embeddings | Partial | [`apps/aja/svc-reference-video/src/types.ts`](../../apps/aja/svc-reference-video/src/types.ts) | Broad model foundation; persistence and production integration need validation | | Reference-video ingestion and scene detection | Fixture-backed / partial | [`scene-detection.ts`](../../apps/aja/svc-reference-video/src/scene-detection.ts), [`metadata-extraction.ts`](../../apps/aja/svc-reference-video/src/metadata-extraction.ts) | Several paths explicitly simulate frame statistics, external imports, or metadata | | Performance reference library | Partial | [`performance-reference-library.ts`](../../libs/yemaya/agents/src/creative/performance-reference-library.ts) | Good performance dimensions and basic rights enum; in-memory storage and insufficient rights semantics | | Facial, vocal, timing, chemistry, intention, subtext, emotional, and take-comparison analysis | Partial | [`libs/yemaya/agents/src/creative`](../../libs/yemaya/agents/src/creative) | Rich analysis vocabulary; many analyzers expect pre-extracted features rather than owning reliable extraction | | Director performance replay Studio surface | Fixture-backed | [`StudioHathorDirectorPerformanceReplaySystemPanel.tsx`](../../apps/oshun/web/src/components/studio/StudioHathorDirectorPerformanceReplaySystemPanel.tsx) | Useful interaction concepts but currently driven by fixtures and readiness scores | | Narrative, MDA, story, character, shot, composition, lighting, rhythm, and continuity theory | Implemented primitive / partial | [Hathor features](../domains/hathor/deep-dive/features.md), [`libs/hathor`](../../libs/hathor) | Strong semantic lenses; no single source-bound deconstruction workflow | | Timestamp-grounded video transcript ingestion | Implemented primitive | [`video-transcript.ts`](../../libs/sophia/ingestion/src/adapters/video-transcript.ts) | Good evidence anchor pattern; covers transcripts, not full visual and audio craft analysis | | Fashion, fabric, garment, accessory, and style knowledge | Implemented primitive / partial | [`libs/aglaea`](../../libs/aglaea), [Aglaea domain documentation](../domains/aglaea/deep-dive/features.md) | Valuable costume lens; needs media-region grounding and cross-domain character context | | Adaptive assessment and mastery | Implemented primitive | [Metis documentation](../domains/metis/README.md), [`knowledge-tracker.ts`](../../libs/metis/adaptive/src/profiling/knowledge-tracker.ts) | Strong basis for practice progression; no film/game craft curriculum mapping yet | | Gameplay replay and player-behavior telemetry | Product-specific primitives | [`libs/aphrodite/game-runtime/src/replay`](../../libs/aphrodite/game-runtime/src/replay), [`apps/v2/player-behavior-heatmaps`](../../apps/v2/player-behavior-heatmaps), [V2 telemetry docs](../../V2/docs/telemetry/README.md) | Reusable ideas exist, but there is no cross-game study contract | | Animation learning surface | Fixture-backed / planned | [`AnimationLearningPage.tsx`](../../apps/yemaya/studio-web/src/pages/AnimationLearningPage.tsx) | Hard-coded learning material, not source-derived study | | Dailies review | Fixture-backed / partial | [`DailiesReviewPage.tsx`](../../apps/yemaya/studio-web/src/pages/DailiesReviewPage.tsx) | Demonstrates review interaction; does not provide corpus-scale study | | Full rights resolver for media analysis | Missing | Existing performance reference uses a four-value enum | Must become a first-class policy service and auditable grant model | | Shared film/game deconstruction ontology | Missing | Domain-specific types exist separately | Required to align evidence across lenses without flattening domain expertise | | Project-specific inspiration graph and source-to-decision trail | Missing | Comparison, notebook, and project-transfer primitives exist separately | Needs typed cross-references, visual graph/canvas views, and original-concept entities | | End-to-end multimodal analysis orchestration | Missing | Individual agents and services exist | Needs durable jobs, model/version records, retries, and human review | | Cross-source emotion/performance atlas | Missing | Performance primitives exist | Central user request remains uncomposed | | Instrumented commercial-game analysis | Missing by design | Product runtimes only | Must be limited to authorized or owned builds; video-only mode covers external games | ### 5.3 Key conclusion The repository is closer to a toolkit than a product. It contains enough primitives to build a credible first release without inventing every domain engine, but it needs shared contracts, persistence, rights policy, real media pipelines, evaluation data, and one carefully designed user journey. --- ## 6. Primary Users and Jobs ### 6.1 Learner filmmaker Needs to understand how camera, staging, acting, editing, production design, sound, and narrative work together. Starts with questions rather than formal taxonomies and needs definitions, guided lenses, and exercises. ### 6.2 Learner game developer Needs to study mechanics, feedback, level flow, combat readability, camera behavior, animation, UI, audio, economy, narrative, and player decision-making. May have only captured footage for external titles but deep runtime data for their own builds. Needs to connect reference mechanics, encounters, levels, animation, UI, sound, and world rules to original design decisions without pretending that visually similar games have identical systems. ### 6.3 Actor, animator, or director Needs to compare performances and movement at beat level; inspect face, voice, breath, posture, gaze, gesture, blocking, timing, and camera relationship; rehearse alternatives; and review attempts. ### 6.4 Character, costume, and concept artist Needs high-resolution regions, silhouettes, material and garment terminology, accessory function, wear states, color relationships, historical/cultural context, links between design and story, and a way to synthesize many sources into an original character or world system with a traceable decision history. ### 6.5 Teacher, mentor, or team lead Needs to create source-safe study sets, assign guided analyses, review evidence, comment on interpretations, publish rubrics, and monitor growth without turning taste into a fake objective score. ### 6.6 Researcher or critic Needs a citable corpus, explicit interpretive claims, source lineage, comparison tables, disagreement handling, export, and reproducibility across analysis versions. --- ## 7. Core User Journeys ### 7.1 Bring in a source 1. Create or open a study project. 2. Add a local file, creator-owned asset, authorized game capture, provider deep link, public-domain source, or licensed source. 3. Declare or resolve rights, territory, expiry, allowed derivatives, collaborators, and retention policy. 4. Normalize technical metadata and create a stable source identity. 5. Generate only the derivatives permitted by the rights policy. 6. Present processing status and make manual annotation available immediately. **Output:** A source record with an inspectable rights decision, media tracks, provenance, and processing status. ### 7.2 Deconstruct a scene 1. Open a scene or encounter in the synchronized player. 2. Choose lenses such as performance, camera, narrative, animation, sound, costume, or mechanics. 3. Inspect proposed segments and correct them. 4. Add observations at scene, shot, beat, frame, region, character, or signal scope. 5. Promote selected observations into interpretations or craft hypotheses. 6. Save a study card with evidence anchors and questions. **Output:** A source-grounded deconstruction page, not an untraceable summary. ### 7.3 Build an anger atlas 1. Search for examples labeled or inferred as anger-related. 2. Filter by context, intensity, regulation, relationship, genre, culture, medium, and performance channel. 3. Review clips in a synchronized comparison grid. 4. Separate visible/audible observations from emotional interpretation. 5. Record agreement, disagreement, counterexamples, and missing context. 6. Build an exercise such as "restrained anger without raised volume." **Output:** A comparative atlas whose claims remain contextual and contestable. ### 7.4 Study a character design 1. Select a character across scenes, states, costumes, or game skins. 2. Compare silhouettes, palettes, facial design, materials, garments, accessories, wear, motion, pose, framing, and story role. 3. Inspect region-level crops linked back to exact frames. 4. Add Aglaea terminology and historical/cultural references with provenance. 5. Extract reusable design principles rather than copying the design. **Output:** A character system map and an original design brief. ### 7.5 Study a game system 1. Add video footage or connect an authorized instrumented build. 2. Mark tutorial, encounter, mechanic, feedback, failure, recovery, and reward moments. 3. In instrumented mode, align frames with input, state, AI, camera, animation, damage, economy, and performance events. 4. Compare player intention with system response. 5. Create a mechanic hypothesis and prototype test. **Output:** An evidence-backed mechanic analysis and an experiment for the learner's project. ### 7.6 Practice and review 1. Convert findings into a bounded exercise with a rubric. 2. Upload or connect an original attempt. 3. Compare the attempt with principles and selected references, never with a mandate to duplicate them. 4. Receive evidence-linked automated suggestions and human feedback. 5. Reflect, revise, and update mastery. **Output:** A versioned practice portfolio showing growth and decisions. ### 7.7 Build an original-project inspiration system 1. Start with an original-project question such as a world rule, character contrast, location identity, emotional arc, mechanic, or audience effect. 2. Pull permitted works, moments, stills, regions, sounds, documents, mechanics, and creator-owned assets into a project-specific inspiration collection. 3. Record what is relevant in each item, what should not be copied, and whether it supports, contrasts with, or complicates another reference. 4. Connect sources to reusable principles and then to original characters, factions, locations, cultures, histories, scenes, quests, mechanics, art rules, sound rules, and other project concepts. 5. Inspect coverage, contradictions, repeated dependence on one source, missing perspectives, and relationships suggested by the system but not yet reviewed. 6. Commit selected principles as versioned creative decisions with owners, rationale, alternatives, and source backlinks. **Output:** An evidence-backed inspiration graph and original project concept system, not an untraceable collage or style-copying prompt. ### 7.8 Transfer into production 1. Select insights, palettes, motion principles, shot logic, narrative functions, or mechanic hypotheses. 2. Review the source and rights trail. 3. Convert them into abstract constraints, questions, or tasks. 4. Send them to a Yemaya project, game backlog, storyboard, shot list, character brief, animation task, or test plan. 5. Preserve a backlink to the study record. **Output:** Original production work informed by study, with provenance and anti-copying guardrails. --- ## 8. Workspace Information Architecture ### 8.1 Top-level navigation | Area | Purpose | | ----------- | ----------------------------------------------------------------------------------------------------- | | Home | Resume studies, processing jobs, assignments, and recent findings | | Sources | Rights-aware media and game-session library | | Workbench | Synchronized player and multi-lens deconstruction | | Atlas | Cross-source collections such as anger, entrances, reveals, hit reactions, or costume transformations | | Compare | Side-by-side and synchronized comparison sets | | Inspiration | Project-specific image canvas, typed reference graph, comparison matrix, and source-to-decision trail | | Notebooks | Nisaba-backed research narratives and study cards | | Practice | Exercises, attempts, rubrics, feedback, and mastery | | Projects | Transfer findings into active Yemaya or game projects | | Reports | Exported analyses, teaching packs, and audit trails | ### 8.2 Workbench layout ```text ┌──────────────────────────────────────────────────────────────────────────────┐ │ Study project / source / version Search Rights Share Export │ ├──────────────────┬───────────────────────────────────┬───────────────────────┤ │ Source navigator │ Synchronized media canvas │ Lens inspector │ │ Work │ - video / image / game replay │ Observe │ │ Sequence │ - overlays / regions / skeleton │ Interpret │ │ Scene │ - A/B / onion skin / split view │ Hypothesize │ │ Shot │ │ Evidence + confidence │ │ Beat │ │ Terms + context │ ├──────────────────┴───────────────────────────────────┴───────────────────────┤ │ Multitrack timeline: shots · beats · dialogue · performance · camera · │ │ motion · sound · music · costume · mechanics · runtime events · annotations │ ├──────────────────────────────────────────────────────────────────────────────┤ │ Notebook / compare tray / inspiration canvas + graph / project handoff │ └──────────────────────────────────────────────────────────────────────────────┘ ``` ### 8.3 Interaction requirements - Frame-accurate step, shuttle, loop, variable speed, reverse, and keyboard control. - Persistent selected entity, track, range, lens set, zoom, and comparison state. - Click any analysis to reveal its exact anchors, run version, model, confidence, reviewer, and source rights. - Pin any moment into the comparison tray without leaving the workbench. - Pin a whole work, moment, frame, image, region, sound interval, runtime event, or creator-owned asset into an inspiration collection without losing its source identity and rights state. - Keep the selected reference synchronized across the evidence canvas, cross-work matrix, relationship graph, notebook, and original project map. - Let users create, accept, reject, contest, and annotate typed cross-references without automatically merging entities that merely look or sound similar. - Toggle overlays independently so the screen does not become an unreadable diagnostic wall. - Keep source imagery or media as the dominant working surface; navigation and relationship detail remain secondary and appear progressively instead of as a mosaic of competing cards. - Use restrained shared-selection transitions when moving a frame or region between the source canvas, comparison, and inspiration views; expand graph neighborhoods only on request; and use a brief cross-view highlight to reveal the active evidence path. All three behaviors honor reduced-motion settings. - Preserve a clean "watch" mode for experiencing the work without analysis. - Support a spoiler-safe first-viewing state that hides annotations, beat labels, community claims, and structural navigation beyond the current playhead, and records naive observations with an explicit first-viewing context (Section 15.6). - Provide beginner explanations and expert parameters through progressive disclosure. - Allow a no-AI manual mode and show what analysis is unavailable rather than fabricating results. --- ## 9. The Granularity and Evidence Model ### 9.1 Common hierarchy The system must not force every medium into a single timeline vocabulary, but it needs shared anchor semantics. ```text Study project └── Source work └── Edition / cut / build / version └── Presentation or session └── Sequence / chapter / level └── Scene / encounter └── Shot / take / gameplay phase └── Beat / action / state transition └── Frame / audio interval / runtime event └── Region / entity / joint / sound stem / property └── Observation / detection / claim / hypothesis ``` ### 9.2 Film and linear media anchors - Edition, cut, language track, and frame-rate identity. - Reel, act, chapter, sequence, scene, shot, take, beat, line, word, frame, and region. - Timecode with rational frame rate and drop-frame awareness. - Transcript, speaker, subtitle, audio stem, music cue, and sound event intervals. - Character, performer, garment, prop, location, and camera entities. ### 9.3 Game anchors - Title, platform, region, patch, build, settings, mods, and capture configuration. - Session, save state, level, checkpoint, encounter, round, phase, input window, action, state transition, frame, and telemetry event. - Player, character, NPC, camera, object, ability, animation state, quest, economy transaction, UI state, and audio event. - Deterministic replay identity where available; video time plus synchronization error otherwise. ### 9.4 Non-temporal and spatial anchors - Script, screenplay, design document, comic, art book, or storyboard: document, edition, page, panel, block, line, word, and rectangular or polygonal region. - Still image or concept art: image revision, canvas, layer where available, pixel or normalized region, detected entity, palette region, and user-defined guide. - Creator-owned 3D asset: asset revision, scene, node, mesh, primitive, vertex/face set, UV island, material slot, texture region, bone, socket, morph target, animation clip, and time sample. - Creator-owned level or scene: world/level revision, sublevel, actor/entity, component, volume, spline, camera, light, material, and gameplay reference. - Cross-view identity links must preserve uncertainty; the system must not assume two depicted figures or assets are the same entity solely because they look similar. ### 9.5 Evidence object Every evidence-bearing object should support: | Field | Requirement | | --------------- | ----------------------------------------------------------------------------------- | | Source identity | Stable work, edition/build, and asset/session identifiers | | Locator | Time range, frames, region, event range, transcript span, entity, or combination | | Snapshot | Permitted thumbnail, waveform, feature vector, or provider deep link | | Provenance | Acquisition method, source revision, processor, model and configuration | | Rights | Grant/policy decision controlling display, derivation, sharing, and export | | Confidence | Calibrated confidence for machine detections; never a substitute for interpretation | | Author | Human, model, imported system, or collaborative group | | Review state | Suggested, accepted, corrected, contested, rejected, or superseded | | Version | Immutable history with reason for change | ### 9.6 Epistemic object types The workspace must visibly distinguish: 1. **Source fact** — metadata or a directly verifiable source property. 2. **Detection** — a model- or algorithm-produced signal such as a cut, pose, pitch contour, or object region. 3. **Observation** — a human description of what is visible or audible. 4. **Interpretation** — a contextual reading such as "the pause may communicate controlled anger." 5. **Craft hypothesis** — a causal or reusable proposition such as "withholding the cut preserves pressure." 6. **Creator statement** — documented intent from a source, kept separate from textual analysis. 7. **Practice result** — evidence from the learner's own exercise or project. The UI must not silently promote a detection into an interpretation or an interpretation into authorial intent. ### 9.7 Cross-edition and cross-build anchor mapping Editions must never be silently merged, but they should not be isolated islands either. When a study project contains more than one edition, cut, build, or patch of the same work, the system may compute or accept an **edition alignment map**: a reviewable set of correspondences stating that an anchor range in one edition corresponds, exactly or approximately, to a range in another. - Alignment maps may be proposed by matching signals such as audio fingerprints, shot structure, transcript alignment, or telemetry landmarks, or authored manually; every correspondence carries its method, confidence, and review state. - An accepted map lets annotations, claims, and comparison items **propose** a counterpart location in another edition. A migrated anchor remains a suggestion until a person confirms it, and it records both the source and target edition versions. - Material removed, added, reordered, re-scored, or re-graded between editions surfaces as an explicit gap rather than being interpolated across. - For games, alignment maps connect builds and patches so mechanic annotations survive an update through review instead of dying with the build they were made on. This matters most for live-service titles whose "current version" is a moving target. --- ## 10. Comprehensive Feature Set ### 10.1 Source acquisition and governance | Feature | Essential behavior | Primary owner | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | | File and capture ingest | Resumable upload, checksum, malware scan, metadata, transcode policy | Yemaya / Aja / platform | | Provider deep links | Study against authorized playback without copying restricted media | Sophia / platform | | Game capture import | Video, audio, controller overlay, capture settings, patch/build metadata | Bellona / Yemaya | | Instrumented build connector | Signed session manifest, telemetry clock, replay/state data | Bellona | | Rights resolver | License/grant, allowed actions, territory, expiry, retention, collaborators | Sophia / legal platform | | Source lineage | Work, edition, cut/build, derivative, transcript, and analysis versions | Sophia / Nisaba | | Processing controls | Per-lens opt-in, cost estimate, quality tier, cancellation, retry | Isis / platform | | Deletion and expiry | Cascading derived-asset deletion and expiring-access enforcement | Platform / Sophia | | Paratext ingest | Commentary tracks, interviews, making-ofs, talks, art books, patch notes, and developer diaries linked or time-aligned to the works they discuss | Sophia / Yemaya | | Reference-board and library import | Migrate PureRef, Milanote, Are.na, Pinterest, and Zotero collections as quarantined user-declared sources with per-item rights review | Yemaya / Sophia | | Clipper and capture hotkeys | Browser clipper and screenshot/region hotkeys that create evidence-anchored, rights-classified inspiration items without leaving the current tool | Yemaya / platform | ### 10.2 Playback, navigation, and annotation | Feature | Essential behavior | Primary owner | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------ | | Professional playback | Frame stepping, loop, shuttle, speed, reverse, A/B, safe audio | Yemaya | | Hierarchical navigator | Work to frame/event tree with user correction | Yemaya / Nisaba | | Multitrack timeline | Toggleable analysis, media, runtime, and annotation tracks | Yemaya | | Region and entity annotation | Boxes, polygons, masks, skeletons, points, tracks, links | Aja | | Temporal annotation | Instant, range, beat, recurring motif, linked moments | Nisaba / Aja | | Layered notes | Observation, interpretation, hypothesis, question, correction | Nisaba | | Versioned collaboration | Comments, mentions, assignments, review, approval, conflict history | Oshun / Nisaba | | Live co-study sessions | Synchronized group playback, presence, anchored live discussion, and crystallization of discussion into reviewed claims | Oshun / Nisaba | | Annotation templates | Lens-specific prompts and rubrics | Metis / lens owner | ### 10.3 Character and visual design lens - Character identity and role across scenes, versions, states, and disguises. - Silhouette, shape language, proportion, scale, line, mass, negative space, and asymmetry. - Face, hair, makeup, scars, body marks, age signals, and expression range. - Palette extraction, color script context, contrast, saturation, value grouping, and palette evolution. - Material, surface, texture, wear, damage, repair, cleanliness, and environmental storytelling. - Costume layering, construction, fit, drape, fabric, fastening, footwear, jewelry, weapon carry, and accessories. - Historical, occupational, cultural, status, faction, and ritual context with sourced terminology. - Prop relationships, repeated motifs, symbolic readings, and story-function hypotheses. - Character turnaround assembled only from permitted frames, with uncertainty when views do not exist. - Cross-scene continuity and transformation tracking. ### 10.4 Cinematography and camera lens - Shot boundary, scale, angle, height, roll, orientation, movement, and stabilization. - Estimated focal length class and field of view with explicit uncertainty unless camera metadata is available. - Perspective, compression, depth cues, depth of field, focus target, rack focus, and lens artifacts. - Composition: balance, leading lines, headroom, look room, symmetry, layers, occlusion, frame-within-frame, and subject hierarchy. - Blocking relative to camera, eyelines, screen direction, entrances, exits, and power geometry. - Movement path, speed, acceleration, motivation, reveal structure, parallax, and subjective/objective camera stance. - Exposure, contrast, key/fill/rim relationships, color temperature, practicals, shadow design, and lighting transitions. - Camera-to-performance relationship, including when framing suppresses or amplifies gesture. - Virtual camera and gameplay camera state when instrumented data is available. ### 10.5 Performance and acting lens - Scene objective, obstacle, tactic, stakes, given circumstances, relationship, status, and beat changes. - Facial action observations, gaze, blink, jaw, mouth, tension, release, and asymmetry. - Posture, weight, grounding, gesture, self-contact, reach, retreat, stillness, and use of space. - Vocal pitch, range, contour, volume, pace, rhythm, pause, breath, articulation, resonance, and overlap. - Dialogue phrasing, emphasis, interruption, listening, reaction, subtext, and silence. - Blocking precision, camera awareness, ensemble chemistry, and physical continuity. - Onset, build, peak, suppression, leakage, recovery, and transition of an interpreted affect. - Comparative takes and alternate readings without reducing quality to one opaque score. - Actor-safe notes: behavior-specific, playable, contextual, and free of identity or mental-health diagnosis. ### 10.6 Animation and motion lens - Pose, silhouette, center of mass, balance, support, weight shift, line of action, and joint trajectories. - Timing, spacing, arcs, anticipation, follow-through, overlap, drag, overshoot, settle, holds, and moving holds. - Contact, impact, recoil, recovery, locomotion phase, foot plant, root motion, and slip detection. - Facial animation, lip synchronization, eye darts, blinks, micro-movement, and dialogue timing. - Stylization profile, exaggeration, pose economy, limited/full animation characteristics, and cadence. - Motion trails, onion skin, pose overlays, synchronized skeleton comparison, and time warping. - Game animation state, blend transitions, montage/ability alignment, responsiveness, cancel windows, and animation locks when telemetry exists. - Accessibility-safe visualization that does not depend on color alone or excessive motion. ### 10.7 Narrative and character-function lens - Fabula versus syuzhet, act/sequence/scene structure, causality, revelation, setup/payoff, and dramatic irony. - Character want, need, belief, wound, tactic, decision, reversal, relationship, arc, and story function. - Scene question, value shift, conflict, stakes, beats, turning point, climax, resolution, and unresolved pressure. - Dialogue function, exposition load, subtext, motif, theme, symbol, genre convention, and tonal shift. - Pacing measured through duration, information rate, event density, shot rhythm, performance rhythm, and game agency. - Branching narrative, quest state, systemic story, player-authored sequence, and counterfactual paths. - Interpretation disagreement and cultural/historical context, with sources and epistemic labels. ### 10.8 Editing and temporal construction lens - Cut type, transition, duration, rhythm, continuity, discontinuity, match, ellipsis, montage, and temporal compression. - Picture-sound relationship, J/L cuts, reaction timing, held shots, insert function, and point-of-view construction. - Coverage map, master/close-up relationship, take usage, continuity deviations, and editorial emphasis. - Shot-duration distributions and sequence rhythm, always paired with qualitative context. - Alternative assembly sandbox using user-owned or permitted clips only. ### 10.9 Sound, voice, and music lens - Dialogue, production sound, ADR, ambience, effects, foley, score, silence, and mix hierarchy. - Loudness, dynamic range, spectral balance, spatial placement, reverberation, masking, and transitions. - Sound motif, leitmotif, instrumentation, harmony, rhythm, tempo, meter, texture, and thematic transformation. - Diegetic, non-diegetic, internal, acousmatic, subjective, and point-of-audition classifications. - Voice-performance features aligned with transcript and facial/body behavior. - Game audio triggers, priority, repetition, variation, state transitions, feedback timing, and mix under load. - Source separation only where rights and model reliability permit; inferred stems must be labeled. ### 10.10 Art direction, environment, prop, VFX, and UI lens - Environment layout, architecture, geography, scale, landmarks, affordances, navigation, and visual hierarchy. - Production design motifs, decoration, clutter, wear, class/status signals, world rules, and historical context. - Prop identity, function, interaction, continuity, symbolic interpretation, and material response. - VFX layer, particle behavior, compositing, integration, simulation character, readability, and timing. - Film titles and game UI: typography, information hierarchy, motion, feedback, diegesis, accessibility, and state. - Spatial progression and environmental storytelling comparisons across a sequence or level. ### 10.11 Game design and systems lens - Core loop, verbs, goals, rules, resources, constraints, feedback, risk, reward, failure, recovery, and progression. - MDA mapping: mechanics, dynamics, and aesthetics with evidence from play rather than design-document assumption. - Control mapping, input buffering, response latency, aim/movement behavior, camera coupling, and accessibility settings. - Combat readability, anticipation, telegraphing, hit confirmation, stun/recovery, spacing, tempo, and decision windows. - AI perception, state, tactic, coordination, difficulty behavior, and player counterplay where instrumented. - Level flow, gating, critical path, optional path, encounter rhythm, checkpoints, landmarks, and spatial teaching. - Tutorialization, affordances, signifiers, onboarding, hint timing, failure messaging, and mastery curve. - Economy sources/sinks, prices, scarcity, reward schedules, inventory pressure, and progression pacing. - Social, multiplayer, live-service, fairness, retention, and community systems without manipulative-pattern endorsement. - Performance data: frame time, latency, load, streaming, network conditions, and their effect on perceived design. ### 10.12 Still-image, document, storyboard, and creator-owned 3D asset study - High-resolution tiled image viewing, deep zoom, pan, rotation, region annotation, palette inspection, and cross-image alignment. - Script and screenplay parsing for scene headings, action, dialogue, characters, transitions, page timing, motifs, relationships, and revision comparison. - Script-to-storyboard-to-shot-to-final alignment with missing, combined, reordered, or transformed material made explicit. - Storyboard panel analysis for composition, staging, lens intent, continuity, movement arrows, annotations, and editorial rhythm. - Character sheets and turnarounds with view, expression, costume, accessory, material, proportion, and construction comparisons. - Creator-owned 3D model inspection for topology, silhouette by view, scale, pivots, UVs, materials, textures, rig, skin weights, morphs, sockets, LODs, collision, and animation clips. - Material and shader study for graph structure, texture channels, value ranges, physical parameters, layer/blend logic, and rendering context. - Scene and level inspection for hierarchy, spatial relationships, lights, cameras, volumes, affordances, optimization, and version history. - Non-destructive measurements, guides, section planes, exploded views, wireframe, normals, UV, weight, skeleton, and material-channel overlays. - Project-aware links back to DCC or engine objects only for creator-owned or explicitly authorized assets; published works remain frame- and evidence-based. ### 10.13 Comparison, notebook, and output features - Synchronized two-to-eight-up playback by start, event, beat, pose, line, or normalized duration. - Difference overlays for pose, motion, palette, framing, loudness, timing, and runtime state. - Contact sheets, strip views, beat boards, shot maps, relationship maps, state graphs, and motif timelines. - Comparison sets with a declared question, inclusion criteria, exclusions, and counterexamples. - Claim cards containing evidence, interpretation, confidence, reviewer context, and dissent. - Notebook narratives that combine sources, annotations, tables, diagrams, and practice results. - Exports to Markdown, PDF, presentation, JSON, CSV, image contact sheet, edit markers, and supported production formats, subject to rights. - Deep links that restore source, time, selected lens, layout, and permissions. ### 10.14 Inspiration, cross-reference, and original-concept features - Project-framed inspiration collections with a declared creative question, target project or concept, intended audience effect, scope, exclusions, and collaborators. - Evidence-backed inspiration items that may target an entire work or an exact scene, frame, image, region, object, pose, palette, sound interval, transcript span, runtime event, document passage, or creator-owned asset component. - A dominant visual canvas, contact sheet, corpus matrix, relationship graph, timeline, and notebook outline as coordinated views over the same objects; spatial canvas position is presentation state, not evidence of a relationship. - Typed, directed cross-references for identity, similarity, contrast, influence, analogy, shared function, transformation, sequence, evolution, support, contradiction, counterexample, avoidance, derived principle, and informed creative decision. - Multi-level linking so one image can participate as a whole while independent regions connect to different characters, materials, motifs, palettes, locations, craft principles, and original project concepts. - Cross-media analogy mapping, such as relating a cinematic reveal to a game encounter reveal by function without claiming that their media mechanics are identical. - Human-authored links and reviewable machine suggestions with rationale, confidence, provenance, rights state, and accept, reject, correct, contest, merge, or keep-distinct actions. - Original concept graphs for films, games, characters, factions, locations, cultures, ecologies, histories, technologies, economies, quests, mechanics, art direction, sound rules, and narrative systems. - Coverage, contradiction, missing-perspective, source-concentration, and over-specificity checks before a principle becomes a project decision. - Versioned creative decisions with owner, status, rationale, alternatives, constraints, rejected directions, source-to-principle paths, and backlinks to resulting briefs, scenes, assets, tasks, or prototypes. - Rights-aware exports that preserve structured principles, links, citations, and permitted thumbnails while excluding prohibited source expression. ### 10.15 Paratext, commentary, and creator-statement study Creator statements deserve the same evidence discipline as the works themselves, and they are the richest untapped source for the `Creator statement` epistemic type. - Ingest and align director, actor, editor, or composer commentary tracks as synchronized tracks over the exact edition they describe, so a statement can be cited against the precise moment it discusses. - Link interviews, making-of documentaries, conference talks such as GDC sessions, art books, patch notes, and developer diaries to works, scenes, mechanics, or entities as creator-statement evidence with normal provenance, citation, and rights handling. - Keep creator statements epistemically separate: a documented intent never silently overrides an observation or settles an interpretation. The UI shows statement and analysis side by side, including when they conflict. - Support contradiction between paratexts: when two creator statements disagree, or a statement conflicts with observable evidence, both remain visible with review context rather than one being suppressed. - Paratext sources follow the same rights model as primary sources; a quoted interview passage carries attribution, license state, and permitted-use limits. --- ## 11. The Emotion and Performance Atlas ### 11.1 The correct framing The product should never promise a database of what "true anger" looks like. Anger is not one universal visual template. It can be expressed, suppressed, performed, redirected, mixed with fear or grief, shaped by relationship and status, stylized by genre, and interpreted differently across people and cultures. The useful product is an **evidence-grounded atlas of anger-related performances and contexts**. It helps learners notice patterns and variations without converting them into deterministic mind-reading. ### 11.2 Atlas facets | Facet group | Example values | | --------------------------- | --------------------------------------------------------------------------------------------------- | | Context | betrayal, injustice, humiliation, obstruction, grief, threat, protective response, status challenge | | Function | instrumental, expressive, defensive, coercive, boundary-setting, displaced, performative | | Regulation | unfiltered, escalating, restrained, masked, leaked, redirected, recovering | | Intensity and time | simmer, onset, build, eruption, plateau, collapse, aftermath | | Relationship | intimate, familial, peer, subordinate/superior, stranger, crowd, self-directed | | Channel | face, gaze, voice, breath, posture, gesture, movement, language, silence, spacing | | Performance style | naturalistic, theatrical, melodramatic, comedic, stylized animation, mocap, game loop | | Camera and edit | unbroken close-up, withheld reaction, handheld pursuit, wide tableau, rapid montage | | Sound context | silence, score pressure, distorted subjective sound, dense effects, vocal isolation | | Cultural/production context | place, era, language, acting tradition, genre convention, production constraints | Facets may be human-applied, model-suggested, or imported. The source of each facet must be visible. ### 11.3 Evidence channels For each selected interval, the atlas can align: - visible facial and gaze observations; - body, gesture, posture, distance, and blocking; - voice, breath, pacing, overlap, articulation, and silence; - spoken language, tactic, and subtext; - narrative circumstances and relationship state; - camera distance, movement, composition, lighting, and edit rhythm; - sound design and score; - animation or gameplay state; - human interpretations, confidence, and disagreement. ### 11.4 Comparison workflow 1. State a question, such as "How does restrained anger remain legible without volume?" 2. Select examples and counterexamples from rights-cleared sources. 3. Normalize only the dimension relevant to the question: line start, emotional turn, contact, or duration. 4. Record observations before revealing community or model interpretations. 5. Compare channel use and context. 6. Write a craft hypothesis with explicit limitations. 7. Convert the hypothesis into an original exercise. 8. Review whether the exercise communicated the intended relationship and stakes to multiple viewers. ### 11.5 Safety constraints - Do not infer a performer's real emotional or mental state from a performance. - Do not identify people through face or voice embeddings. - Do not treat facial action units or vocal features as proof of an emotion. - Do not score cultural conformity to a presumed universal expression template. - Do not expose private rehearsal or audition footage without explicit consent and access control. - Do not rank actors globally by "emotional truth" using opaque model scores. - Use behavior-specific language: "volume rises after the interruption" rather than "the actor is truly furious." ### 11.6 Practice outputs - Re-perform the same beat using restrained, escalating, and redirected tactics. - Animate the same line with different onset and recovery timing. - Shoot the same performance in a close-up and wide shot to study legibility. - Recut reactions to test when the audience reads the anger. - Redesign the sound bed while keeping the picture constant. - Write an original scene with the same dramatic function but different expression, relationship, and setting. ### 11.7 Generalization beyond anger Anger is the worked example, not the product boundary. The same facet model, evidence channels, comparison workflow, safety constraints, and practice outputs apply to any recurring performance or design question: fear, grief, joy, tension, comedic timing, seduction, menace, and awe, as well as non-emotional atlas subjects such as entrances, reveals, betrayals, boss introductions, and tutorial moments. Each new atlas template declares its own facets, contexts, and safety notes rather than inheriting anger's uncritically, because the contextual and cultural risks differ by subject. --- ## 12. Film-Specific Analysis ### 12.1 Source integrity A film record must identify the work, exact cut, frame rate, aspect ratio, language/subtitle/audio version, color/mastering information where known, and whether the source is a file, licensed stream, link-only provider, or internal production asset. Analyses across different cuts must not be silently merged. ### 12.2 Automatic suggestions Automation may suggest: - chapters, sequences, scenes, shots, transitions, and fades; - speakers, transcript alignment, dialogue turns, and sound events; - people, tracks, poses, regions, props, garments, and environments; - camera movement, composition features, color, lighting, motion, and focus changes; - music cues, tempo, loudness, ambience, and effects; - narrative beats, performance turns, motifs, and possible thematic relationships. These are reviewable suggestions. Shot detection and transcript alignment can be measured directly; theme and emotion require stronger contextual caution. ### 12.3 Production-material mode For creator-owned dailies, scripts, storyboards, EDL/XML/AAF markers, camera reports, sound reports, lens metadata, continuity notes, and take metadata, the workspace can provide deeper functions: - script-to-take alignment; - coverage and missing-beat maps; - performance continuity and alternate-take comparison; - camera/lens intent versus recorded metadata; - edit decision lineage; - VFX and sound turnover markers; - review and approval workflows. Production-material mode must remain permissioned separately from published-work study. --- ## 13. Game-Specific Analysis ### 13.1 Three analysis tiers The workspace must be honest about what it can know. | Tier | Source | Capabilities | Limits | | ----------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | A. Video-only | Authorized capture or link | Visual, audio, UI, apparent action, timing, level flow, manual mechanic annotation | Cannot know hidden state, exact inputs, AI state, or engine parameters | | B. Instrumented session | Creator-owned or authorized build | Video plus input, state, camera, animation, AI, combat, economy, network, and performance telemetry | Requires SDK/connector and compatible build | | C. Project-aware | Creator-owned source project and assets | Tier B plus asset, level, animation graph, behavior tree, data table, and version links | Never applies to extracted commercial assets without authorization | ### 13.2 Synchronization contract Instrumented sessions require: - a monotonic session clock and video clock mapping; - capture of drift and synchronization uncertainty; - build, patch, platform, content manifest, settings, device, and network metadata; - deterministic or best-effort replay classification; - event schemas with versioning and source ownership; - privacy filtering for player identifiers, chat, and telemetry; - explicit gaps when capture drops events or frames. ### 13.3 Instrumented event families - Input: device, action, press/release, analog value, buffering, remapping, and accessibility assists. - Player state: transform, velocity, locomotion, health, resources, status, inventory, target, and ability state. - Camera: mode, transform, target, obstruction, assist, shake, FOV, and transition. - Animation: state, montage, clip, normalized time, blend, root motion, notifies, IK, and contact. - Combat: attack phase, hitbox/hurtbox, collision, damage, stun, invulnerability, cancel, parry, and hit confirmation. - AI: perception, threat, state, goal, selected action, path, coordination, and difficulty modifier. - Level: checkpoint, volume, encounter, streaming, objective, landmark, route, and fail/retry. - Narrative: quest, dialogue, choice, flag, relationship, branch, consequence, and systemic story event. - Economy: source, sink, balance, purchase, reward, unlock, scarcity, and progression. - UI/audio/feedback: prompt, icon, haptic, sound, music state, subtitle, and accessibility feedback. - Technical: CPU/GPU frame time, latency, network, memory, streaming, errors, and dropped samples. ### 13.4 Game study outputs - Input-to-response latency map. - Mechanic state diagram and evidence-linked transition table. - Encounter and difficulty curve. - Tutorial teaching sequence and failure-recovery map. - Combat readability and decision-window timeline. - Camera/animation/control coupling analysis. - Level route, attention, landmark, and pacing map. - Economy source/sink and progression graph. - Player behavior heatmap with privacy thresholds. - Hit "feel stack" micro-timeline aligning hitstop frames, camera-shake amplitude and duration, particle bursts, sound layering, haptic and rumble events, and UI feedback for a single action, so game feel can be studied as a composed stack of timed decisions rather than a vague impression. - Reproducible session bookmark containing build, save/checkpoint, settings, and event range. ### 13.5 External-title constraint For games the user does not own or control, the product should remain in video-only study mode unless the publisher or platform provides an authorized data interface. It must not inject into processes, evade anti-cheat, scrape memory, decrypt archives, or extract protected assets. ### 13.6 Video-only analysis assists The gap between video-only and instrumented study can be narrowed honestly with detections that read only what is visibly on screen: - **HUD parsing.** Health, resource, ammunition, cooldown, score, damage numbers, and objective text read through OCR and template detection, always labeled as detections with confidence, and never presented as telemetry. - **Input-overlay recognition** for footage that includes a capture-card or community input display, with explicit uncertainty for dropped, occluded, or ambiguous indicators. - **Community data import.** Frame-data tables, patch notes, and mechanics wikis can be attached as source-documented facts with citation, version, and authorship, clearly separated from anything measured inside this workspace. - Assist outputs never claim hidden state. They give Tier A study quantitative traction while preserving that tier's stated limits, and every assist value remains traceable to the frames it was read from. --- ## 14. Search, Comparison, Inspiration, and Synthesis ### 14.1 Search modes - **Exact metadata:** work, edition/build, creator, performer, character, level, date, genre, language, platform. - **Taxonomy:** shot type, motion principle, garment, narrative function, mechanic, sound event, emotion-related facet. - **Full text:** transcripts, notes, source documents, comments, and creator statements. - **Semantic:** natural-language queries over permitted embeddings and grounded descriptions. - **Visual:** palette, composition, silhouette, pose, object, region, or image similarity. - **Motion:** pose sequence, trajectory, timing, contact, or action similarity. - **Audio:** voice, rhythm, timbre, music, sound-event, or mix similarity. - **Runtime:** event sequence, state transition, mechanic, input pattern, or performance condition. - **Relational:** character-to-character, motif-to-scene, garment-to-faction, mechanic-to-emotion, claim-to-evidence, source-region-to-principle, principle-to-original-concept, or decision-to-production-artifact. ### 14.2 Query contract A query should be able to express: ```text Find intervals where: interpretation includes restrained anger AND observed vocal volume does not rise more than the corpus threshold AND the character is interrupted by a higher-status character AND camera scale is close-up or medium close-up AND rights permit in-workspace comparison Return: source anchors, observations, dissent, confidence, and context Group by: acting tradition and genre ``` The result must not imply that an interpretation is a measured fact. Filters must identify whether values are detected, observed, interpreted, or source-documented. ### 14.3 Comparison alignment Supported alignment strategies should include: - absolute time or frame; - normalized clip duration; - selected beat or line; - motion event such as anticipation, impact, or settle; - narrative event such as reveal, reversal, or decision; - gameplay event such as input, telegraph, hit, failure, or reward; - manually placed sync markers. ### 14.4 Synthesis rules - Every generated synthesis links to the evidence set it used. - Conflicting evidence and dissent appear in the output. - The synthesis declares corpus boundaries and missing context. - Model-generated causal language is softened unless supported by a study or creator statement. - Users can freeze a synthesis against exact source and analysis versions. - Regeneration creates a new version; it does not overwrite the prior scholarly record. ### 14.5 Inspiration workspace contract The inspiration workspace is a project-specific research surface, not a free-floating recommendation feed. Each collection begins with a question or creative intent and names the original project entities it is meant to inform. It must support film, television, animation, games, performances, still images, concept art, scripts, storyboards, sound, documents, historical material, and creator-owned 3D or engine assets under one rights-aware evidence model. Every inspiration item records: - its exact evidence anchor and permitted preview; - why it was selected and which aspect is relevant; - the intended audience experience or design problem it helps investigate; - an abstracted principle or an explicit unanswered question; - what must not be copied or transferred; - its role as support, contrast, counterexample, boundary, precedent, warning, or unresolved possibility; - rights, attribution, cultural context, confidence, authorship, review state, and version. The primary composition should be image- or media-led. The active image, frame, region, or clip receives the dominant canvas; navigation and relationship details remain restrained secondary context. The canvas, contact sheet, matrix, graph, timeline, and notebook are interchangeable views over shared data rather than separate stores. No relationship may be inferred merely from proximity on the canvas. ### 14.6 Typed visual and multimodal knowledge graph Any addressable level in the evidence hierarchy can be a graph node: corpus, work, edition/build, sequence, scene, encounter, shot, beat, frame, image, region, entity, material, palette, pose, motion segment, sound interval, transcript span, runtime event, document passage, study claim, craft principle, original concept, or creative decision. Every edge must declare: - source and target, with direction when meaningful; - relationship type and plain-language rationale; - author or suggesting model, creation time, confidence, and review state; - supporting anchors, counterevidence, cultural or contextual bounds, and rights dependencies; - validity interval and supersession history when a source or project evolves. Required graph behavior includes bidirectional backlinks, path inspection, neighborhood expansion, filtered traversal, grouping, clustering, saved graph views, and queries such as "show every source region that informed this faction rule" or "show which original decisions depend on this expiring source." Suggested entity identity and relationship links remain provisional until reviewed. Visual similarity alone never merges people, characters, objects, assets, places, cultures, or concepts. ### 14.7 Cross-work and cross-media comparison matrix Corpus-level comparison must not inherit the simultaneous-player limit. A comparison set may contain any supported number of works or examples, while interactive synchronized playback remains a two-to-eight-up focused view. The matrix should support: - rows or columns for works, scenes, frames, regions, entities, or project concepts and user-selected craft dimensions on the other axis; - multi-key sorting, grouping, faceting, clustering, annotation, and saved comparison templates; - observed differences, interpretations, unknowns, dissent, and counterexamples without filling missing values with model guesses; - within-medium alignment and explicitly labeled cross-media functional analogy, such as film pacing versus player-controlled pacing; - roll-up from regions to images, scenes, works, collections, and corpora while retaining the underlying anchors; - drill-down from a corpus pattern to each supporting or contradicting example. ### 14.8 Similarity, difference, and discovery Discovery should answer more than "show visually similar pictures." Supported intent modes include: - **More like this** along user-selected dimensions such as palette, composition, shape, motion, sound, mechanic, tone, or narrative function. - **Functionally analogous** examples that solve a comparable problem through a different medium, genre, culture, period, or craft technique. - **Productive contrast** and **show me something unlike these** to challenge an emerging pattern. - **Bridge references** that explain a path between otherwise distant clusters. - **Coverage gaps** showing missing views, cultures, eras, disciplines, counterexamples, or world-system dimensions. Every result explains why it was retrieved, which features or relationships contributed, what evidence is missing, and whether it is permitted for the requested action. Users can weight or exclude dimensions and choose diversity, distance, culture, period, medium, and source boundaries. The system must avoid feedback loops that repeatedly recommend one famous work, one style, or close derivatives of already selected references. ### 14.9 Original film, game, and world synthesis Source-derived graphs and original-project graphs remain distinct. A learner creates project-native concepts and connects them to abstracted principles, not directly reusable protected expression. Supported concept systems should cover, where relevant: - premise, theme, tone, genre contract, audience experience, and dramatic questions; - characters, relationships, factions, cultures, institutions, language, belief, ritual, history, conflict, and power; - geography, architecture, environment, ecology, climate, resources, technology, material culture, costume, props, color, and visual rules; - sound worlds, musical rules, voice, rhythm, silence, and sonic motifs; - levels, quests, encounters, mechanics, controls, feedback, economy, progression, AI, camera, animation, UI, accessibility, and player agency; - film structure, sequence and scene logic, performance rules, camera grammar, lighting, editing, VFX, and production constraints. The workspace should expose coverage and consistency views across these systems. It flags contradictions as questions rather than declaring them errors, because intentional contradiction can be a valid creative choice. It also reports source concentration, overly direct mappings, unsupported assumptions, and concepts with no evidence or original rationale. A decision becomes committed only after a person records its rationale, alternatives, transformation from source principles, and intended project effect. ### 14.10 Source-to-decision trace and change impact The system must preserve a navigable chain: ```text authorized source -> exact work / moment / image / region / event -> observation or documented fact -> interpretation and counter-reading -> reusable principle or constraint -> original project concept -> creative decision -> brief / scene / asset / mechanic / task / prototype -> playtest / screening / review outcome -> principle and decision track record ``` Users can traverse the chain in either direction. When a source expires, a claim is contested, an analysis changes, or a project decision is revised, the workspace identifies every dependent collection, concept, decision, export, and production artifact. It does not silently rewrite accepted creative decisions; it opens a review task with the affected evidence path and available alternatives. ### 14.11 Outcome evidence and principle track records The chain must not end at the production artifact. When a decision's output is exercised — a playtest, a screening, a review session, or a shipped release — the resulting evidence flows back into the study record: - **Outcome evidence** attaches playtest telemetry, screening and review feedback, and release analytics to the creative decision it exercises, under the same anchor, rights, privacy, and consent discipline as source evidence. - A decision records its intended audience effect when it is committed. Outcome evidence is evaluated against that stated intent, never against a generic quality score. - Craft hypotheses and creative principles accumulate a **track record**: where each was applied, what was intended, and what the outcome evidence supported, contradicted, or left unresolved. - Track records are contextual summaries, not scores. "The held reaction preserved pressure in two of four uses" is a review input for the next decision; it never automatically promotes or demotes a principle. - Outcome evidence uses the practice-result epistemic family and never rewrites the original study record. Like source changes in the dependency model above, it opens review on the decisions and principles it affects. This closes the loop: the workspace stops being a one-way pipeline from other people's work into the learner's project and becomes a system in which the learner's own results continuously test the principles they extracted. --- ## 15. Learning and Practice System ### 15.1 Learning loop ```mermaid flowchart LR Q[Question] --> O[Observe source] O --> D[Deconstruct with evidence] D --> C[Compare and form hypothesis] C --> P[Original practice exercise] P --> F[Feedback and reflection] F --> M[Mastery update] M --> Q ``` The question that starts this loop is a first-class, durable object (`StudyQuestion`, Section 16.1), not a transient prompt. It carries a lifecycle of open, under investigation, answered, or abandoned; links the observations, comparisons, inspiration collections, and exercises it spawned; and makes unanswered questions a queryable surface across a project rather than text buried inside individual collections. ### 15.2 Craft concept graph Metis should model concepts and prerequisites without pretending that all artistic growth is linear. Examples: - frame navigation before shot-rhythm analysis; - observable behavior before performance interpretation; - timing and spacing before complex animation polish; - goal/rule/feedback before economy-balancing analysis; - focal length and distance before perspective comparison; - source observation before cultural or thematic interpretation. Mastery can combine factual knowledge, perceptual discrimination, analysis quality, production application, reflection, and repeated performance. Taste and creative originality should not be collapsed into one numeric mastery probability. This pedagogical concept graph is distinct from the original-project concept graph in Section 14. Metis models what a learner is practicing and which craft ideas support other ideas; the project graph models the learner's own world, characters, systems, and creative decisions. They may link through exercises and principles, but neither silently becomes the other. ### 15.3 Exercise types - Identify and justify a shot, beat, pose, mechanic, sound cue, garment, or story function. - Blind comparison before revealing metadata or peer interpretation. - Sort examples by a declared observable dimension. - Mark boundaries and compare with expert or consensus annotations. - Reconstruct a state graph, shot map, blocking diagram, or sound hierarchy. - Create an original scene, animation, shot, costume, level, or mechanic under constraints. - Diagnose a learner-owned attempt and propose a revision. - Teach-back: explain a principle with source anchors and a counterexample. - Portfolio reflection comparing early and revised attempts. ### 15.4 Assessment dimensions - Anchor accuracy and source use. - Separation of observation from interpretation. - Appropriate use of craft vocabulary. - Context awareness and acknowledgment of uncertainty. - Quality of comparison and counterexample selection. - Causal humility: whether claims exceed the evidence. - Transfer into an original solution. - Revision quality and ability to explain decisions. ### 15.5 Feedback rules - Automated feedback must cite the learner's source anchor or attempt moment. - Feedback should be actionable and behavior-specific. - Rubrics expose criteria and allow teacher override with reasons. - Peer and model feedback remain distinguishable. - Learners can challenge a label or score. - Creative divergence can satisfy a principle through a different solution. ### 15.6 First-viewing and re-watch protocol Analytical study should not destroy the naive first experience, which is itself evidence about what the craft did to a viewer. - A first-viewing mode records naive observations and reactions with an explicit first-viewing context so they are never confused with informed analysis. - Spoiler-safe study hides annotations, beat labels, community claims, and structural navigation beyond the current playhead until the learner opts in or completes the work. - Re-watch passes can be declared with a focus such as structure, camera, or sound, and the workspace can compare naive impressions with informed readings — often the clearest demonstration of how a technique worked on the learner before they could name it. - Teachers can assign a blind first pass before releasing an annotated study set, matching the blind-comparison exercise pattern above. ### 15.7 Retention and spaced review Study that is never revisited decays. The practice system should include: - spaced-repetition review of study cards, claim cards, and craft vocabulary, reusing the repository's existing scheduler implementations (the FSRS family and item-response models already in Metis) rather than inventing a new algorithm; - auto-generated perceptual discrimination drills built only from rights-permitted derivatives, such as "which of these two shots uses the longer lens" or "which clip cuts on the action"; - drill provenance: every generated drill records its source anchors and the intended discrimination, and the learner can always open the underlying evidence; - retention items that link back to the originating question, study card, or exercise so review reinforces the learner's own findings rather than detached trivia. ### 15.8 Onboarding, seeded studies, and cold start An empty workspace teaches nothing, and the first hour decides whether a learner returns. The first release should ship with: - expert-authored exemplar studies on rights-cleared sources that demonstrate a complete question-to-decision loop the learner can inspect, fork, and redo; - open production corpora as first-class seed material — the Blender open movies are uniquely valuable because their full production assets (scripts, storyboards, scene files, and renders) are openly licensed, which exercises production-material mode and the creator-owned 3D lens with no rights risk; - open-source games as instrumented-tier seed content where telemetry hooks can be added freely; - guided study-along walkthroughs that scaffold the first project: a bounded question, a prepared source, prompted observation, and a first exercise; - template galleries for comparison sets, atlas facets, and annotation templates, so the first session produces a real artifact rather than configuration. --- ## 16. Data and Knowledge Model ### 16.1 Core entities | Entity | Purpose | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | `StudyProject` | Members, purpose, curriculum, policies, sources, notebooks, and project links | | `StudyQuestion` | First-class research question with lifecycle, scope, and links to the evidence, comparisons, collections, and exercises it spawned | | `SourceWork` | Canonical film/game/work identity independent of a particular copy | | `SourceEdition` | Cut, version, build, patch, platform, language, frame rate, and technical identity | | `EditionAlignmentMap` | Reviewable correspondences between editions, cuts, builds, or patches of the same work, with method, confidence, and explicit gaps | | `SourceAsset` | File, stream reference, transcript, image, telemetry bundle, project asset, or document | | `RightsGrant` | Authority, territory, expiry, allowed actions, retention, sharing, and evidence | | `MediaTrack` | Video, audio, subtitle, transcript, telemetry, camera, animation, or other synchronized stream | | `Segment` | Hierarchical temporal unit with human/model provenance | | `EvidenceAnchor` | Exact source locator and permitted derivative representation | | `StudyEntity` | Character, performer, garment, prop, location, camera, mechanic, level, sound, motif, and more | | `Detection` | Machine output with model/run/version, feature, confidence, and review state | | `Observation` | Human-authored description tied to anchors | | `InterpretationClaim` | Contextual reading with support, counterevidence, epistemic status, and dissent | | `CraftHypothesis` | Reusable proposition derived from selected evidence and bounded by limitations | | `TaxonomyTerm` | Versioned domain vocabulary and relationships | | `ComparisonSet` | Question, inclusion logic, aligned examples, counterexamples, and layout | | `InspirationCollection` | Project question, scope, target concepts, items, views, collaborators, and diversity posture | | `InspirationItem` | Evidence-backed selection, relevant aspect, intended effect, exclusions, and transfer warning | | `CrossReference` | Typed, directed, reviewable relationship between any addressable evidence or project targets | | `CreativePrinciple` | Abstracted, source-supported principle safe to consider in original work | | `OriginalConcept` | Project-native world, character, location, system, craft-rule, or other design entity | | `CreativeDecision` | Versioned choice, rationale, alternatives, owner, status, dependency paths, and outputs | | `OutcomeEvidence` | Playtest, screening, review, or release evidence attached to the decision it exercises and rolled into principle track records | | `Notebook` / `StudyCard` | Durable Nisaba narrative and atomic insight | | `PracticeExercise` | Objective, constraints, rubric, examples, rights, and expected evidence | | `PracticeAttempt` | Learner-owned artifact, anchors, feedback, reflection, and version | | `MasteryRecord` | Metis concept evidence and progression | | `SpacedReviewItem` | Scheduled retention item derived from a study card, claim, term, or perceptual drill, with source anchors | | `ProjectTransfer` | Abstracted insight, target project, task, provenance, and anti-copying review | | `AnalysisRun` | Pipeline, models, configurations, input versions, cost, status, and outputs | | `ReviewDecision` | Human acceptance, correction, contest, rejection, or approval | ### 16.2 Relationship model ```mermaid flowchart TD P[StudyProject] --> W[SourceWork] W --> E[SourceEdition] E --> A[SourceAsset] A --> R[RightsGrant] A --> T[MediaTrack] T --> S[Segment] S --> X[EvidenceAnchor] X --> D[Detection] X --> O[Observation] D --> O O --> I[InterpretationClaim] I --> H[CraftHypothesis] H --> C[ComparisonSet] H --> N[StudyCard / Notebook] X --> J[InspirationItem] J --> B[InspirationCollection] J --> L[CrossReference] H --> K[CreativePrinciple] B --> G[OriginalConcept graph] K --> G L --> G G --> V[CreativeDecision] N --> Q[PracticeExercise] Q --> U[PracticeAttempt] U --> M[MasteryRecord] N --> Y[ProjectTransfer] V --> Y P --> QS[StudyQuestion] QS --> C QS --> B QS --> Q V --> Z[OutcomeEvidence] Z --> K ``` `CrossReference` endpoints are not limited to the simplified arrows above. An edge may connect any stable source, anchor, entity, claim, principle, inspiration item, original concept, decision, or production-artifact reference. The relational record remains authoritative even when canvas, matrix, graph, timeline, or notebook projections render it differently. ### 16.3 Identity and versioning rules - A work identity must not collapse editions, cuts, builds, or regional versions. - Edition alignment maps connect versions without merging them: a migrated anchor is a reviewed suggestion that records both endpoint versions, and unmapped material remains an explicit gap. - Media hashes identify exact bytes; provider references identify externally controlled sources. - Segment IDs remain stable only within a source revision and segmentation version. - Human corrections produce versioned supersession, not silent mutation. - Analysis outputs record the exact model, prompt/configuration, feature extractor, code version, and input revision. - Taxonomy changes use migrations and aliases so old notebooks remain readable. - Cross-reference endpoint versions are immutable; a changed target creates a reviewed supersession instead of silently retargeting an existing edge. - Suggested identity links never merge canonical entities until a person or an authorized domain workflow accepts the merge with evidence. - Original concepts use project-owned identities and never masquerade as source-work entities, even when a source inspired them. - Deletion and rights expiry propagate to derivatives, embeddings, caches, exports, shared views, relationship projections, and decision impact reports. ### 16.4 Storage profile - **Object storage:** authorized originals and derived media, encrypted and lifecycle-controlled. - **Relational store:** projects, rights, hierarchy, anchors, claims, reviews, inspiration collections, typed cross-references, original concepts, creative decisions, jobs, and learning records. - **Search index:** text, facets, permissions, and source-aware retrieval. - **Vector index:** permitted visual, motion, audio, and semantic embeddings with model/version metadata. - **Graph projection:** source, region, entity, motif, narrative, comparison, inspiration, original-concept, creative-decision, and claim-evidence relationships with permission-filtered traversal. - **Time-series/event store:** instrumented gameplay and processing telemetry where volume warrants it. - **Audit ledger:** rights decisions, access, exports, deletion, model runs, and review actions. PostgreSQL should remain the authoritative metadata store. Search, vector, graph, and time-series systems are projections that can be rebuilt. --- ## 17. Proposed System Architecture ### 17.1 Logical architecture ```mermaid flowchart TB UI[Oshun Studio /studio/study] --> BFF[Study Workspace BFF] BFF --> WS[Yemaya Study Orchestrator] WS --> NS[Nisaba study and notebook adapter] WS --> SP[Sophia evidence, provenance, and search adapter] WS --> AJ[Aja video, pose, motion, and annotation adapter] WS --> HA[Hathor narrative, character, directing, and MDA adapter] WS --> EU[Euterpe audio, voice, and music adapter] WS --> AG[Aglaea costume and material adapter] WS --> BE[Bellona game-session and engine adapter] WS --> ME[Metis curriculum, assessment, and mastery adapter] WS --> IS[Isis multimodal inference gateway] WS --> DB[(PostgreSQL)] WS --> OBJ[(Rights-aware object storage)] WS --> IDX[(Search and vector projections)] WS --> GPH[(Relationship graph projection)] WS --> BUS[(Durable jobs and events)] ``` ### 17.2 Proposed repository placement The final paths require an ADR and project graph review, but the intended separation is: - `apps/oshun/web/src/app/studio/study/` — canonical route composition. - `apps/yemaya/svc-study-workspace/` — orchestration API and job coordination. - `libs/yemaya/study-workspace/` — client-neutral use cases and policies owned by Yemaya. - `libs/contracts/` — shared versioned study, evidence, rights, and event contracts. - Domain adapters under their owning domains, not copied into Yemaya. - Existing `apps/aja/svc-reference-video` evolves or is wrapped behind an Aja adapter rather than duplicated. - Nisaba notebooks and Sophia provenance remain canonical through adapters. ### 17.3 Orchestrator responsibilities The Yemaya study orchestrator should own: - study-project lifecycle; - composed source hierarchy; - lens selection and analysis-job orchestration; - cross-domain permissions and rights enforcement; - normalized evidence/claim read models; - comparison-set coordination; - inspiration-collection, typed cross-reference, original-concept, and source-to-decision coordination; - dependency and change-impact calculation across evidence and creative decisions; - project transfer; - API aggregation for the Studio route. It should not own: - domain taxonomies that already have an owner; - raw motion, narrative, sound, costume, learning, or game-engine algorithms; - the canonical provenance or notebook implementation; - general-purpose model hosting; - global identity, tenant, or audit infrastructure. ### 17.4 Adapter rules - Every adapter has a versioned input/output contract and declared capability list. - Missing capabilities return an explicit unsupported status, never synthetic success. - Domain-native IDs and evidence anchors are preserved. - Adapter results carry model/code version, confidence, cost, latency, and review state. - Permission filters apply before data enters search, embeddings, or downstream models. - Cross-domain derived claims preserve all upstream evidence and policy dependencies. --- ## 18. Ingestion and Analysis Pipeline ### 18.1 Pipeline stages 1. **Authorize** — authenticate, resolve tenant/project access, declare source authority, and create a provisional rights decision. 2. **Identify** — hash or reference the source; resolve work and edition/build metadata without silently merging versions. 3. **Secure ingest** — scan, quarantine, verify content credentials where present, copy or link according to policy, and record provenance. 4. **Normalize** — probe tracks, validate time bases, transcode permitted proxies, align audio/subtitles/transcripts/telemetry. 5. **Structure** — suggest hierarchy, scenes, shots, beats, encounters, entities, and tracks. 6. **Extract signals** — visual, motion, audio, transcript, runtime, and technical features. 7. **Run lenses** — invoke domain analyzers against stable anchors. 8. **Ground and review** — bind outputs to evidence, calibrate confidence, expose human correction, and block unsupported claims. 9. **Index** — write permission-filtered text, facet, vector, and graph projections. 10. **Connect and review** — suggest explainable similarities, analogies, contrasts, identity candidates, coverage gaps, and typed relationships without accepting them automatically. 11. **Teach and transfer** — create study cards, inspiration collections, comparisons, original concepts, creative decisions, exercises, and project handoffs. 12. **Retain or delete** — enforce expiry, deletion, dependency review, and derivative lifecycle continuously. ### 18.2 Job behavior - Jobs are idempotent for the same source revision and configuration. - Each stage can retry independently and records structured failure reasons. - Long-running jobs expose progress by source, stage, lens, and estimated remaining work. - Users can begin manual study before optional automated stages finish. - Models and quality tiers are selectable within policy and budget. - Partial success is explicit; one failed lens does not invalidate validated outputs from another. - Cancellation stops downstream work and cleans uncommitted derivatives. - Reanalysis creates new versioned outputs and a diff against prior accepted annotations. ### 18.3 Human-in-the-loop checkpoints - Rights uncertain or insufficient. - Work/edition/build identity ambiguous. - Low-confidence segmentation or synchronization. - Identity-sensitive tracking or private performance footage. - Emotion, culture, mental state, authorial intent, or other high-interpretation claims. - Model disagreement above threshold. - Suggested cross-source entity identity, cultural equivalence, influence, or causal relationship. - Export or project transfer that approaches protected expression. - Publication of a shared study pack or learner assessment. --- ## 19. Contracts, APIs, and Events ### 19.1 Proposed API groups | API group | Example responsibilities | | ----------------------------- | -------------------------------------------------------------------------- | | `/study-projects` | Create, list, membership, policy, archive, export | | `/sources` | Add/link, identity, versions, metadata, retention, deletion | | `/rights` | Resolve, attach evidence, approve, expire, audit allowed actions | | `/tracks` and `/segments` | Timeline tracks, hierarchy, corrections, alignment | | `/anchors` | Frame/time/region/event/transcript locators and snapshots | | `/analyses` | Capability discovery, estimate, run, cancel, status, versions, diffs | | `/observations` | Manual observations, review, correction, provenance | | `/claims` | Interpretations, support, counterevidence, dissent, epistemic status | | `/entities` and `/taxonomies` | Cross-source entities, domain terms, relationships | | `/search` | Hybrid query with source, epistemic, rights, and permission filters | | `/comparisons` | Sets, alignment, layouts, snapshots, collaborative review | | `/inspiration-collections` | Project questions, evidence-backed items, views, coverage, collaborators | | `/cross-references` | Typed edges, rationale, evidence, suggestions, review, traversal, impact | | `/original-concepts` | Project-native entities, system maps, consistency questions, versions | | `/creative-decisions` | Principles, alternatives, approval, dependencies, backlinks, change review | | `/notebooks` | Nisaba-backed cards, narratives, citations, publishing | | `/practice` | Exercises, attempts, rubrics, feedback, mastery evidence | | `/project-transfers` | Originality review, destination, tasks, backlinks | | `/game-sessions` | Manifests, clocks, telemetry, replays, checkpoints, events | | `/study-questions` | Question lifecycle, linked evidence, status, and unanswered-question views | | `/edition-alignments` | Cross-edition and cross-build correspondences, review, anchor migration | | `/live-sessions` | Synchronized group playback, anchored discussion, claim crystallization | | `/outcome-evidence` | Playtest, screening, and release evidence; principle track records | ### 19.2 Proposed domain events - `study.project.created` - `study.question.opened` - `study.question.resolved` - `study.source.authorization.requested` - `study.source.rights.resolved` - `study.source.ingested` - `study.source.expired` - `study.source.deletion.requested` - `study.source.deletion.completed` - `study.track.normalized` - `study.segmentation.proposed` - `study.segmentation.corrected` - `study.edition_alignment.proposed` - `study.edition_alignment.reviewed` - `study.paratext.aligned` - `study.analysis.requested` - `study.analysis.completed` - `study.analysis.partially_failed` - `study.detection.reviewed` - `study.observation.created` - `study.claim.created` - `study.claim.contested` - `study.comparison.published` - `study.live_session.started` - `study.live_session.crystallized` - `study.inspiration_collection.created` - `study.inspiration_item.pinned` - `study.cross_reference.suggested` - `study.cross_reference.reviewed` - `study.original_concept.created` - `study.creative_decision.committed` - `study.creative_decision.impact_review_requested` - `study.outcome.evidence_recorded` - `study.notebook.saved` - `study.practice.assigned` - `study.practice.attempted` - `study.mastery.evidence_recorded` - `study.project_transfer.created` - `study.export.created` ### 19.3 Contract invariants - Every analysis, observation, claim, comparison item, and feedback item has at least one authorized evidence anchor. - Every machine output has an analysis run and model/code version. - Every interpretation declares its epistemic type and author. - Every read and export is rights- and permission-filtered. - Every source locator states its time base and version. - Every game event states schema version and session/build identity. - Every inspiration item has an authorized anchor, a declared relevance, and an explicit transfer warning or exclusion state. - Every cross-reference has typed endpoints, rationale, provenance, review state, and permission-filtered traversal behavior. - Every committed creative decision can traverse through an abstracted principle to evidence or explicitly states that it is an original unsupported exploration. - No model-suggested relationship, identity, cultural equivalence, or source influence is represented as human-accepted without a review event. - Every deletion request is traceable through all derivative stores. ### 19.4 Interoperability profile - Use W3C Web Annotation-style bodies, targets, selectors, motivations, and provenance where they can represent the anchor without loss. - Represent portable typed cross-references with stable identifiers and JSON-LD-compatible relation semantics where practical; workspace canvas coordinates remain optional presentation metadata. - Use IIIF Presentation/Image concepts for rights-permitted still images, document canvases, tiled deep zoom, ranges, and region annotations. - Preserve SMPTE-compatible timecode semantics and rational frame rates for linear media. - Prefer established subtitle, transcript, edit-marker, camera-report, and production metadata formats before inventing workspace-only representations. - Define an engine-neutral game-session envelope, then publish adapters for Unreal, Unity, Godot, and product-specific runtimes as justified. - Support glTF/GLB as a portable creator-owned 3D study format while retaining source-DCC or engine identifiers and richer native metadata through sidecars. - Export standard annotations and a workspace manifest separately from media so recipients can honor their own source permissions. - Verify and preserve C2PA content credentials at ingest where present, and attach C2PA manifests to exported study packs and learner attempts through the repository's existing content-signing capability ([`libs/shared/content-signing`](../../libs/shared/content-signing)). - Reuse the repository's existing Nisaba standards support in [`reference-linked-data.ts`](../../libs/nisaba/standards/src/reference-linked-data.ts) rather than creating a competing annotation vocabulary. --- ## 20. Rights, Privacy, Safety, and Epistemic Integrity ### 20.1 Rights model The current performance-reference enum (`owned`, `licensed`, `fair-use-reference`, `internal`) is useful as a prototype but insufficient for production. "Fair use" is contextual and jurisdiction-dependent; it cannot be self-certified by a generic enum and then treated as unlimited authorization. A `RightsGrant` should include: - source of authority and supporting evidence; - owner/licensor and authorized user or organization; - work, edition, asset, and territory; - start, expiry, revocation, and review dates; - allowed playback, frame extraction, proxy generation, transcription, embedding, model analysis, collaboration, teaching, publication, export, and project-transfer actions; - maximum resolution, clip duration, storage location, and retention; - attribution and notice requirements; - commercial/non-commercial and internal/external use; - performer, student, employee, or participant consent where applicable; - policy decision, reviewer, legal basis, and audit history. ### 20.2 Source policy classes | Class | Default behavior | | ----------------------------- | -------------------------------------------------------------------------------------------------- | | Creator-owned/internal | Full analysis within project policy; explicit participant consent for private performance material | | Explicitly licensed | Enforce the exact grant and expiry | | Public domain/open license | Verify status and attribution; record jurisdiction and license version | | Provider link-only | Deep-link or authorized playback; no download, decryption, or unauthorized persistent derivative | | User-declared study reference | Quarantine sharing/export; require policy review for derivatives and model processing | | Restricted/prohibited | Metadata-only record or rejection; no analysis derivatives | ### 20.3 Copyright and originality safeguards - Do not bypass DRM or access controls. - Do not make long source clips or high-resolution frames broadly exportable by default. - Apply output limits based on grant, not a universal clip-length assumption. - Preserve attribution and source links in every study pack. - Detect and warn when a project transfer carries highly specific protected expression rather than an abstract principle. - Detect source concentration and direct one-to-one mappings that make an original concept depend too heavily on one protected work; present the result as a review warning, not an originality score or legal conclusion. - Prefer principle cards such as "hold the reaction before cutting" over extractable assets or near-copy prompts. - Keep source-derived embeddings and model training opt-ins separate from ordinary analysis consent. - Provide takedown, rights correction, expiry, and deletion processes. ### 20.4 Performer and learner privacy - Private rehearsal, audition, classroom, mocap, voice, and gameplay footage is restricted by default. - Face and voice features are treated as sensitive derived data even when not used for identity. - No face recognition, voice identification, demographic inference, mental-health diagnosis, or deception detection. - Identity labels are human-provided or source-metadata-based, not inferred through biometric matching. - Minors require a dedicated consent, access, retention, and publication policy. - Users can inspect, correct, export, and delete their own attempts and derived features. - Shared examples require consent compatible with the intended audience. ### 20.5 Epistemic integrity Every claim should carry one of the product's governed epistemic statuses, aligned where possible with Sophia/Aletheia conventions: - directly observed; - model-suggested; - source-documented; - widely established craft convention; - one interpretation; - contested; - speculative; - insufficient context. The system should additionally store support strength, counterevidence, reviewer agreement, corpus boundary, and known limitations. ### 20.6 Bias and cultural safety - Evaluate expression, gesture, gaze, voice, costume, body, and emotion models across cultures, languages, skin tones, ages, disability presentations, gender expression, and performance traditions. - Do not treat Western naturalism, one animation tradition, or one game genre as the neutral baseline. - Require source-backed cultural and historical claims. - Display who authored a taxonomy and where it may not transfer. - Invite counter-readings and community review without allowing harassment or identity targeting. ### 20.7 Security - Tenant- and project-scoped authorization on originals, derivatives, annotations, embeddings, and exports. - Encryption in transit and at rest, signed URLs, short-lived access, and audit logging. - Malware and media-parser sandboxing at ingest. - SSRF protection for URL imports and provider callbacks. - Content-type, size, duration, codec, archive, and decompression limits. - Model prompt-injection and untrusted transcript/document isolation. - Secret and token separation from exported notebooks. - Rate, cost, and concurrency limits per tenant and analysis tier. ### 20.8 Content authenticity and synthetic media - Verify C2PA content credentials at ingest when they are present; record the manifest, signer, and validation result as source facts. - Label detected or declared AI-generated and AI-modified source material. Studying synthetic references is legitimate, but a learner must know whether a "performance" was ever performed, because that changes what the source is evidence of. - Treat the absence of credentials as unknown provenance, never as evidence of manipulation. - Sign exported study packs, notebooks, and learner attempts with content credentials through the repository's content-signing capability so recipients can verify origin and integrity. - Propagate synthetic-media labels into search filters, comparison sets, atlas facets, and evaluation slices so synthetic and captured performances are never silently pooled. --- ## 21. Accessibility and Internationalization ### 21.1 Accessibility requirements - Complete keyboard operation for player, timeline, annotation, comparison, lens controls, inspiration canvas, relationship graph, matrix, project concept map, and dialogs. - Screen-reader names, states, relationships, and useful summaries for visualizations. - Non-spatial list, outline, and structured-table alternatives for every canvas or graph operation, including link creation, traversal, grouping, and source-to-decision inspection. - Captions, searchable transcripts, speaker labels, and transcript-follow playback. - Audio description tracks or user-authored visual-description notes where available. - Waveform and sound-event information represented textually, not only visually. - Color-independent tracks, confidence, review states, and comparison differences. - Reduced-motion mode for animated overlays, scrubbing effects, and synchronized views. - Configurable text size, contrast, focus appearance, timeline density, and playback controls. - One-handed and switch-access-friendly commands where feasible. - Time extensions and non-timed alternatives in exercises. - Alt-text and structured-table exports for contact sheets and diagrams. - Keyboard-reachable region descriptions and text alternatives for image crops; a picture-to-picture connection must never depend on sight or line color alone. ### 21.2 Internationalization requirements - Multiple dialogue, subtitle, transcript, translation, and transliteration tracks. - Locale-aware timecode display, dates, numbers, names, and sort behavior. - Right-to-left layout support across player-adjacent text, timeline labels, and notebooks. - Search across original text, translation, transliteration, and aliases without erasing language identity. - Cultural and regional taxonomy variants with explicit provenance. - Translation quality and confidence displayed separately from source dialogue. - No assumption that a translated line preserves rhythm, status, wordplay, or subtext. --- ## 22. Non-Functional Requirements ### 22.1 Performance targets Initial product targets, to be validated on representative hardware and sources: - Cached source shell and metadata interactive within 2 seconds at the 75th percentile. - Local frame-step response under 100 ms when a proxy is buffered. - Timeline pan/zoom and overlay toggles sustain 60 frames per second on the supported desktop baseline, with a 30-fps accessible fallback. - Search returns the first useful page within 1 second for ordinary project queries and 3 seconds for hybrid cross-modal queries. - An inspiration collection with 10,000 items remains filterable and searchable without loading every preview, and a 5,000-node filtered relationship view supports progressive expansion rather than attempting an unreadable full layout. - Manual annotation remains available while background analysis runs. - Progress appears within 1 second of starting a long job. - Instrumented game synchronization reports drift and aims for less than one displayed frame where the connector supports it. These are release budgets, not claims about current code. ### 22.2 Reliability - No accepted annotation, notebook edit, rights decision, or practice submission is lost after acknowledgement. - Analysis jobs are retryable and idempotent. - Partial failures are visible and recoverable. - Source expiry or permission loss blocks access immediately and schedules derivative cleanup. - Offline or unstable connections preserve manual notes in a conflict-safe local queue where policy permits. - Backups and restores include relationships between source revisions, anchors, claims, inspiration items, cross-references, original concepts, creative decisions, and notebooks. ### 22.3 Scale and cost - Separate cheap metadata/manual workflows from expensive multimodal runs. - Estimate time, GPU class, storage, and monetary cost before processing. - Deduplicate authorized features by exact source revision and model configuration without crossing tenant boundaries. - Use tiered proxies and lazy high-resolution frame access. - Index only policy-permitted derivatives. - Budget per project, user, lens, and analysis run; provide cancellation and hard caps. - Archive cold sources and rebuild disposable projections from authoritative records. ### 22.4 Portability and offline study - Export a portable study manifest containing metadata, anchors, claims, and links without prohibited media. - Allow fully portable packages only when the grant permits embedded derivatives. - Preserve stable deep links and source identifiers across clients. - Support desktop/local processing for sensitive footage when model and rights policy allow. - Make model-provider replacement possible through versioned adapter contracts. ### 22.5 Observability - Trace every request from UI through orchestrator, domain adapter, model run, and persistence. - Metrics for ingest failures, sync drift, job latency, model quality, rights denials, deletion lag, search relevance, accessibility errors, and cost. - Structured logs that avoid source text, private media URLs, biometric-like features, and learner responses by default. - Per-analysis audit view showing inputs, outputs, versions, reviewers, retries, cost, and policy decisions. - Alerts for stuck deletion, expired access leakage, cross-tenant authorization failures, queue backlog, and quality regression. --- ## 23. Evaluation and Release Gates ### 23.1 Evaluation sets Build versioned, rights-cleared gold sets with film educators, directors, actors, animators, editors, cinematographers, sound designers, costume specialists, game designers, accessibility experts, cultural reviewers, and learners. Evaluation slices must cover: - medium, genre, era, language, culture, acting and animation tradition; - skin tone, age, disability presentation, gender expression, voice type, and body variation; - low light, stylized imagery, occlusion, crowds, cuts, compression, and noisy audio; - game genre, platform, frame rate, latency, camera type, controller, settings, and accessibility modes; - beginner versus expert annotations and legitimate interpretive disagreement; - curated same-function, productive-contrast, bridge-reference, and keep-distinct image-region relationships across works and media; - original-project examples with expert-reviewed source-to-principle-to-decision paths, deliberate contradictions, missing coverage, and source concentration. ### 23.2 Technical metrics - Source identity and edition/build match accuracy. - Shot, scene, beat, speaker, word, sound-event, pose, object, and action boundary precision/recall. - Timecode and telemetry synchronization error. - Tracking stability, region accuracy, pose error, transcript error, and retrieval relevance. - Confidence calibration rather than raw confidence magnitude. - Claim-to-anchor completeness and unsupported-claim rate. - Suggested cross-reference precision, review calibration, keep-distinct accuracy, and explanation sufficiency by relation type. - Source-to-decision path completeness, broken-edge rate, dependency-impact accuracy, and permission leakage through graph traversal. - Search permission leakage rate, which must be zero. - Rights decision and expiry enforcement accuracy. - Deletion completion across all stores. - Job success, retry, latency, cost, and stale-output rates. ### 23.3 Human-centered metrics - Inter-rater agreement where agreement is meaningful, and disagreement coverage where it is not. - Learner ability to distinguish observation from interpretation. - Improvement in source-based analysis and original transfer across attempts. - Teacher-rated usefulness and actionability of feedback. - Time to find, compare, and cite a useful moment. - Time to organize references from several works into a usable, explainable inspiration system and trace a resulting decision back to exact regions. - Ability to discover relevant contrasts and distant analogies rather than only near-duplicate visual references. - Accessibility task completion with assistive technology. - Cultural reviewer assessment of stereotyping and context loss. - Creative-diversity impact: whether recommendations narrow work toward one style. ### 23.4 Product success metrics Release gates measure safety and quality; these measure whether the product works as a product. They are tracked with privacy-safe analytics and never justify weakening a gate. - **Activation:** time from first session to first pinned evidence anchor, and to first completed study card. - **Depth:** weekly active study projects, annotations per returning learner, and the ratio of interpretation-bearing studies to source-only libraries. - **Loop completion:** the share of projects that reach a comparison, an exercise attempt, or a committed creative decision. - **Retention:** returning-learner rate at one, four, and twelve weeks, segmented by persona. - **Transfer:** the share of studies that produce a project transfer, and the reported usefulness of transferred principles. ### 23.5 Mandatory release gates 1. Every displayed analysis can open its authorized evidence anchor. 2. Every machine output exposes model/run/version and review state. 3. Interpretations cannot be presented as detections or creator intent. 4. Restricted rights actions are blocked in playback, processing, search, sharing, and export. 5. Expiry and deletion propagate through originals, derivatives, embeddings, indexes, caches, and exports under the documented service objective. 6. Cross-tenant data leakage tests pass. 7. Private performance and learner data receive the required consent and access controls. 8. Emotion-related output passes bias, calibration, and language-safety evaluation. 9. Instrumented game analysis reports capture gaps and synchronization uncertainty. 10. Keyboard, screen-reader, caption/transcript, contrast, reduced-motion, and zoom automation passes for the critical journey. 11. Search relevance, job reliability, and performance budgets pass on representative data. 12. A source can be studied manually when optional models are unavailable. 13. Practice feedback is evidence-linked, contestable, and does not mandate imitation. 14. Project transfer removes prohibited media and warns on overly specific expression. 15. A user can pin whole images and exact regions from several works, connect them with typed relationships, and traverse every edge back to authorized evidence. 16. Suggested links remain visibly provisional until reviewed, and lookalike entities are not silently merged. 17. Graph and cross-work discovery pass diversity, cultural-context, source-concentration, accessibility, and zero-permission-leakage gates. 18. A committed original-project decision records its principles, alternatives, transformation rationale, source paths, and affected production artifacts. --- ## 24. Delivery Roadmap ### Phase 0 — Decisions and contracts - Approve ownership and route placement through an ADR. - Define source, edition/build, anchor, epistemic, rights, analysis-run, inspiration-item, cross-reference, original-concept, creative-decision, and adapter contracts. - Inventory Aja, Yemaya, Nisaba, Sophia, Hathor, Euterpe, Aglaea, Bellona, Metis, and Isis capabilities against the contracts. - Establish rights policy, private-performance consent, threat model, retention, and evaluation governance. - Build the first rights-cleared gold set and manual annotation guide. **Exit:** Teams can implement independently without creating competing identities or evidence models. ### Phase 1 — Manual-first foundation - Sequence the phase around a named walking-skeleton slice shipped first: one authorized local-file class, the player and hierarchy, manual annotation, one notebook flow, and rights denial, end to end on real persistence, before the remaining Phase 1 surface area is attempted in parallel. - `/studio/study` route, project/source library, professional player, hierarchy, multitrack timeline, manual annotations, rights resolver, notebooks, search, compare tray, project-specific inspiration collections, image-region pinning, manual typed links, accessible list/outline alternatives, and exports. - First-viewing and spoiler-safe study modes as player states (Section 15.6); they are manual UI behavior and need no model support. - Seed the release with exemplar studies and open corpora — Blender open movies and selected open-source games (Section 15.8) — so the first session starts from worked examples rather than an empty library. - Use real persistence and shared identity/permission/audit infrastructure. - Support authorized local files and deep-link sources; do not wait for advanced AI. - Ship deep Playwright coverage for ingest, annotate, compare, pin an image region, create and traverse a typed link, save, rights denial, deletion, keyboard, and screen-reader-critical flows. **Exit:** A learner can complete a valuable film or gameplay-video study without automatic interpretation. ### Phase 2 — Reliable structural analysis - Real metadata probing, proxy generation, transcript alignment, scene/shot suggestion, thumbnails, waveform, speaker turns, basic object/pose tracks, and hybrid search. - Human correction, confidence calibration, model/version audit, reanalysis diff, and gold-set gates. - Explainable visual, semantic, contrast, and function-based relationship suggestions with explicit review and keep-distinct behavior. - Edition and build alignment maps with reviewed anchor migration (Section 9.7), built on the same audio/shot/transcript matching signals. - Reference-board and library importers (PureRef, Milanote, Are.na, Zotero) and the browser clipper, arriving as quarantined user-declared sources. - Replace simulated Aja paths used by the product or explicitly keep them disabled. **Exit:** Automation saves time while every output remains reviewable and source-bound. ### Phase 3 — Film craft lenses and emotion atlas - Performance, camera, animation, narrative, edit, sound, costume, art-direction, and character lenses. - Anger-related atlas with contextual facets, disagreement, blind observation, comparison alignment, and safety constraints. - Commentary-track and paratext alignment as creator-statement evidence (Section 10.15), starting with creator-owned or licensed commentaries. - Nisaba notebooks and Metis practice exercises connected to findings, plus spaced review and perceptual drills reusing Metis's existing schedulers (Section 15.7). **Exit:** The primary filmmaking and performance-learning journey is coherent end to end. ### Phase 4 — Game study - Video-only game study templates and mechanic/level/UI/audio lenses. - Video-only analysis assists: HUD parsing, input-overlay recognition, and community frame-data import as source-documented facts (Section 13.6). - Versioned instrumented-session SDK and at least one first-party game integration. - Input, state, camera, animation, combat, AI, economy, narrative, performance, and accessibility event tracks. - Replay bookmarks and reproducible encounter comparisons. **Exit:** One external game can be studied honestly in video mode and one owned game deeply in instrumented mode. ### Phase 5 — Learning, collaboration, and project transfer - Courses, assignments, rubrics, attempts, teacher review, mastery evidence, portfolios, teams, and publishing. - Live co-study sessions with synchronized group playback, anchored discussion, and crystallization of discussion into reviewed claims. - Outcome-evidence capture and principle track records (Section 14.11), fed by playtest telemetry, screenings, and review sessions. - Original film, game, and world concept graphs; source-to-principle-to-decision paths; cross-work matrices; coverage and consistency views; and dependency impact review. - Source-diversity, missing-perspective, source-concentration, and overly direct mapping warnings that remain advisory and inspectable. - Originality-aware transfer to shot lists, storyboards, character briefs, animation tasks, sound briefs, design documents, and game backlogs. - Mobile review companion and offline note queue if justified by learner research. **Exit:** Study reliably becomes practice and original production work. ### Phase 6 — Advanced analysis and ecosystem - Higher-quality visual, motion, audio, multimodal, causal-comparison, and project-aware analysis after evaluation proves value. - Bridge-reference discovery, user-controlled similarity weighting, productive contrast, corpus clustering, and rights-aware cross-media analogy suggestions. - Approved third-party lens SDK, taxonomy extensions, teaching-pack marketplace, and institutional controls. - Local/private model execution and enterprise data-residency options. **Exit:** The workspace is extensible without weakening evidence, rights, privacy, or quality gates. ### Deliberately excluded from the first release - Automatic universal emotion recognition. - Asset extraction from commercial games. - DRM circumvention or general streaming download. - Fully automatic theme or authorial-intent claims. - Global actor, filmmaker, or game quality scores. - Training generative models on study sources by default. - Unreviewed automatic entity merging, influence claims, cultural equivalence, or one-click generation of a supposedly original world from source material. - A full non-linear editor, DCC, or game engine embedded in the browser. --- ## 25. Second-Pass Gap Audit After the initial ownership and feature assessment, a second pass checked the design against adjacent repository capabilities and common failure modes. The following gaps were added or strengthened as a result. ### 25.1 Ownership gap: Nisaba was initially underrepresented Nisaba is already the accepted first-class domain for source-grounded study, commentary, comparative reading, and notebook continuity. The final design therefore makes Nisaba the durable study substrate while retaining Yemaya as creator-experience owner. This avoids building a second, incompatible research system inside Yemaya. ### 25.2 Rights gap: a simple enum is not a policy system The existing performance library's rights enum does not express authority evidence, territory, expiry, allowed derivatives, model processing, collaboration, export, attribution, or deletion. The proposal adds a full rights grant, resolver, audit, and lifecycle model. ### 25.3 Game gap: footage and engine truth are different Video can show apparent outcomes but not hidden state, exact input, AI decisions, or engine parameters. The proposal adds three explicit tiers and synchronization uncertainty so the UI never presents inferred state as telemetry. ### 25.4 Epistemic gap: emotion must not become mind-reading The initial concept of collecting "true anger" could accidentally create a universal-expression or biometric-truth product. The revised design centers contextual performance study, epistemic labels, human disagreement, behavior-specific language, cultural evaluation, and strict prohibitions on identity and mental-state inference. ### 25.5 Pedagogy gap: analysis alone does not create skill The first concept emphasized inspection. The second pass adds concept graphs, deliberate practice, original attempts, evidence-linked feedback, assessment dimensions, learner challenge, portfolios, and mastery evidence through Metis. ### 25.6 Accessibility gap Dense timelines and visual overlays can exclude learners. The revised scope adds keyboard-first professional playback, screen-reader summaries, captions, transcripts, audio-description notes, non-color encodings, reduced motion, zoom, alternative assessments, and accessible exports. ### 25.7 Cultural and taxonomy gap Craft taxonomies can silently encode one tradition as universal. The proposal now requires taxonomy provenance, language and cultural variants, sourced claims, counter-readings, bias slices, and explicit limitations. ### 25.8 Version and reproducibility gap Films have cuts; games have builds and patches; analyses have model versions. The revised model prevents cross-version collapse and records exact source, configuration, code/model, review, and synchronization provenance. ### 25.9 Privacy gap for private performance and gameplay Rehearsal, audition, classroom, mocap, voice, and gameplay data can be highly sensitive. The proposal adds consent, restricted defaults, sensitive-feature handling, minor protection, access/export/delete rights, and privacy-safe observability. ### 25.10 Anti-copying and transfer gap A reference tool can become a style-copying pipeline if project handoff exports source-specific expression. The revision limits transfer to abstract principles, questions, constraints, and original exercises, with rights and similarity review. ### 25.11 Persistence and deletion gap Several current primitives are in-memory or fixture-backed. The final architecture requires authoritative persistence, durable jobs, immutable history, derivative lifecycle, rebuildable projections, and deletion propagation across object, search, vector, graph, cache, export, and model stores. ### 25.12 Evaluation gap Feature breadth is not evidence of quality. The proposal adds expert and learner gold sets, calibration, retrieval and boundary metrics, disagreement modeling, bias slices, learning outcomes, privacy and rights tests, accessibility automation, and mandatory release gates. ### 25.13 Cost and operability gap Frame-level multimodal processing can be slow and expensive. The revision adds manual-first value, per-lens processing, estimates, tiers, lazy proxies, deduplication boundaries, budgets, cancellation, idempotency, partial failure, tracing, and quality/cost observability. ### 25.14 Interoperability and longevity gap Study records must outlive a particular model or UI. The proposal adds stable identities, versioned contracts, portable manifests, W3C Web Annotation- and IIIF-compatible representations where appropriate, rebuildable indexes, provider-neutral adapters, and exports that remain useful without embedding prohibited source media. ### 25.15 Non-video media gap The original request includes character art, garments, accessories, scripts, storyboards, and fine visual details, while the strongest current reference primitive is video-oriented. The final scope therefore adds document/page, image/canvas/region, storyboard/panel, and creator-owned 3D/scene/asset hierarchies, plus deep zoom and project-aware inspection. This prevents frame extraction from becoming the only way to study visual development or game art. ### 25.16 Inspiration and connectivity gap Comparison, notebooks, and project transfer do not by themselves create an organized inspiration system. The expanded proposal adds evidence-backed inspiration items, typed region-level cross-references, coordinated canvas, matrix, graph, timeline, and notebook views, cross-media functional analogies, original-project concept graphs, and a versioned source-to-decision trail. It also adds contrast, bridge, diversity, coverage, consistency, concentration, and dependency-impact behavior so "similar images" does not become the limit of creative research. ### 25.17 Remaining unknowns The repository audit cannot resolve these without product, legal, and user research: - Which source providers allow the required playback and analysis in target territories? - Are individual learners, schools, studios, or internal teams the first customer? - Which first-party game will provide the initial instrumented integration? - Which two or three craft lenses create enough value for the first paid or strategic release? - What media retention and local-processing promises are required for studios and actors? - Which external annotation standards and NLE/DCC/game-engine interchange formats are mandatory at launch? - What level of teacher moderation is needed for shared study packs? - Which evaluation experts and rights-cleared corpora can be secured before model development? - Which original-project systems and cross-reference types create the most value in the first inspiration workflow: character, environment, world, camera, narrative, sound, mechanic, or a smaller combination? Two of these now carry repository-grounded recommendations rather than fully open questions. V2 is the strongest first-party instrumented candidate because replay primitives and player-behavior heatmaps already exist ([`libs/aphrodite/game-runtime/src/replay`](../../libs/aphrodite/game-runtime/src/replay), [`apps/v2/player-behavior-heatmaps`](../../apps/v2/player-behavior-heatmaps)), and the Blender open movies plus selected open-source games are the natural first rights-cleared corpora (Section 15.8). Both still require owner confirmation. --- ## 26. Decisions Required Before Build 1. **Approve the ownership split:** Yemaya experience, Nisaba study substrate, Sophia evidence substrate, domain-owned lenses. 2. **Approve the canonical shell route:** `/studio/study` versus a nested `/studio/yemaya/study` route. 3. **Choose the first customer:** individual creator learner, classroom, studio team, or internal production. 4. **Choose the first source posture:** local/owned files only, selected provider integrations, or both. 5. **Approve rights policy and legal review workflow.** 6. **Choose the first film lenses:** recommended starting set is playback/annotation, camera, performance, narrative, and sound, with costume and animation closely following. 7. **Choose the first game integration:** one owned title/build with replay and telemetry access. The recommended candidate is V2, whose replay and player-behavior-heatmap primitives already exist in the repository. 8. **Approve the shared anchor and epistemic contracts before implementing analyzers.** 9. **Choose persistence and projection technologies based on measured scale rather than speculative polyglot storage.** 10. **Secure rights-cleared gold sets and expert reviewers.** 11. **Define private/local model execution requirements.** 12. **Approve project-transfer originality policy and blocked export classes.** 13. **Approve the first typed cross-reference vocabulary, review states, and rules for entity identity versus similarity.** 14. **Choose the first original-project concept systems and define which source concentration, diversity, and consistency warnings ship as advisory.** 15. **Choose the collaborative-editing conflict model** for co-annotation, offline note queues, and live co-study sessions — CRDT-based merge versus lock- or lease-based editing — because it shapes persistence, the offline queue, and the live-session design and is expensive to change later. --- ## 27. Definition of Done The first coherent release is complete when a learner can: 1. Create a study project and add an authorized film clip or gameplay capture. 2. See an explicit rights decision and understand what playback, processing, sharing, and export are allowed. 3. Navigate and correct a source hierarchy with frame-accurate playback. 4. Add observations at scene, shot/phase, beat/action, frame/event, and region/entity levels. 5. Run at least the agreed first-release lenses against real media rather than fixture-only data. 6. Inspect every machine result's anchor, confidence, model/run version, and review state. 7. Create an interpretation that is visibly distinct from a detection or observation. 8. Compare several examples with synchronized alignment and counterexamples. 9. Pin whole images and exact regions from multiple works into a project-framed inspiration collection with relevance and do-not-copy notes. 10. Create and review typed connections across image, scene, sound, text, mechanic, principle, and original-concept levels using both visual and non-spatial accessible views. 11. Compare more than eight corpus examples in a matrix while using focused two-to-eight-up synchronized playback where appropriate. 12. Build an original film, game, or world concept system from multiple abstracted principles; inspect coverage, contradictions, missing perspectives, and source concentration. 13. Commit one creative decision whose rationale, alternatives, source-to-principle path, and production backlinks are traversable. 14. Save a Nisaba-backed notebook whose source trail is durable. 15. Turn one finding into an original Metis exercise, submit an attempt, receive evidence-linked feedback, and reflect on it. 16. Transfer an abstracted insight into a Yemaya or game project without exporting prohibited source expression. 17. Complete the critical flow by keyboard and with the defined assistive-technology support. 18. Delete or expire a source and verify that access, derivatives, relationship projections, and affected-decision reviews are handled across every store. 19. Pass rights, privacy, security, epistemic, bias, accessibility, reliability, search, graph traversal, performance, integration, and end-to-end release gates. The broader vision is complete only when the same evidence and learning model works across film, animation, performance, costume, sound, narrative, and both video-only and instrumented game study; connects pictures and concepts from corpus to region to project decision; and does so without hiding the differences between those media. --- ## 28. Prior Art and Competitive Positioning The differentiation claims in Section 2 should be grounded against existing tools rather than asserted. No existing product combines evidence-anchored deconstruction, typed cross-references, rights governance, epistemic labeling, and a practice loop across film and games, but each tool below has proven interaction patterns worth borrowing, and the set directly informs the importer (Section 10.1) and interoperability (Section 19.4) decisions. ### 28.1 Academic and research annotation tools | Tool | What it proves | What to borrow | | --------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | ELAN | Multi-tier, time-aligned annotation is viable for serious AV research | The tier/track model, controlled vocabularies, exportable annotation formats | | ANVIL | Track-based multimodal video annotation with user-defined typed schemes | Per-lens annotation scheme definitions | | VIAN | Film colorimetry and visual-analysis workflows | Palette-over-time views and screenshot-region study ergonomics | | Advene | Hypervideo annotation packages that travel separately from the media | The annotation-package model behind the portable manifest in Section 22.4 | | Lignes de temps | Timeline-first film deconstruction designed for education | The timeline as a primary document rather than a scrub bar | | Cinemetrics | Crowd-sourced shot-length statistics sustain a research community | Shot-rhythm statistics, paired with the qualitative-context caution in Section 10.8 | ### 28.2 Commercial reference and inspiration tools | Tool | What it proves | What this workspace adds beyond it | | ----------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------- | | ShotDeck | Filmmakers pay for large, well-tagged still-frame libraries | Frames anchored to full works, editions, and timecodes instead of floating stills | | Flim | ML visual search over film imagery has real demand | Retrieval explanations, rights state, and evidence anchors on every result | | Frame Set | Curated reference collections are a product, not a feature | Typed relationships and a decision trail instead of flat collections | | PureRef | Frictionless local image boards are the artist's default | Its canvas ergonomics are the bar to meet; provenance and rights are the gap | | Milanote / Are.na | Creatives want connected boards and linked collections | Typed, evidence-backed, reviewable edges instead of untyped links | | StudioBinder | Study output wants to land in production planning documents | A natural interchange target for the shot lists and breakdowns in Section 7.8 | ### 28.3 Game-side references - GDC Vault and developer post-mortems form the richest paratext corpus for the creator-statement features in Section 10.15. - Noclip and similar documentary archives model long-form, creator-consented game study. - Community frame-data wikis and speedrun archives prove that players will build precise mechanical knowledge bases; Section 13.6 imports them as source-documented facts instead of re-measuring them. - Engine replay, profiling, and analytics dashboards — including this repository's own replay and heatmap primitives — cover telemetry capture but not evidence-grounded craft study on top of it. ### 28.4 The combined gap None of the above joins anchored evidence, epistemic labels, a typed relationship graph, rights governance, telemetry-aligned game study, and a practice loop in one system; each covers at most two of those. The positioning consequence is also a posture: the workspace should meet learners where their references already live, by importing their existing boards and libraries (Section 10.1), rather than competing with every tool above for cold-start content. --- ## 29. Repository Evidence ### 29.1 Product and shell decisions - [Oshun Studio information architecture](../adr/ADR-0013-oshun-studio-information-architecture.md) - [Nisaba as a first-class customer domain](../adr/ADR-0054-oshun-nisaba-first-class-customer-domain.md) - [Research-to-practice journey model](../adr/ADR-0059-oshun-research-to-practice-journey-model.md) - [Story-to-source journey model](../adr/ADR-0060-oshun-story-to-source-journey-model.md) - [Sky-to-text journey model](../adr/ADR-0061-oshun-sky-to-text-journey-model.md) ### 29.2 Domain documentation - [Yemaya feature inventory](../domains/yemaya/deep-dive/features.md) - [Hathor feature inventory](../domains/hathor/deep-dive/features.md) - [Aja feature inventory](../domains/aja/deep-dive/features.md) - [Metis domain overview](../domains/metis/README.md) - [Oshun domain features](../domains/oshun/deep-dive/features.md) - [Nisaba feature inventory](../domains/nisaba/deep-dive/features.md) - [Aglaea feature inventory](../domains/aglaea/deep-dive/features.md) - [Euterpe feature inventory](../domains/euterpe/deep-dive/features.md) - [Bellona feature inventory](../domains/bellona/deep-dive/features.md) - [Isis feature inventory](../domains/isis/deep-dive/features.md) ### 29.3 Relevant implementation primitives - [Aja reference-video types](../../apps/aja/svc-reference-video/src/types.ts) - [Aja scene detection](../../apps/aja/svc-reference-video/src/scene-detection.ts) - [Aja metadata extraction](../../apps/aja/svc-reference-video/src/metadata-extraction.ts) - [Yemaya performance reference library](../../libs/yemaya/agents/src/creative/performance-reference-library.ts) - [Yemaya creative analysis agents](../../libs/yemaya/agents/src/creative) - [Sophia timestamp-anchored video transcript adapter](../../libs/sophia/ingestion/src/adapters/video-transcript.ts) - [Metis knowledge tracker](../../libs/metis/adaptive/src/profiling/knowledge-tracker.ts) - [Metis FSRS spaced-repetition scheduler](../../libs/metis/adaptive/src/path/fsrs.ts) - [Shared content-signing library](../../libs/shared/content-signing) - [Nisaba linked-data, Web Annotation, and IIIF primitives](../../libs/nisaba/standards/src/reference-linked-data.ts) - [Aphrodite game replay primitives](../../libs/aphrodite/game-runtime/src/replay) - [V2 player-behavior heatmaps](../../apps/v2/player-behavior-heatmaps) - [Hathor director performance replay Studio panel](../../apps/oshun/web/src/components/studio/StudioHathorDirectorPerformanceReplaySystemPanel.tsx) - [Yemaya animation learning page](../../apps/yemaya/studio-web/src/pages/AnimationLearningPage.tsx) - [Yemaya dailies review page](../../apps/yemaya/studio-web/src/pages/DailiesReviewPage.tsx) --- ## Final Recommendation Proceed with a formal ADR and a manual-first vertical slice in Oshun Studio. Do not begin by trying to automate every craft lens. First establish the shared rights, source-version, evidence-anchor, epistemic, notebook, and analysis-run contracts together with typed cross-reference and original-concept contracts; then ship a professional player, precise annotation, comparison, image-region inspiration, and study-to-practice loop using real persistence. That foundation will make the existing Yemaya, Nisaba, Sophia, Hathor, Aja, Euterpe, Aglaea, Bellona, Metis, and Isis capabilities composable. Without it, adding more analyzers will enlarge the toolkit while leaving the learner's actual workspace fragmented.