refactor(callouts): normalize outbound failure-policy configuration

[leseb]

Description

Outbound AI callout filters express equivalent failure behavior through several configuration vocabularies:

• provider_failure_mode: open|closed
• callout_failure_mode: open|closed
• on_error: ignore|reject
• on_missing: continue|reject

There are also duplicate FailureMode types and validators in the shared web-search and OpenAI Responses paths. This makes new filters choose names and semantics ad hoc, complicates documentation, and makes cross-filter safety review harder.

Define one canonical vocabulary and shared representation for equivalent outbound callout failures. Preserve separate domain policies where they are genuinely different: for example, file resolution's on_missing governs resource absence and must not automatically become equivalent to a transport/provider failure.

The design must also account for the pipeline-level failure_mode key, which is structural and currently prevents filters from simply reusing that field name.

Motivation

Equivalent operational choices should look and behave the same across callout filters. A shared model reduces configuration mistakes and keeps fail-open/fail-closed validation, status handling, documentation, and future filters consistent.

Acceptance criteria

• Inventory every outbound AI callout filter and classify its transport, provider, missing-resource, partial-result, and parse failures.
• Choose and document one canonical external vocabulary for equivalent callout failures without colliding with pipeline-level failure_mode.
• Consolidate duplicate internal policy types and validators where semantics match.
• Keep semantically distinct policies separate and document their interaction.
• Existing configuration has an explicit compatibility strategy: aliases with deprecation, a documented migration, or a deliberate breaking-change decision.
• Fail-open choices remain subject to the server's security-filter policy and cannot silently weaken security-sensitive failures.
• Generated filter documentation, examples, schema/validation, and focused behavior tests are updated together.

Alternatives Considered

Only renaming fields would leave duplicate semantics and validators. Conversely, forcing every error into one enum would erase meaningful distinctions such as missing resources versus failed upstream calls.

Area

Provider APIs (OpenAI/Anthropic)

Parent Epic (optional)

#694

Related

• status_on_error validators accept success and informational HTTP statuses #672 should remain focused on rejecting invalid status_on_error values; this refactor should reuse its constrained validation.
• feat(openai): add file_search_callout filter for hosted vector store search #493 currently introduces on_error: ignore|reject for file-search callouts.