Keep run and window summaries out of the AiRequest store

[jaywedgeworth22]

Summary

Restricts the AiRequest per-request store (UM-1592 ingest path) to events that describe a single model call. Run and window summaries are still ingested, aggregated, and priced, but they no longer create an AiRequest row — so a run or window total duration cannot be misinterpreted as one request's duration.

What changed

• src/lib/ai-usage-metadata.ts

  • Extends AiRequestSourceEvent with optional requests, windowStart, and windowEnd fields.
  • aiRequestFromUsageEvent now returns null (no AiRequest row) when:
    • requests is present and not equal to 1 (e.g. 0 or 12), or
    • a windowStart / windowEnd is provided.
  • Events with no requests value keep the previous behavior, preserving backward compatibility for existing single-call producers.

• src/app/api/ingest/usage/route.ts

  • Carries requests, windowStart, and windowEnd through persistIngestAiRequests into the event passed to the mapping, so the new eligibility rule applies on the ingest path.
  • Updates the surrounding comment to state that only single-call events land in the per-request store.

• docs/api-contract.md

  • Documents the rule: an event with the typed ai block creates one AiRequest row only when it is a single call (requests absent or 1, no window). Run/window summaries must set requests to their call count (or 0) or provide the window so their duration is not read as a single request.

• src/lib/__tests__/ai-usage-metadata.test.ts

  • Adds a test confirming requests: 1 produces a row while requests: 0, requests: 12, windowStart, and windowEnd do not.

Functional impact

• The usage event remains the record of truth; only the derived per-request AiRequest row is suppressed for aggregate events.
• Single-call producers are unaffected.
• Consumers of the AiRequest store no longer see run or window totals misclassified as individual requests.

Test coverage

New unit coverage in ai-usage-metadata.test.ts exercises the single-call vs. summary boundaries.

Review note

The automated review flagged that the business/eligibility rules are not fully described in the task context. The intended behavior is captured in docs/api-contract.md; reviewers should confirm the contract doc reflects the agreed product rules for what qualifies as a single request.

[linear-code]

UM-1592

[kody-ai]

Kody Review Complete

Great news! 🎉
No issues were found that match your current review configurations.

Keep up the excellent work! 🚀

Kody Guide: Usage and Configuration

Interacting with Kody

• Request a Review: Ask Kody to review your PR manually by adding a comment with the @kody start-review command at the root of your PR.

• Validate Business Logic: Ask Kody to validate your code against business rules by adding a comment with the @kody -v business-logic command.

• Provide Feedback: Help Kody learn and improve by reacting to its comments with a 👍 for helpful suggestions or a 👎 if improvements are needed.

Current Kody Configuration

Review Options

The following review options are enabled or disabled:

Options	Enabled
Bug	✅
Performance	✅
Security	✅
Business Logic	✅

Access your configuration settings here.

​

[kody-ai]

🤔 Insufficient Task Context

I found a task linked to this PR, but it only contains minimal information (title only, no description or acceptance criteria). To perform a meaningful business rules validation, I need more details.

🔍 What I need to validate:

• Business requirements and acceptance criteria
• Expected behavior and business rules
• Edge cases and constraints to consider

💡 How to improve the task context:

• Add a description to the linked ticket
• Include acceptance criteria or business rules
• Describe the expected behavior after the change

⚠️ Important:

A task title alone is not sufficient to determine whether the implementation is correct or complete.

---

💡 This validation runs automatically only on the first review of a pull request. To run it again, comment @kody -v business-logic.