spec(errors): add PROPOSAL_EXPIRED and PROPOSAL_NOT_FOUND to canonical error catalog

[bokelley]

Motivation

Two new error codes needed for the proposal lifecycle (`buying_mode='refine'` with `action='finalize'`):

• `PROPOSAL_EXPIRED` — `create_media_buy(proposal_id=...)` issued after the committed proposal's `expires_at` hold window has passed. Buyer-fixable: the buyer must re-finalize a fresh proposal. Non-transient.
• `PROPOSAL_NOT_FOUND` — `create_media_buy` references a `proposal_id` the seller doesn't recognize (typo, wrong tenant, evicted from cache before consumption). Buyer-fixable: re-issue `get_products` to obtain a current proposal.

These are the natural counterparts to existing codes like `MEDIA_BUY_NOT_FOUND`. Today there's no spec-conformant way to signal proposal-lifecycle errors — adopters either reuse `INVALID_REQUEST` (loses semantics, recovery type wrong) or invent local codes (no cross-SDK consistency).

Proposed semantics

`PROPOSAL_EXPIRED`

```yaml
PROPOSAL_EXPIRED:
recovery: terminal
category: proposal-lifecycle
description: |
The proposal's expires_at hold window has passed. Buyer must
re-issue get_products with buying_mode='refine' + action='finalize'
to obtain a fresh committed proposal before calling create_media_buy.
examples:
- "create_media_buy(proposal_id='abc') called 2 hours after the proposal's
expires_at='2026-04-15T14:00:00Z' window expired"
```

`PROPOSAL_NOT_FOUND`

```yaml
PROPOSAL_NOT_FOUND:
recovery: correctable
category: proposal-lifecycle
description: |
The proposal_id is not recognized by the seller — never finalized,
belongs to a different tenant, or evicted from the seller's session
cache. Buyer should re-issue get_products to obtain a current
proposal_id.
examples:
- "create_media_buy(proposal_id='unknown_xyz') without a prior finalize"
- "proposal evicted from session cache before create_media_buy"
```

Wire shape

Same envelope as every other error. Just two new code values in the catalog.

Why now

The Python SDK is shipping v1.5 ProposalManager (PR #538 design doc; implementation pending) which includes finalize-transition handling and `expires_at` enforcement. The framework needs spec-conformant codes for the structured error envelope (especially after PR #525 + PR #536 made structured error codes load-bearing for storyboard `/adcp_error/code` JSON-pointer assertions).

The Python SDK will ship these codes via its `KNOWN_NON_SPEC_CODES` allowlist as a stopgap (same pattern as `CONFIGURATION_ERROR` from spec issue #3995) until the spec catalog includes them. Other SDKs implementing proposal lifecycle support will face the same gap.

Acceptance

• `PROPOSAL_EXPIRED` and `PROPOSAL_NOT_FOUND` added to `static/schemas/source/enums/error-code.json`'s `enum`, `enumDescriptions`, and `enumMetadata` (per the three-parallel-structures convention)
• Recovery semantics: `PROPOSAL_EXPIRED` = `terminal`; `PROPOSAL_NOT_FOUND` = `correctable`
• Targeted for AdCP 3.1
• Documentation note about how this maps to `buying_mode='refine'` + `action='finalize'` lifecycle

Refs

• AdCP 3.0 `proposal_finalize` storyboard scenario: `static/compliance/source/protocols/media-buy/scenarios/proposal_finalize.yaml`
• Sibling spec issue: spec(errors): add CONFIGURATION_ERROR to canonical error catalog #3995 (`CONFIGURATION_ERROR`) — same allowlist-then-spec-catch-up pattern
• Implementing SDK PR: `docs(proposals): ProposalManager v1.5 design — session cache, finalize, expires_at, capability validation, recipe lifecycle adcp-client-python#538` (v1.5 ProposalManager design doc; cites this issue)

[bokelley]

Triage

Classification: Feature request
Bucket(s): spec / protocol, schema
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: PROPOSAL_EXPIRED already exists on main with recovery: correctable — the proposed terminal is incorrect (buyer can autonomously re-run get_products, no operator required). Reject PROPOSAL_NOT_FOUND — REFERENCE_NOT_FOUND's description carries normative MUST language explicitly listing "proposals" and prohibiting custom *_NOT_FOUND codes without a spec change to that rule.
• adtech-product-expert: PROPOSAL_EXPIRED correctable is correct. Execute PROPOSAL_NOT_FOUND with correctable — consistent with MEDIA_BUY_NOT_FOUND, PLAN_NOT_FOUND patterns; SDK consumers get unambiguous dispatch without parsing error.field.

My take: Both experts agree PROPOSAL_EXPIRED is already present on main and correctly classified as correctable — drop the terminal proposal (autonomous recovery via get_products exists, making this correctable by definition). They split on PROPOSAL_NOT_FOUND. @bokelley, your call: Option A or Option B?

---

PROPOSAL_EXPIRED — no code change needed. Already in enum + enumDescriptions on main with recovery: correctable. The description can be enriched to name the buying_mode='refine' + action='finalize' path explicitly — that's a nit-level doc improvement, not a recovery reclassification. One dependency to clarify: the acceptance criteria reference enumMetadata, which doesn't exist on main yet and appears to be in-flight on a separate branch — confirm whether this PR should depend on or include that section.

---

PROPOSAL_NOT_FOUND — two paths:

Option A — use REFERENCE_NOT_FOUND (current spec, no schema change):

{
  "errors": [{
    "code": "REFERENCE_NOT_FOUND",
    "field": "proposal_id",
    "message": "proposal_id not recognized"
  }]
}

REFERENCE_NOT_FOUND's description already covers this with normative MUST language: "Use when no resource-specific not-found code applies (e.g., …, proposals, …)" and "Typed parameters that lack a dedicated standard code MUST use REFERENCE_NOT_FOUND." SDKs dispatch via error.field to identify the resource type. Zero schema changes needed.

Option B — add PROPOSAL_NOT_FOUND (requires normative update to anti-proliferation text):

{
  "errors": [{
    "code": "PROPOSAL_NOT_FOUND",
    "field": "proposal_id",
    "message": "proposal_id not recognized"
  }]
}

Unambiguous dispatch without error.field parsing — same operational clarity as CREATIVE_NOT_FOUND, PLAN_NOT_FOUND. Requires: (a) removing "proposals" from REFERENCE_NOT_FOUND's examples; (b) updating the MUST in REFERENCE_NOT_FOUND + error-handling.mdx uniform-response list; (c) cross-tenant enumeration posture identical to CREATIVE_NOT_FOUND / PLAN_NOT_FOUND.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01QHpoTZ3VKrME9tktX55pwA

---

Generated by Claude Code