Temporal Modes

The Core Insight

Time isn’t one thing. Depending on your use case, “consistency” and “causality” mean very different things:

Standard timeline: Causes must precede effects (FORWARD)
Strategic planning: Reason backward from goals (PORTAL)
Decision analysis: Explore counterfactual branches (BRANCHING)
Mythic narratives: Future constrains past (CYCLICAL)
Story arcs: Dramatic tension drives events (DIRECTORIAL)

Timepoint Pro treats temporal mode as a first-class architectural dimension. Each mode has different validation rules, generation strategies, and output structures.

The Five Modes

FORWARD

Strict forward causality—no anachronisms

PORTAL

Backward inference from fixed endpoints

BRANCHING

Counterfactual timelines from decision points

CYCLICAL

Prophecy, time loops, generational repetition

DIRECTORIAL

Five-act dramatic structure, narrative-driven

Comparison Table

Mode	Causality Model	Best For	Example Template	Cost/Time
FORWARD	Strict forward	Standard timelines	`board_meeting`	$0.15 / 5min
PORTAL	Backward from target	Goal decomposition, critical paths	`mars_mission_portal`	$0.18 / 6min
BRANCHING	Counterfactual branches	”What if” analysis	`castaway_colony_branching`	$0.35 / 12min
CYCLICAL	Future constrains past	Mythic loops, generational sagas	`agent4_elk_migration`	$0.25 / 10min
DIRECTORIAL	Dramatic tension drives	Story arcs, training data	`hound_shadow_directorial`	$0.20 / 8min

FORWARD Mode

Overview

Standard causal DAG: causes precede effects, strict temporal ordering, no time travel.

config = TemporalConfig(
    mode=TemporalMode.FORWARD,
)

Validation Rules

Information Conservation

Entity knowledge state ⊆ exposure history. No magical knowledge acquisition.

Temporal Ordering

Event at T cannot reference information from T+1. Strict ancestry.

Network Flow

Information propagates along relationship edges. No telepathy.

Use Cases

Corporate board meetings
Historical simulations with known timeline
Training data for causal reasoning models
Baseline for comparing other modes

./run.sh run board_meeting

PORTAL Mode

Overview

Backward temporal reasoning: Given a known endpoint (“startup reaches $1B valuation in 2030”) and origin (“founders meet in 2024”), discover plausible paths connecting them.

Architecture

Generate Candidate Antecedents

For each consequent state, generate 3-5 plausible prior states

Score Coherence

Hybrid evaluation: LLM plausibility + historical precedent + causal necessity + entity capability

Validate Forward

Backward-generated paths must make sense when simulated forward

Detect Pivots

Identify key decision points where paths could have diverged

Configuration

config = TemporalConfig(
    mode=TemporalMode.PORTAL,
    portal_description="John Doe elected President in 2040",
    portal_year=2040,
    origin_year=2025,
    backward_steps=15,
    path_count=3,
    preserve_all_paths=True,  # Return all paths, not just top N
)

Exploration Strategies

Strategy	Pattern	Best For
Reverse chronological	2040 → 2039 → 2038 → … → 2025	Simple, predictable scenarios
Oscillating	2040 → 2025 → 2039 → 2026 → 2038 → …	Complex interdependencies
Adaptive	System chooses based on complexity	General-purpose (default)

Entity Inference (2026 Fix)

Portal mode uses LLM-based entity inference to populate entities_present for generated timepoints:

Extract available entities from causal graph
Prompt LLM to identify which entities should be present
Fallback to regex-based name extraction

# Example output
inferred_entities = ["jane_chen", "campaign_manager", "opponent"]
# Based on event: "Heated debate at city council meeting"

Pivot Point Detection

Multi-strategy detection:

Divergence-based
Keyword-based
Event-based
Score-variance

Steps where >30% of paths have unique narratives

Check key_events and entity_changes for significant shifts

Advanced: Simulation-Based Judging

Optional enhancement: Run mini forward simulations from each candidate antecedent, use judge LLM to evaluate plausibility. 2-5x cost increase for significantly better paths.

# Enable simulation judging with quick mode
./run.sh run mars_mission_portal --portal-simjudged-quick

Use Cases

Strategic foresight: Map critical paths to business goals
Decision testing: Identify necessary preconditions for outcomes
Historical analysis: “What had to happen for X to occur?”
Training data: Backward reasoning datasets for causal models

./run.sh run mars_mission_portal --portal-quick

Output Structure

