byoc: per-job balance keying — design discussion

[rickstaa]

Context

While reviewing #3869, the BYOC payment accounting model surfaced a structural concern: balances are keyed by (sender_address, capability_id) rather than per-job/per-stream. Effects:

• Multiple concurrent jobs from the same sender for the same capability share one balance pool.
• The orchestrator can't manage admission for individual jobs based on payment state — only aggregate sender balance for that capability.
• Remote signers (clearinghouse signing on behalf of multiple downstream customers) collapse all customer balances into one bucket, so per-customer billing has to be reconstructed out-of-band.

LiveAI explicitly works around this — server/ai_process.go calls clearSessionBalance(sess, RandomManifestID()) per stream to force per-session isolation in the existing AddressBalances map. BYOC inherited the per-capability pattern without that band-aid.

What this PR does

Switches the ManifestID used for balance keying from capability to JobRequest.ID across the BYOC orch + gateway:

Orchestrator

• processJob, monitorOrchStream, ProcessStreamPayment, confirmPayment, processPayment, chargeForCompute, getPaymentBalance all key Balance/DebitFees/ProcessPayment on jobReq.ID.
• confirmPayment/processPayment take both jobID (balance) and capability (capacity-slot management) since the two concerns are now distinct.
• GetJobToken accepts an optional Livepeer-Job-Id header. Initial token requests (no job context) return balance=0; refresh calls for an existing job/stream pass the ID and get the per-job balance.

Gateway

• createPayment, updateGatewayBalance, getToken thread jobID.
• sendPaymentForStream sets req.ID = streamID so the orch matches per-stream payments.

Capacity-management call sites (FreeExternalCapabilityCapacity, RemoveExternalCapability, worker routing) still use Capability — those are scheduling, not money.

Stacked on #3906 to keep the diff scoped to the refactor.

The genuine question for the author

@eliteprox — before going further, I'd like to understand the reasoning behind sender+capability keying. Reasons it might have been intentional:

1. PM session alignment. One pm.Sender.StartSession() produces tickets for many jobs. Capability-keyed balance lets one PM session feed one balance bucket cleanly. Per-job keying creates a many-to-one routing question on ticket payout that this PR doesn't yet solve.
2. Prepaid-credit mental model. "User buys $X of compute for capability Y, spends across many requests" maps cleanly to capability balance.
3. First-token discovery info. The capability balance returned in the initial token response was a useful signal for the gateway. Per-job balance is always 0 there.
4. Bounded key cardinality. (senders × capabilities) is bounded. (senders × job_ids) grows unbounded — every completed job leaves a dust balance that needs GC.
5. Residual carry-over. User does job A, gateway crashes mid-flow, user submits job B with same capability — capability-keyed model preserves leftover credit. Per-job keying strands it.

If any of these were primary drivers, this refactor needs to address them rather than ignore them. If the original choice was inherited from the pre-existing AI-jobs pattern without explicit consideration of streams or remote signers, the trade-offs above are mostly recoverable.

Out of scope (deferred)

• Per-job PM session reset. LiveAI calls clearSessionBalance per stream to avoid ticket nonce reuse. BYOC still calls Sender.StartSession() once per createPayment. If we go per-job balance, per-job PM sessions likely need to follow.
• Test suite update. TestGetJobToken_Success now correctly returns 0 (no jobID provided) and the test asserts the legacy 1000. Other tests in payment_test.go / job_orchestrator_test.go / stream_test.go still assume capability-keyed balance. Left so the diff is reviewable as a design question first.
• Backward compat. No wire-format change, but old gateways/orchs talking to new ones will create capability-keyed balances the new code never reads. Coordinate-deploy or fall-through-during-deprecation needs deciding.
• Dust-balance GC. Per-job keying leaves orphan balances after job completion.

Status

Draft. Builds clean (go build ./...). One test fails intentionally to document the behavior change. Not ready to merge — raising for design discussion before investing in the test pass and PM session refactor.