Battle Execution Paths

LenserFight has two distinct execution surfaces for running AI battles. Understanding which path is active for a given battle type is critical for debugging and extending the system.

---

Surface 1 — Direct Worker Path

Entry point: apps/worker/src/worker/battle-worker.ts

When it runs: For all battle_execution_jobs rows pulled from battles.battle_execution_jobs. The worker polls via fn_worker_claim_battle_job() on a configurable interval.

Job lifecycle:

queued → claimed → [running] → completed
                              → failed → (retry via fn_requeue_battle_job_with_backoff)
                                       → DLQ (fn_move_battle_job_to_dlq after max retries)

Execution branches:

Model kind	Function called	Submission columns
text	callProvider()	content_text, output_modality: 'text'
image	callGenerativeMedia('image')	media_url, mime_type, output_modality: 'image', is_final: true
audio	callGenerativeMedia('audio')	media_url, mime_type, output_modality: 'audio', is_final: true
video	callGenerativeMedia('video')	artifact_id (task ID), output_modality: 'video', is_final: false
music	callGenerativeMedia('audio')	artifact_id (task ID), output_modality: 'audio', is_final: false

Model kind is resolved via modelKind(job.model_key) from @lenserfight/providers.

Async media (video/music): artifact_id stores the provider's task ID. The poll-async-executions edge function (scheduled via pg_cron) polls until the URL is available and updates is_final: true.

Submissions constraint: battles.submissions requires status='pending' OR content_text IS NOT NULL OR content_url IS NOT NULL. The fn_worker_upsert_battle_submission SQL function mirrors media_url into content_url to satisfy this constraint.

---

Surface 2 — DAG Runner Path

Entry point: libs/infra/execution/src/lib/ (WorkflowExecutionService)

When it runs: For workflow-composed battles where the battle nodes are part of a user-authored workflow graph.

Runner registry dispatch: getNodeRunner(nodeType) looks up the INodeRunner for each node type. registerDefaultNodeRunners() registers all built-in runners at startup.

Battle node types and their runners:

Node type	Runner	Responsibility
battle_create	BattleCreateRunner	Emits __battle_create_request envelope; app layer creates the battle
battle_execute	BattleExecuteRunner	GRASP Controller: validates battleId, collects upstream contender outputs
contender_run	ContenderRunRunner	Executes one AI slot via ctx.executeProvider
judge_battle	JudgeBattleRunner	POSTs to ai-judge-battle edge function
vote_collector	VoteCollectorRunner	Reads vote tallies from fn_battle_scores
score_aggregator	ScoreAggregatorRunner	Calls fn_battles_finalize to close battle + update ELO
leaderboard_update	LeaderboardUpdateRunner	Calls fn_compute_elo_after_battle (idempotent follow-up)

Media node types:

Node type	Runner	Output mediaType
text_to_image	TextToImageRunner	image
text_to_speech	TextToSpeechRunner	audio
text_to_video	TextToVideoRunner	video
image_to_image	ImageToImageRunner	image
speech_to_text	SpeechToTextRunner	text
image_to_audio	ImageToAudioRunner	audio
image_upscale	ImageUpscaleRunner	image
media_convert	MediaConvertRunner	throws (not yet wired)

Context interface key fields:

• ctx.resolvedPrompt — template-rendered prompt (engine fills this before calling runner)
• ctx.executeProvider — closed-over (input: ExecutionInput) => Promise<ExecutionResult> for this node's model
• ctx.upstreamOutputs — ReadonlyMap<nodeId, ExecutionResult> from upstream nodes
• ctx.nodeConfig — per-node canvas configuration

---

Funding Source Resolution

Both paths resolve API keys via the same byokKeyResolver:

1. Check job.byok_key_ref_id — user-provided BYOK key from lensers.byok_api_keys
2. Fall back to platform key for the provider

---

Status Transitions (DB-owned)

Battle status transitions are owned by the DB RPCs, not the runners:

draft → published → executing → voting → scoring → closed

• executing → voting: triggered when all submissions are present (fn_worker_complete_battle_job)
• voting → scoring: triggered by vote deadline CRON or fn_auto_finalize_battles
• scoring → closed: triggered by fn_battles_finalize or ai-judge-battle edge function

---

Handicap Enforcement

enforceHandicap(params, handicapConfig) in libs/domain/battle-governance clamps max_tokens to max_context_tokens and enforces allowed_model_tier. Apply before provider calls in both execution surfaces.