{
  "paths": [
    {
      "path_id": "path_1",
      "coherence_score": 0.847,
      "states": [...],
      "pivot_points": [4, 7, 12],
      "key_divergences": ["funding_secured", "key_hire"]
    }
  ],
  "divergence_analysis": {
    "key_divergence_steps": [4, 5],
    "clusters": {"high_coherence": 2, "medium": 3, "low": 1}
  },
  "total_pivots": 84
}

BRANCHING Mode

Overview

Create alternate timelines from intervention points. Each branch is internally consistent with proper causal propagation.

How It Works

def create_counterfactual_branch(parent_timeline, intervention_point, intervention):
    branch = Timeline(parent_id=parent_timeline.id, branch_point=intervention_point)
    
    # Copy timepoints before intervention
    for tp in parent_timeline.get_timepoints_before(intervention_point):
        branch.add_timepoint(tp.deep_copy())
    
    # Apply intervention
    branch_tp = parent_timeline.get_timepoint(intervention_point).deep_copy()
    apply_intervention(branch_tp, intervention)
    branch.add_timepoint(branch_tp)
    
    # Propagate causal effects forward
    propagate_causal_effects(branch, intervention_point)
    
    return branch

Scenario Anchoring

BRANCHING mode forward steps are anchored to the scenario premise via:

Scenario Anchor Block

First 800 chars of scenario_description injected in every prompt with “do NOT drift” instruction

Entity Roster

Rich role descriptions injected per step to prevent LLM from inventing new characters

Accumulated World State

Persistent store of key_events_history, resource_states, monitoring for running context

Example: Castaway Colony

At Day 7, Commander Tanaka’s decision spawns 3 counterfactual branches:

Branch A: Fortify & Wait
Branch B: Explore & Adapt
Branch C: Repair & Signal

Conservative resource consumption
Focus on shelter and rationing
Risk: slow rescue, low morale
Entities: Commander, Engineer, Doctor (8 total)

Causal Consistency: Branch B can’t use cave shelter discovered in Branch A. Branch C can’t benefit from food sources found in Branch B’s exploration.

Configuration

config = TemporalConfig(
    mode=TemporalMode.BRANCHING,
    branch_points=["day_7_decision"],  # Where to create branches
    interventions=[
        Intervention(type="decision_override", target="commander", 
                    parameters={"choice": "fortify"}),
        Intervention(type="decision_override", target="commander", 
                    parameters={"choice": "explore"}),
        Intervention(type="decision_override", target="commander", 
                    parameters={"choice": "repair"}),
    ]
)

Use Cases

Decision testing: Compare outcomes of different strategies
Risk analysis: Quantify downside of each option
Policy simulation: Test interventions before implementation
Training data: Counterfactual reasoning datasets

./run.sh run castaway_colony_branching
# 8 entities, 16 timepoints, 3 branches
# Cost: ~$0.35, Time: ~12 minutes

CYCLICAL Mode

Overview

Prophecy, time loops, generational repetition. Future events can constrain or cause past events within relaxed causality rules.

The Core Innovation

Cycle type is discovered, not prescribed. The LLM interprets what “cyclical” means for the specific scenario:

Cycle Type	What Repeats	What Changes	Example
repeating	Events, structure	Details, awareness	Groundhog Day loop
spiral	Structural beats	Stakes, intensity	Dynasty saga
causal_loop	Causal structure	Nothing (bootstrap)	Predestination paradox
oscillating	Poles	Magnitude, timing	Boom/bust cycles
composite	LLM-directed	LLM-directed	Mixed patterns

Prophecy System

Prophecies create narrative obligation: either fulfill (destiny) or subvert (tragedy).

config = TemporalConfig(
    mode=TemporalMode.CYCLICAL,
    cycle_length=4,  # Timepoints per cycle
    prophecy_accuracy=0.7,  # How often prophecies come true
)

Prophecy Tracking

prophecy_accuracy: 0.0-1.0 fulfillment rate
fulfillment_confidence: LLM-rated confidence
prophecy_source_cycle: Which cycle generated it

Prophecy Mechanisms

Vary by scenario: witches’ riddles (Macbeth), deja vu (time loop), analyst forecasts (economics), ancestral curses (dynasty)

Causal Loop System

For bootstrap paradoxes where events cause themselves:

Detect Opportunities

“This event could be what caused X in cycle 1”

Enforce Closure

Rewrite states to create explicit causal links

Validate Completion

All opened loops must eventually close

Fidelity Allocation

Position	Fidelity	Why
Cycle boundaries	DIALOG	Where patterns become visible
Prophecy moments	TRAINED	High-stakes narrative pivots
Mid-cycle events	SCENE	Repeating “texture”
Variation points	DIALOG	Where this cycle diverges

Use Cases

