Type Alias ProjectionDiagnostic

Type Declaration

• ProjectionDiagnosticBase & {
      code: "FORMAT_PROJECTION_FAILED";
      error: {
          details: {
              format_kind: CanonicalFormatKind;
              product_id: string;
              format_option_id?: string;
              resolution_failure:
                  | "no_registry_match"
                  | "catalog_lacks_canonical_annotation"
                  | "no_match";
          };
      };
  }

  • code: "FORMAT_PROJECTION_FAILED"

    Spec code (enums/error-code.json): registry-coverage gap or v1-catalog-coverage gap depending on resolution_failure:

    • no_registry_match — v2→v1 direction. Registry has no entries for this canonical (and v1_translatable is true).
    • catalog_lacks_canonical_annotation — v1→v2 direction. The AAO catalog has this v1 format but hasn't annotated it with a canonical: field. Native, DOOH, broadcast, and card-scaffolding categories sit in this bucket at 3.1 GA. Distinct from a generic registry gap — the catalog DOES know the format, it just hasn't blessed a v2 canonical mapping yet. Symmetric counterpart to CANONICAL_NOT_V1_TRANSLATABLE: that signals "no v1 form possible"; this signals "no v2 form yet."
    • no_match — v1→v2 direction, format not in catalog or registry, no structural match.

  • error: {
        details: {
            format_kind: CanonicalFormatKind;
            product_id: string;
            format_option_id?: string;
            resolution_failure:
                | "no_registry_match"
                | "catalog_lacks_canonical_annotation"
                | "no_match";
        };
    }

• ProjectionDiagnosticBase & {
      code: "FORMAT_DECLARATION_V1_AMBIGUOUS";
      error: {
          details: {
              format_kind: CanonicalFormatKind;
              product_id: string;
              format_option_id?: string;
              registry_matches: number;
          };
      };
  }

  • code: "FORMAT_DECLARATION_V1_AMBIGUOUS"

    Spec code (enums/error-code.json): registry has family-level structural entries for this canonical (e.g., the VAST entries for video_vast), but none are invertible to a specific v1 named format. Family is known, specific format isn't pickable. Correctable by the seller adding v1_format_ref to the declaration.

  • error: {
        details: {
            format_kind: CanonicalFormatKind;
            product_id: string;
            format_option_id?: string;
            registry_matches: number;
        };
    }

• ProjectionDiagnosticBase & {
      code: "FORMAT_DECLARATION_V1_NOT_APPLICABLE";
      error: {
          details: {
              format_kind: CanonicalFormatKind;
              product_id: string;
              format_option_id?: string;
              reason: "canonical_formats_only";
          };
      };
  }

  • code: "FORMAT_DECLARATION_V1_NOT_APPLICABLE"

    SDK-local code: declaration has canonical_formats_only: true. Seller explicitly opted out of v1 emission. Not a registry- coverage gap; not ambiguous. Informational so buyers can see why a product disappeared from a v1-only catalog.

  • error: {
        details: {
            format_kind: CanonicalFormatKind;
            product_id: string;
            format_option_id?: string;
            reason: "canonical_formats_only";
        };
    }

