refactor(runtime): converge AgentRun metadata into the RuntimeInvocation event spine #4311

Problem

Maka currently represents one physical runtime attempt through overlapping durable identities and ledgers:

• RuntimeEvent is the canonical execution and model-history fact.
• AgentRunHeader is a mutable per-run record containing route, configuration, lineage, and lifecycle projection state.
• AgentRunEvent is a separate append-only operational ledger containing lifecycle, provider-attempt, accounting, checkpoint, permission, and diagnostic records.
• Phase 0–3 define one invocationId per runId; production construction commonly sets them to the same value.

This was a reasonable migration shape: AgentRun first extracted one execution from SessionManager and supplied durable recovery metadata; Runtime v2 then introduced RuntimeEvent as the canonical fact model without a flag-day storage migration. The transition is now incomplete.

PR #4286 exposed the cost directly. Provider-owned reasoning lives on RuntimeEvent, but its source route is resolved through event.runId -> AgentRunHeader. Every normal, continuation, compaction, overflow, and durable-reload exit therefore has to carry both records. One missing Header path deterministically removed compatible reasoning from provider requests even though the durable replay boundary had admitted it.

Renaming AgentRun or AgentRunHeader would preserve that split. The goal is to remove the duplicate authority, not give it a new noun.

Target authority model

Session
  -> RuntimeInvocation
       -> immutable run-opening fact
       -> RuntimeEvent[]
       -> one terminal RuntimeEvent
       -> rebuildable RuntimeInvocationIndex

• sessionId identifies the conversation.
• turnId identifies the user-semantic turn.
• invocationId identifies one physical execution attempt.
• Runtime events hold immutable execution facts.
• One opening fact holds invocation-scoped metadata once; route/configuration is not copied to every event.
• The terminal RuntimeEvent is the lifecycle outcome authority.
• Any index used for enumeration or query is rebuildable and has no independent semantic writer.

The current AgentRun in-memory object may remain as the live execution owner during migration. Its eventual naming or decomposition follows responsibility; it is not a reason to retain a durable AgentRunHeader authority.

Migration workstreams

1. Define the invocation opening fact and derived index contract

• Classify every current AgentRunHeader field as immutable opening metadata, RuntimeEvent-derived terminal state, dedicated control-plane authority, operational diagnostic, or legacy-only data.
• Define one closed, versioned invocation-opening fact committed before provider/tool dispatch.
• Define the rebuildable RuntimeInvocationIndex required for session enumeration and indexed lookups.
• Prove whether runId and invocationId remain exactly one-to-one across supported current writers, recovery, continuation, copy/import, and persisted data. Do not collapse them on naming preference alone.

2. Make new executions event-first

• Commit the opening fact before the first provider/tool side effect.
• Derive route, configuration, lineage, and lifecycle reads from opening/terminal facts through the index.
• Keep compatibility reading for legacy Header-only runs behind one bounded migration seam; do not create permanent dual-write authority.
• Make index repair/rebuild deterministic and crash safe.

3. Move consumers off independent Header semantics

• Migrate replay provenance, continuation/recovery admission, session/graph inspection, copy/import, checkpoint lookup, and execution diagnostics to the canonical invocation facts plus derived index.
• Classify AgentRunEvent writers individually. Move duplicated lifecycle/tool/permission facts to their canonical owners; retain metering, request-attempt, checkpoint, and diagnostic facts only where they have an independent operational demand.
• Do not funnel unrelated accounting or control-plane state into model-history RuntimeEvents merely to reduce table count.

4. Retire the old authority

• Stop current production writers from independently creating or mutating AgentRunHeader semantic state.
• Remove legacy Header reads after the declared compatibility window and verified migration/rebuild coverage.
• Remove the old Header storage surface and any AgentRun lifecycle events made redundant by canonical RuntimeEvents.
• If workstream 1 proves runId and invocationId are the same supported identity, converge on invocationId; otherwise document and encode the real multiplicity before retaining both.
• Rename or fold the live AgentRun executor only after its durable meaning has disappeared; avoid a mechanical SingleRun rename.

Invariants

• No provider or tool dispatch occurs before a durable invocation-opening fact when durability is required.
• Route provenance is recorded once per invocation and can be joined to every event without copying it onto each event.
• Terminal lifecycle state is derived from the terminal RuntimeEvent and cannot disagree with an independently written Header.
• Clearing the derived invocation index and rebuilding from canonical facts produces the same current-session run inventory and replay provenance.
• Continuation, recovery, compaction, overflow retry, restart, copy/branch, and inspection do not require a parallel Header authority.
• Legacy data fails closed where provenance is missing but retains portable transcript and tool evidence.
• The migration has a defined end state; no permanent old/new dual read or dual write remains.

Non-goals

• Expanding PR fix(runtime): gate provider reasoning replay by source model #4286 beyond its provider-replay correctness fix.
• Copying connection/model metadata into every RuntimeEvent or provider option.
• Rewriting ToolRuntime, provider model loops, or AI SDK converters.
• Combining all operational telemetry, accounting, and model-history facts into one untyped event catalogue.
• Renaming AgentRun to SingleRun without deleting an authority or identity.

Done

• Invocation-opening fact and rebuildable index contract are accepted.
• New executions no longer require independent Header semantic writes.
• All current consumers read canonical invocation facts or the derived index.
• Legacy migration/compatibility window is complete and verified.
• Independent AgentRunHeader authority is removed.
• runId and invocationId are either converged or retained with proven distinct semantics.

Related: #4283, #4286.