Add Server-Timing response headers

[karangoel16]

SEP: Add Server-Timing Response Headers

📋 SEP Metadata

• SEP Number: SEP Proposal: Add Server-Timing response headers #274 - SEP Proposal: Add Server-Timing response headers #274
• Author(s): Karan Goel / Meta
• Status: proposal (awaiting sponsor)
• Type: [x] Major Change [ ] Process Change
• Related Issues/RFCs: Related UCP PRs: docs: add server timing response header Universal-Commerce-Protocol/ucp#547, docs: add catalog REST headers section Universal-Commerce-Protocol/ucp#548

---

🎯 Abstract

This proposal adds optional Server-Timing response headers across ACP REST OpenAPI 2xx responses and documents the behavior in the relevant RFCs. Implementations may use the W3C Server-Timing header to report business/server-side processing duration with the acp metric and dur in milliseconds, for example Server-Timing: acp;dur=42.3.

The header is informational only. It excludes network time, does not alter response semantics, and does not replace client-observed latency measurement. Clients and platforms should continue to measure end-to-end latency independently.

---

💡 Motivation

ACP currently defines several protocol-level request and response headers, but it does not provide a standard way for servers to report processing duration. UCP recently added equivalent optional Server-Timing guidance. Aligning ACP gives agents and platforms a consistent, standards-based signal for separating server processing time from client-observed latency during checkout, cart, feed, payment, authentication, and webhook flows.

Without a shared convention, implementers may use proprietary timing headers, inconsistent metric names, or omit server-side timing entirely, making latency analysis harder across integrations.

---

📐 Specification

ACP REST responses MAY include the W3C Server-Timing header on successful 2xx responses.

When present, ACP responses SHOULD use:

Server-Timing: acp;dur=42.3

Where:

• acp is the metric name.
• dur is server processing duration in milliseconds.
• The value excludes network time.
• The value is informational; callers SHOULD measure client-observed latency independently.

This PR updates:

• spec/unreleased/openapi/openapi.agentic_checkout.yaml
• spec/unreleased/openapi/openapi.agentic_checkout_webhook.yaml
• spec/unreleased/openapi/openapi.cart.yaml
• spec/unreleased/openapi/openapi.delegate_authentication.yaml
• spec/unreleased/openapi/openapi.delegate_payment.yaml
• spec/unreleased/openapi/openapi.feed.yaml
• RFC guidance for checkout, cart, delegate authentication, delegate payment, and product feeds
• changelog/unreleased/add-server-timing-header.md

---

🤔 Rationale

Server-Timing is a standard HTTP response header, so ACP does not need a custom timing field or proprietary header. Keeping the header optional avoids imposing runtime instrumentation requirements on existing implementations. Using a single acp metric keeps the convention simple and mirrors the approach used in UCP, while avoiding protocol-specific endpoint metric proliferation in the base spec.

The proposal intentionally does not make the header required, does not define SLA semantics, and does not treat this value as authoritative for user-visible latency.

---

🔄 Backward Compatibility

This is additive and backward compatible.

• Existing clients can ignore unknown response headers.
• Existing servers do not need to emit Server-Timing.
• No request or response body schemas are changed.
• No deprecation or migration timeline is required.

---

🛠️ Reference Implementation

No runtime reference implementation is included. This PR updates the protocol OpenAPI and RFC documentation only.

---

🔒 Security Implications

The header may expose approximate server processing duration. Implementers should avoid putting sensitive internal system names, topology, query names, or vendor-specific details in the metric. This proposal recommends only the generic acp metric with a duration value.

The header does not affect authentication, authorization, signing, payment handling, or user data processing.

---

✅ Pre-Submission Checklist

• I have created a GitHub Issue for this SEP proposal (SEP Proposal: Add Server-Timing response headers #274; repo does not currently have SEP/proposal labels)
• I have linked the SEP issue number above
• I have discussed this proposal in the community (Discord/GitHub Discussions)
• I have signed the Contributor License Agreement (CLA)
• This PR includes updates to OpenAPI/JSON schemas (if applicable)
• This PR includes example requests/responses (if applicable)
• This PR includes a changelog entry file in changelog/unreleased/your-change-description.md
• I am seeking or have found a sponsor (Founding Maintainer)

---

📚 Additional Context

Validation run locally:

• Ruby YAML parse for all spec/unreleased/openapi/*.yaml
• Structural check that all unreleased OpenAPI 2xx responses include Server-Timing
• git diff --check

pnpm validate:consistency could not be run locally because pnpm/corepack are not installed in this environment.

---

🙋 Questions for Reviewers

• Should this be accepted as a SEP-level protocol addition, or reclassified as a minor additive documentation/spec clarification?
• Should the base metric name be acp, or should each API surface define a more specific metric name?
• Should ACP include examples with Server-Timing headers in examples/unreleased/, or is OpenAPI/RFC documentation sufficient for an optional response header?

[CLAassistant]

All committers have signed the CLA.