# 02 — Media Ontology and Graph

## 1. Why a graph is required

A folder can tell you where a file is. It cannot reliably tell you:

- which question a sentence answers;
- which claim a chart proves;
- which reaction belongs to a confession;
- which B-roll can cover a jump cut;
- which earlier premise a short clip requires;
- which generated shot is an alternative to a real shot;
- which change will break continuity downstream.

The system therefore uses both:

1. **A time graph** for order, duration, overlap, and synchronization.
2. **A meaning graph** for cause, support, contradiction, reference, setup, and payoff.

## 2. Object hierarchy

```text
Project
└── Series
    └── Episode
        ├── Source
        │   ├── Track
        │   ├── Shot
        │   ├── SoundEvent
        │   └── TranscriptUnit
        ├── TopicSegment
        │   ├── Proposition
        │   ├── Claim
        │   ├── Exchange
        │   └── ClipCandidate
        ├── Story
        │   ├── Act
        │   ├── Sequence
        │   ├── Scene
        │   └── Beat
        ├── Asset
        │   ├── Graphic
        │   ├── GeneratedShot
        │   ├── MusicCue
        │   ├── SFX
        │   └── CaptionCue
        ├── Timeline
        │   ├── Track
        │   ├── TimelineItem
        │   ├── Transition
        │   └── Marker
        └── Version
            ├── DeliveryProfile
            ├── Render
            └── QAReport
```

## 3. Universal object fields

Every object has:

```json
{
  "id": "typed_unique_id",
  "type": "clip|beat|shot|claim|graphic|...",
  "project_id": "project_id",
  "source_ids": [],
  "created_at": "ISO-8601",
  "created_by": "human_or_agent_id",
  "status": "draft|review|approved|rejected|published",
  "confidence": 0.0,
  "provenance": {},
  "rights": {},
  "tags": [],
  "notes": [],
  "version": 1
}
```

Time-based objects add:

```json
{
  "source_range": {"start": 0.0, "end": 0.0},
  "output_range": {"start": 0.0, "end": 0.0},
  "handles": {"pre": 1.0, "post": 1.0}
}
```

## 4. Edge types

### Temporal edges

| Edge | Meaning |
|---|---|
| `PRECEDES` | A occurs before B |
| `FOLLOWS` | A occurs after B |
| `OVERLAPS` | A and B coexist |
| `CONTAINS` | A temporally contains B |
| `SYNCHRONIZED_WITH` | A aligns with B |
| `ALTERNATE_TAKE_OF` | Same intended event or line |
| `COVERAGE_OF` | Different visual view of the same beat |

### Semantic edges

| Edge | Meaning |
|---|---|
| `REFERS_TO` | Pronoun, phrase, or visual refers to another object |
| `DEFINES` | A defines B |
| `ELABORATES` | A adds detail to B |
| `EXEMPLIFIES` | A is an example of B |
| `SUPPORTS` | A increases confidence in B |
| `CONTRADICTS` | A conflicts with B |
| `QUALIFIES` | A limits or conditions B |
| `CAUSES` | A is presented as causing B |
| `ENABLES` | A makes B possible |
| `PREVENTS` | A blocks B |
| `ANSWERS` | A answers B |
| `QUESTIONS` | A raises uncertainty about B |
| `SUMMARIZES` | A compresses B |
| `TRANSLATES` | A restates B in another language or form |

### Narrative edges

| Edge | Meaning |
|---|---|
| `SETS_UP` | A creates an expectation paid by B |
| `PAYS_OFF` | B resolves or transforms A |
| `ESCALATES` | B increases pressure introduced by A |
| `REVERSES` | B changes interpretation of A |
| `CALLS_BACK_TO` | B deliberately recalls A |
| `FORESHADOWS` | A hints at B |
| `REVEALS` | A makes hidden information available |
| `MOTIVATES` | A gives a character or audience reason for B |
| `RESOLVES` | B closes a question, conflict, or loop |
| `BRIDGES` | A enables transition between otherwise disconnected objects |

### Production edges

| Edge | Meaning |
|---|---|
| `VISUALIZES` | Shot or graphic represents a proposition or beat |
| `SONIFIES` | Sound represents or amplifies a beat |
| `COVERS_EDIT` | Asset hides or motivates an edit |
| `REQUIRES` | A cannot function without B |
| `CONSTRAINS` | A limits possible states of B |
| `GENERATED_FROM` | Synthetic object derives from prompt/reference |
| `DERIVED_FROM` | Version derives from semantic timeline |
| `REPLACES` | A substitutes for B |
| `APPROVED_BY` | Human or policy gate approved A |
| `FLAGGED_BY` | QA process identified a concern |

## 5. Story graph versus timeline

The **story graph** is non-linear and represents meaning.  
The **timeline** is linear and represents presentation.

One story graph can create many timelines:

```text
long interview
→ 60-minute episode
→ 12-minute thematic cut
→ 90-second trailer
→ 30-second vertical insight
→ audio-only episode
→ article and infographic
```

## 6. Semantic timeline

The semantic timeline is the authoritative edit description.

```json
{
  "timeline_id": "tl_main",
  "story_id": "story_01",
  "items": [
    {
      "beat_id": "beat_hook",
      "clip_id": "clip_004",
      "story_function": "hook",
      "source_range": {"start": 132.4, "end": 146.2},
      "output_duration": 13.8,
      "visual_plan_id": "visual_hook",
      "audio_plan_id": "audio_hook",
      "graphic_plan_id": null
    }
  ]
}
```

Rendered timelines for an NLE, web player, vertical crop, or audio-only version are derived from this semantic representation.

## 7. Context dependency graph

A clip can depend on:

- a named person;
- a prior definition;
- an earlier question;
- a stated time or place;
- a qualifying clause;
- a visible object;
- a source or chart;
- an emotional setup;
- a later resolution.

The dependency graph supports a completeness test:

```text
IF required dependency is absent
THEN expand clip boundary
OR add contextual bridge
OR add text/voice-over
OR reject standalone use
```

## 8. Provenance object

```json
{
  "origin_type": "camera|archive|screen_recording|generated|licensed|user_upload",
  "origin_uri": "internal_asset_reference",
  "capture_time": null,
  "creator": null,
  "model": null,
  "prompt_id": null,
  "reference_asset_ids": [],
  "modifications": [],
  "content_credentials": null,
  "disclosure_required": false
}
```

## 9. Rights object

```json
{
  "owner": null,
  "license": null,
  "territories": [],
  "start_date": null,
  "end_date": null,
  "allowed_uses": [],
  "likeness_consent": null,
  "music_clearance": null,
  "restrictions": [],
  "review_required": false
}
```

## 10. State machine

```text
IMPORTED
→ ANALYZED
→ SEGMENTED
→ CONTEXT_RESOLVED
→ CANDIDATE
→ SELECTED
→ PLANNED
→ ASSEMBLED
→ FINISHED
→ QA_PASSED
→ APPROVED
→ PUBLISHED
```

Any state can move to `FLAGGED`, `REJECTED`, or `NEEDS_REVISION`. Published objects remain versioned rather than overwritten.