• ProjectionDiagnosticBase & {
      code: "CANONICAL_NOT_V1_TRANSLATABLE";
      error: {
          details: {
              format_kind: CanonicalFormatKind;
              product_id: string;
              format_option_id?: string;
          };
      };
  }

  • code: "CANONICAL_NOT_V1_TRANSLATABLE"

    SDK-local code: canonical declares v1_translatable: false. Structural v1-unreachability — no v1 form is possible for this canonical regardless of registry coverage. The 4 inherently-v2 canonicals at 3.1 GA: image_carousel, sponsored_placement, responsive_creative, agent_placement. Spec is explicit: SDKs MUST NOT emit FORMAT_PROJECTION_FAILED for these (they're not coverage gaps).

  • error: {
        details: {
            format_kind: CanonicalFormatKind;
            product_id: string;
            format_option_id?: string;
        };
    }

• ProjectionDiagnosticBase & {
      code: "FORMAT_DECLARATION_V1_LOSSY_MULTI_SIZE";
      error: {
          details: {
              format_kind: CanonicalFormatKind;
              product_id: string;
              format_option_id?: string;
              size_mode: "sizes" | "responsive_range";
              declared_sizes_count?: number;
              emitted_sizes_count?: number;
              v1_emit_represents_size?: { width?: number; height?: number };
          };
      };
  }

  • code: "FORMAT_DECLARATION_V1_LOSSY_MULTI_SIZE"

    SDK-local code: v2 declaration uses multi-size (sizes: [...]) or responsive (min_width/max_width/min_height/max_height) params, but v1_format_ref is a single catalog entry that can only carry ONE fixed (width, height). The v1 wire emit represents only the seller-chosen representative size; the remaining sizes are silently dropped on the v1 wire.

    This diagnostic is emitted alongside the v1 format_id — not instead of it — so the v1 buyer still sees the product but the buyer code is told what coverage was lost. Different from FORMAT_DECLARATION_V1_AMBIGUOUS (no v1 emit) and FORMAT_DECLARATION_V1_NOT_APPLICABLE (seller opt-out).

    Surface follow-up: an SDK MAY (non-normative) expand multi- size to N v1 format_ids by looking up the catalog for each size. Today's prototype emits only the seller-asserted representative; multi-emit is a follow-up.

  • error: {
        details: {
            format_kind: CanonicalFormatKind;
            product_id: string;
            format_option_id?: string;
            size_mode: "sizes" | "responsive_range";
            declared_sizes_count?: number;
            emitted_sizes_count?: number;
            v1_emit_represents_size?: { width?: number; height?: number };
        };
    }

    • details: {
          format_kind: CanonicalFormatKind;
          product_id: string;
          format_option_id?: string;
          size_mode: "sizes" | "responsive_range";
          declared_sizes_count?: number;
          emitted_sizes_count?: number;
          v1_emit_represents_size?: { width?: number; height?: number };
      }

      • format_kind: CanonicalFormatKind

      • product_id: string

      • Optionalformat_option_id?: string

      • size_mode: "sizes" | "responsive_range"

      • Optionaldeclared_sizes_count?: number

      • Optionalemitted_sizes_count?: number

        How many v1 format_ids the SDK actually emitted. < declared_sizes_count when the catalog doesn't cover every declared size; equal when the catalog has full coverage. The fan-out is non-normative — when this equals 1, only the seller-asserted rep was emitted; v1 buyers lose the rest.

      • Optionalv1_emit_represents_size?: { width?: number; height?: number }

• ProjectionDiagnosticBase & {
      code: "LEGACY_FORMAT_ID_DROPPED_UNMAPPED";
      error: {
          details: {
              product_id: string;
              dropped_format_id: {
                  agent_url: string;
                  id: string;
                  width?: number;
                  height?: number;
                  duration_ms?: number;
              };
          };
      };
  }

  • code: "LEGACY_FORMAT_ID_DROPPED_UNMAPPED"

    SDK-local code: canonical-only projection (toCanonicalOnlyProduct / toCanonicalOnlyResponse) dropped a legacy format_id that no format_options[].v1_format_ref covers. Emitted only on the v2-native pass-through path — a seller that sent format_options[] directly but also carried a format_ids[] entry with no canonical representation. Without it, canonical-only mode would silently discard a format the buyer could still have acted on via the v1 path.

    On the v1 → v2 projection path an unmappable ref is already surfaced as FORMAT_PROJECTION_FAILED; this code covers the gap the projection path can't see (no projection runs when the seller is already v2-native).

  • error: {
        details: {
            product_id: string;
            dropped_format_id: {
                agent_url: string;
                id: string;
                width?: number;
                height?: number;
                duration_ms?: number;
            };
        };
    }

    • details: {
          product_id: string;
          dropped_format_id: {
              agent_url: string;
              id: string;
              width?: number;
              height?: number;
              duration_ms?: number;
          };
      }

      • product_id: string

      • dropped_format_id: {
            agent_url: string;
            id: string;
            width?: number;
            height?: number;
            duration_ms?: number;
        }

        The full ref that was dropped, including the dimensional discriminators (width / height / duration_ms) when the input carried them — so a buyer can tell which variant of a multi-size/multi-duration family was lost and re-acquire it on the v1 path. Omitted keys mean the input ref carried no value.