Time loop narratives with protagonist evolution
Generational sagas with echoing patterns
Economic/ecological cycles with feedback
Mythic/religious narratives with destiny
Training data for non-linear temporal reasoning

./run.sh run agent4_elk_migration
# 5 paths, 5 cycles, prophecy resolution
# Coherence: 0.727

DIRECTORIAL Mode

Overview

Causality serves narrative, not vice versa. Events happen because the story needs them. Dramatic structure is a first-class constraint.

Arc Engine

Five-act structure with emergent pacing:

Act	Tension	Temporal Density	Fidelity
SETUP	0.2-0.4	Sparse (establishing)	SCENE/TENSOR
RISING	0.4-0.7	Increasing	DIALOG
CLIMAX	0.8-1.0	Dense (every moment matters)	TRAINED
FALLING	0.5-0.3	Decreasing	DIALOG
RESOLUTION	0.1-0.2	Sparse (denouement)	SCENE

Camera System

The “invisible director” controls:

POV Rotation
Framing Vocabulary
Parallel Storylines

Main character for climax
Ensemble for setup
Antagonist for dramatic irony

Dramatic Irony Detection

When audience knows something characters don’t:

# System emphasizes the gap
character_makes_tragic_choice()
  because_they_dont_know(audience_visible_fact)

Fidelity as Dramatic Investment

Resources concentrate where drama concentrates. A 20-timepoint tragedy might allocate 40% of token budget to 3 climax timepoints.

Configuration

config = TemporalConfig(
    mode=TemporalMode.DIRECTORIAL,
    narrative_arc="rising_action",
    dramatic_tension=0.8,
)

Use Cases

Classical dramatic structures (tragedy, comedy, heist, courtroom)
Character-driven vs plot-driven emphasis
Multiple timeline interleaving
Training data for story-aware models

./run.sh run hound_shadow_directorial
# Mystery narrative with dramatic structure

Mode Selection Guide

Need strict causality?

Use FORWARD for corporate, historical, or baseline simulations

Working backward from a goal?

Use PORTAL for strategic planning and critical path analysis

Testing decisions?

Use BRANCHING for counterfactual analysis and risk assessment

Modeling repetition?

Use CYCLICAL for loops, prophecy, or generational patterns

Creating narrative?

Use DIRECTORIAL for story arcs and dramatic training data

Next Steps

Fidelity Management

Learn how resolution levels reduce costs 95%

Knowledge Provenance

Deep dive into exposure events

All 19 Mechanisms

Complete technical reference

Getting Started

Core Concepts

Mechanisms

Guides

Examples

​The Core Insight

​The Five Modes

FORWARD

PORTAL

BRANCHING

CYCLICAL

DIRECTORIAL

​Comparison Table

​FORWARD Mode

​Overview

​Validation Rules

​Use Cases

​PORTAL Mode

​Overview

​Architecture

​Configuration

​Exploration Strategies

​Entity Inference (2026 Fix)

​Pivot Point Detection

​Advanced: Simulation-Based Judging

​Use Cases

​Output Structure

​BRANCHING Mode

​Overview

​How It Works

​Scenario Anchoring

​Example: Castaway Colony

​Configuration

​Use Cases

​CYCLICAL Mode

​Overview

​The Core Innovation

​Prophecy System

​Causal Loop System

​Fidelity Allocation

​Use Cases

​DIRECTORIAL Mode

​Overview

​Arc Engine

​Camera System

​Dramatic Irony Detection

​Fidelity as Dramatic Investment

​Configuration

​Use Cases

​Mode Selection Guide

Need strict causality?

Working backward from a goal?

Testing decisions?

Modeling repetition?

Creating narrative?

​Next Steps

Fidelity Management

Knowledge Provenance

All 19 Mechanisms

Build docs developers (and LLMs) love

The Core Insight

The Five Modes

Comparison Table

FORWARD Mode

Overview

Validation Rules

Use Cases

PORTAL Mode

Overview

Architecture

Configuration

Exploration Strategies

Entity Inference (2026 Fix)

Pivot Point Detection

Advanced: Simulation-Based Judging

Use Cases

Output Structure

BRANCHING Mode

Overview

How It Works

Scenario Anchoring

Example: Castaway Colony

Configuration

Use Cases

CYCLICAL Mode

Overview

The Core Innovation

Prophecy System

Causal Loop System

Fidelity Allocation

Use Cases

DIRECTORIAL Mode

Overview

Arc Engine

Camera System

Dramatic Irony Detection

Fidelity as Dramatic Investment

Configuration

Use Cases

Mode Selection Guide

Next Steps