# Audience-explicit Message Fields

<!-- auto-oncall-optimization-record
{
  "schemaVersion": "auto-oncall-optimization-record-v1",
  "optimizationId": "audience-explicit-message-fields-2026-08-13",
  "problems": [
    {
      "problemId": "response-field-names-hide-customer-internal-audience",
      "summary": "The canonical customer and internal response fields used implementation-history names that did not identify their audience, making prompt, API, and consumer mistakes harder to notice.",
      "status": "candidate",
      "applicability": "Final Response production and every runtime, replay, evaluation, Jira, and optimizer consumer of the paired customer and internal messages.",
      "issueKeys": ["APID-29338"],
      "sourceRefs": [
        "https://tidb.atlassian.net/browse/APID-29338#problem:response-field-names-hide-customer-internal-audience"
      ],
      "signalTextIncludesAny": [
        "commentDraftMarkdown does not identify the customer audience",
        "replayContextMarkdown does not identify the internal audience",
        "customer and internal response fields are easy to confuse"
      ],
      "observedThrough": "2026-08-13",
      "effectiveAt": null,
      "verifiedAt": null,
      "attemptedAction": "Rename the canonical pair to customerReplyMarkdown and internalHandoffMarkdown across Agent schemas, runtime objects, API responses, artifacts, evaluation, and optimizer context; keep historical names read-only and preserve existing answer fingerprints.",
      "evidenceUrl": "https://tidb.atlassian.net/browse/APID-29338"
    }
  ]
}
-->

- Optimization ID: `audience-explicit-message-fields-2026-08-13`
- Owner: Final Response paired-message contract and consumers
- Source reference: APID-29338 audience-boundary review
- Implementation status: implemented and verified locally; not deployed
- Effective status: `candidate`

## Bounded problem

`commentDraftMarkdown` and `replayContextMarkdown` described historical uses,
not audiences. A producer or reviewer could not tell from the names alone which
field was safe for customers and which field carried Support-only details.

## Candidate change

- Use `customerReplyMarkdown` and `internalHandoffMarkdown` as the only new
  canonical fields.
- Remove emitted compatibility aliases and rename workspace artifacts to
  `customer-reply.md` and `internal-handoff.md`.
- Read historical names only at explicit compatibility boundaries.
- Keep the historical fingerprint serialization stable so unchanged message
  text remains the same answer version.

## Verification status

TypeScript contract/consumer tests and the optimizer compatibility tests pass
locally. This remains `candidate` until the new runtime is deployed and
APID-29338 replay returns only the two new field names while preserving the
correct customer/internal audience split.

## Next validation action

Deploy the optimizer compatibility reader first, then deploy Auto-oncall,
replay APID-29338, inspect the API and workspace artifacts, and verify the
existing Jira internal comment remains `public=false` if a write refresh is
performed.