Skip to content

provenance: spec verification-unavailable fallback states (accepted_verifiers all timeout/error) #4446

@bokelley

Description

@bokelley

Problem

When every accepted_verifiers[] entry errors or times out on get_creative_features, the spec doesn't say what the seller does:

  • Hold the creative pending retry?
  • Reject with a new error code?
  • Allow and emit a structured warning?
  • Allow-and-log silently?

Inconsistent supply chain behavior here is a real risk. A buyer's orchestrator can't reason about expected seller behavior if it's per-seller policy with no protocol guidance. Same creative, two sellers, different outcomes depending on which one's verifier was up that minute.

Proposed fallback states

Codify three documented seller-policy modes the seller declares on creative_policy.provenance_requirements:

{
  "provenance_requirements": {
    "require_digital_source_type": true,
    "require_disclosure_metadata": true,
    "verification_unavailable_policy": "hold"
  }
}

Enum values:

  • hold (recommended default): seller responds to sync_creatives with action: 'pending' + new error code PROVENANCE_VERIFICATION_UNAVAILABLE and recovery: 'retry-later'. Idempotent retry expected.
  • reject: seller responds with action: 'failed' + PROVENANCE_VERIFICATION_UNAVAILABLE and recovery: 'correctable'. Buyer must resubmit, presumably to a seller whose verifier is up — or wait. Hard-stop mode for risk-averse sellers.
  • allow_with_warning: seller approves the creative but stamps the artifact with a structured governance_observations entry indicating verification was attempted and unavailable. Audit trail records the gap. Permissive mode for high-volume sellers willing to accept buyer-claim as the evidence floor when their own verifier infra is unreachable.

Default behavior if unspecified: hold. Safest default — neither blocks supply nor allows unverified claims through.

Distinct from inconclusive: an inconclusive verifier result is "I called the verifier and got a low-confidence response." This is "I could not call the verifier at all." Mirror the structure (recovery: retry-later for hold), but the error code distinguishes the root cause so a buyer's orchestrator can pick the right retry strategy.

Scope

Spec edit, not a wire change:

  1. New paragraph in docs/governance/creative/provenance-verification.mdx documenting the three policy modes and the hold default.
  2. New optional field verification_unavailable_policy on creative-policy.json provenance_requirements object.
  3. New error code PROVENANCE_VERIFICATION_UNAVAILABLE on error-code.json (and matching entry in enumMetadata per the dual-surface pattern from PR feat(schema): manifest.json + structured enumMetadata (closes #3725) #3738).
  4. Conformance scenario at static/compliance/source/protocols/media-buy/scenarios/ covering each of the three modes.

Out of scope

  • Retry policy / backoff semantics. That's idempotency-key territory and lives in existing spec surfaces.
  • Defining what "unavailable" means in seconds. Seller-side policy. A seller may decide "30s timeout = unavailable"; the protocol cares about the outcome, not the threshold.

Refs

Priority

Anytime. Low-risk, additive, closes a small gap pre-GA. Realistic candidate for a small docs+schema PR that could land soon after the bigger pre-GA work (signed claims, served-disclosure receipt) gets scoped.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions