convex/runs.ts

Purpose

Realtime ingestion and read APIs for LLM runs in runs_live.

Public Surface

• ingestRun({ projectId, payload }) => { id }
• ingestRuns({ projectId, payloads }) => { ids }
• listRuns({ projectId, sinceMs }) => Doc[]
• listRunsByOrganization({ organizationId, sinceMs }) => Doc[]
• getById({ runId }) => Doc | null
• markSynced({ runId }): internal

Behavior & Invariants

• Idempotent insert by payload.runId (checked via by_run_id).
• Truncates promptPreview to 160 chars.
• Schedules internal sync action after insert.
• listRuns* caps total to 500.

Dependencies

• Depends on: schema.ts tables; runsActions.internalSyncToPg.
• Used by: API /api/ingest and UI pages (runs, dashboard).

Error Handling

• Duplicate run IDs return existing ID without mutation.

Configuration & Flags

• None directly; sync action depends on RUNFORGE_SYNC_URL/RUNFORGE_SYNC_SIGN.

Example Usage

await convex.mutation(api.runs.ingestRun, { projectId, payload })

TODO / Technical Debt

• Add TTL cleanup for runs_live.
• Consider pagination for listRuns.