Function buildGovernanceIntentRequest

Returns {
    adcp_version?: string;
    adcp_major_version?: number;
    plan_id?: string;
    caller: string;
    purchase_type?: PurchaseType;
    target_agent?: string;
    proposed_commitment?: { amount: number; currency: string };
    execution_commitment?: { amount: number; currency: string };
    tool?: string;
    payload?: {};
    proposal?: {
        proposal_id: string;
        proposal_kind:
            | "new_media_buy"
            | "media_buy_update"
            | "media_buy_cancellation";
        parent_proposal_id?: string;
        media_buy_id?: string;
        opportunity_id?: string;
        base_media_buy_revision?: number;
        proposal_status: ProposalStatus;
        accepted_at?: string;
        expires_at?: string;
        name: string;
        description?: string;
        brief_alignment?: string;
        commercial_terms: CommercialTerms;
        terms_digest: string;
        insertion_order?: InsertionOrder;
    };
    governance_context?: string;
    consultation_context?: string;
    phase?: GovernancePhase;
    planned_delivery?: {
        media_buy_id?: string;
        proposal_id?: string;
        proposal_terms_digest?: string;
        geo?: { countries?: string[]; regions?: string[] };
        channels?: MediaChannel[];
        start_time?: string;
        end_time?: string;
        frequency_cap?: {
            suppress?: Duration;
            suppress_minutes?: number;
            max_impressions?: number;
            per?: ReachUnit;
            window?: Duration;
        };
        audience_summary?: string;
        audience_targeting?: [AudienceSelector, ...AudienceSelector[]];
        total_budget?: number;
        daily_budget_cap?: number;
        budget_cap_timezone?: string;
        currency?: string;
        budget_allocation?: BudgetAllocation;
        pacing?: Pacing;
        bidding?: {
            automatic?: true;
            bid_amount?: number;
            max_bid?: number;
            cost_per?: { amount: number; strength: "cap" | "target" };
            roas?: { value: number; strength: "target" | "floor" };
        };
        enforced_policies?: string[];
        ext?: ExtensionObject;
    };
    delivery_metrics?: {
        statement_id?: string;
        statement_digest?: string;
        sequence?: number;
        issued_at?: string;
        reporting_period: { start: string; end: string };
        spend?: number;
        cumulative_spend?: number;
        currency?: string;
        impressions?: number;
        cumulative_impressions?: number;
        geo_distribution?: { [k: string]: number | undefined };
        channel_distribution?: { [k: string]: number | undefined };
        pacing?: "ahead" | "on_track" | "behind";
        audience_distribution?: {
            baseline: "platform" | "custom" | "census";
            baseline_description?: string;
            indices: { [k: string]: number | undefined };
            cumulative_indices?: { [k: string]: number | undefined };
        };
    };
    modification_summary?: string;
    runtime_attestations?: (
        {
            issuer: AttestationIssuer;
            claim_type: string;
            subject: AttestationSubject;
            locator?: | AttestationCredentialUriLocator
            | AttestationIssuerCredentialIdLocator;
            embedded_credential?: {
                format: string;
                value: string
                | {};
                ext?: ExtensionObject;
            };
            content_digest?: string;
            credential_version?: string;
            validity_hint?: { not_before?: string; expires_at?: string };
            verify_agent?: { agent_url: string };
            ext?: ExtensionObject;
        } & {
            issuer: AttestationIssuer;
            claim_type: string;
            subject: AttestationSubject;
            locator?: | AttestationCredentialUriLocator
            | AttestationIssuerCredentialIdLocator;
            embedded_credential?: {
                format: string;
                value: string
                | {};
                ext?: ExtensionObject;
            };
            content_digest?: string;
            credential_version?: string;
            validity_hint?: { not_before?: string; expires_at?: string };
            verify_agent?: { agent_url: string };
            ext?: ExtensionObject;
        } & {
            subject?: {
                type: "resource";
                resource_type: "https://adcontextprotocol.org/claims/subjects/signal";
            };
        }
    )[];
    invoice_recipient?: BusinessEntity;
    context?: ContextObject;
    ext?: ExtensionObject;
}

• Optionaladcp_version?: string

  Release-precision AdCP version (VERSION.RELEASE, e.g. "3.0", "3.1", "3.1-beta"). On a request: the buyer's release pin — the seller validates against its supported_versions and returns VERSION_UNSUPPORTED on cross-major mismatch, or downshifts to the highest supported release within the same major. On a response: the release the seller actually served — clients SHOULD validate the response against that release's schema, not against their pin. Patches are not negotiated; surface them as build_version on capabilities for operational visibility. When omitted, falls back to adcp_major_version (deprecated) or server default. Buyers SHOULD emit both adcp_version and adcp_major_version through 3.x to remain compatible with sellers that only read the legacy field. NORMALIZATION: SDKs that read full-semver values from bundle metadata (e.g. ComplianceIndex.published_version = "3.1.0-beta.1") MUST normalize to release-precision ("3.1-beta.1") before emitting on the wire — meta-field values are NOT valid wire values.

• Optionaladcp_major_version?: number

  Deprecated

  DEPRECATED in favor of adcp_version (release-precision string). Servers MUST continue to honor this field through 3.x. Removed in 4.0. Original semantics: the AdCP major version the buyer's payloads conform to. Sellers validate against their supported major_versions and return VERSION_UNSUPPORTED if unsupported. When omitted, the seller assumes its highest supported version.

• Optionalplan_id?: string

  Campaign governance plan identifier. Required on the initial intent or availability check, before a governance_context exists. Optional on subsequent checks: the governance agent derives the plan from its own signed governance_context. If both are present, the governance agent MUST reject the request when plan_id does not match the token's plan binding. Services MUST treat governance_context as authoritative and MUST NOT require a buyer to disclose plan_id. A plan is owned by the authenticated buyer principal that synchronized it; plan_id is an identifier, not an account credential.

• caller: string

  Claimed URL of the agent making the request. The transport credential MUST resolve to an agent URL; the governance agent requires an exact match and uses only that resolved URL for authorization, audit, and signed context issuance. On intent checks the authenticated buyer must be the plan owner or hold an active delegation, while approved_sellers is evaluated against the target service that becomes the token audience. On execution checks the authenticated caller MUST equal that preserved audience. An unresolved body assertion never grants plan access or authorization.

• Optionalpurchase_type?: PurchaseType

• Optionaltarget_agent?: string

  Exact agent URL of the downstream service that will receive the governed task. Required on intent checks and copied byte-for-byte into the signed governance_context aud claim. This routing and authorization field is not part of payload: payload remains exactly the downstream task arguments. A consultation re-check MUST use the same target_agent.

• Optionalproposed_commitment?: { amount: number; currency: string }

  Task-neutral monetary amount the intent would authorize. For update_media_buy and control_media_buy this is the buyer-computed positive incremental commitment, not the post-update total. For accept_proposal it is derived from the supplied proposal commercial_terms; for buy_products it is derived from the purchase payload. Amount 0 explicitly represents a verified no-cost action. The governance agent persists this value as authoritative check state.

  • amount: number

    Minimum

    0

  • currency: string

    Pattern

    ^[A-Z]{3}$

• Optionalexecution_commitment?: { amount: number; currency: string }

  Seller-computed positive incremental commitment for a MediaBuy execution check. The seller MUST derive this atomically from its authoritative proposal or current revision and the requested operation, and the governance agent MUST reject it when it exceeds the prior intent ceiling or uses another currency.

  • amount: number

    Minimum

    0

  • currency: string

    Pattern

    ^[A-Z]{3}$

• Optionaltool?: string

  The AdCP tool being checked (e.g., 'create_media_buy', 'acquire_rights', 'activate_signal'). Present on intent checks (orchestrator). The governance agent uses the presence of tool+payload to identify an intent check.

• Optionalpayload?: {}

  The full downstream tool arguments exactly as they will be sent to target_agent. Present on intent checks. Governance routing metadata is carried by target_agent, never injected into this object. The governance agent can inspect any field to validate against the plan.

• Optionalproposal?: {
      proposal_id: string;
      proposal_kind:
          | "new_media_buy"
          | "media_buy_update"
          | "media_buy_cancellation";
      parent_proposal_id?: string;
      media_buy_id?: string;
      opportunity_id?: string;
      base_media_buy_revision?: number;
      proposal_status: ProposalStatus;
      accepted_at?: string;
      expires_at?: string;
      name: string;
      description?: string;
      brief_alignment?: string;
      commercial_terms: CommercialTerms;
      terms_digest: string;
      insertion_order?: InsertionOrder;
  }

  • proposal_id: string

  • proposal_kind: "new_media_buy" | "media_buy_update" | "media_buy_cancellation"

  • Optionalparent_proposal_id?: string

    Immediate predecessor this snapshot was forked from. Every proposal produced by refine_proposals carries it, equal to the request's source proposal_id, so negotiation lineage is reconstructible from proposals alone.

  • Optionalmedia_buy_id?: string

  • Optionalopportunity_id?: string

    Buyer planning cycle associated with this proposal. Revisions inherit it; it does not participate in proposal identity.

  • Optionalbase_media_buy_revision?: number

  • proposal_status: ProposalStatus

  • Optionalaccepted_at?: string

  • Optionalexpires_at?: string

    For a draft, the indicative-terms freshness deadline. For a committed proposal, the inventory-hold deadline.

  • name: string

  • Optionaldescription?: string

  • Optionalbrief_alignment?: string

  • commercial_terms: CommercialTerms

  • terms_digest: string

    Base64url SHA-256 digest of the RFC 8785 JCS serialization of commercial_terms, prefixed with sha256:.

  • Optionalinsertion_order?: InsertionOrder

• Optionalgovernance_context?: string

  Opaque authorization context from a prior approved check_governance response. Services pass it verbatim on execution and lifecycle checks; the issuing governance agent derives the plan and prior decision from the token. Intermediaries MUST NOT parse it for business logic. Governance agents MUST emit a compact JWS per the AdCP JWS profile.

  Min Length

  1

  Max Length

  4096

  Pattern

  ^[\x20-\x7E]+$

• Optionalconsultation_context?: string

  Opaque, non-authorizing handle returned with an intent conditions verdict. Pass it only when re-checking the adjusted intent so the governance agent can correlate negotiation attempts. The governance agent MUST resolve it under the authenticated principal and reject the re-check unless principal, caller, plan_id, tool, purchase_type, and target audience match the original conditions check. Services MUST NOT receive or accept this value as authorization.

  Min Length

  1

  Max Length

  255

  Pattern

  ^[A-Za-z0-9_.:-]+$

• Optionalphase?: GovernancePhase

• Optionalplanned_delivery?: {
      media_buy_id?: string;
      proposal_id?: string;
      proposal_terms_digest?: string;
      geo?: { countries?: string[]; regions?: string[] };
      channels?: MediaChannel[];
      start_time?: string;
      end_time?: string;
      frequency_cap?: {
          suppress?: Duration;
          suppress_minutes?: number;
          max_impressions?: number;
          per?: ReachUnit;
          window?: Duration;
      };
      audience_summary?: string;
      audience_targeting?: [AudienceSelector, ...AudienceSelector[]];
      total_budget?: number;
      daily_budget_cap?: number;
      budget_cap_timezone?: string;
      currency?: string;
      budget_allocation?: BudgetAllocation;
      pacing?: Pacing;
      bidding?: {
          automatic?: true;
          bid_amount?: number;
          max_bid?: number;
          cost_per?: { amount: number; strength: "cap" | "target" };
          roas?: { value: number; strength: "target" | "floor" };
      };
      enforced_policies?: string[];
      ext?: ExtensionObject;
  }

  • Optionalmedia_buy_id?: string

    Seller-assigned media buy identifier. Optional on a purchase-phase prepare/check because the service may not assign the identifier until commit; required on modification and delivery lifecycle checks.

  • Optionalproposal_id?: string

    Proposal snapshot being executed or currently governing the MediaBuy.

  • Optionalproposal_terms_digest?: string

    Digest of the proposal commercial_terms. The governance agent compares it to the digest bound during the intent check.

  • Optionalgeo?: { countries?: string[]; regions?: string[] }

    Geographic targeting the seller will apply.

    • Optionalcountries?: string[]

      ISO 3166-1 alpha-2 country codes where ads will deliver.

    • Optionalregions?: string[]

      ISO 3166-2 subdivision codes where ads will deliver.

  • Optionalchannels?: MediaChannel[]

    Channels the seller will deliver on.

  • Optionalstart_time?: string

    Actual flight start the seller will use.

  • Optionalend_time?: string

    Actual flight end the seller will use.

  • Optionalfrequency_cap?: {
        suppress?: Duration;
        suppress_minutes?: number;
        max_impressions?: number;
        per?: ReachUnit;
        window?: Duration;
    }

    • Optionalsuppress?: Duration

      Cooldown period between consecutive exposures to the same entity. Prevents back-to-back ad delivery (e.g. {"interval": 60, "unit": "minutes"} for a 1-hour cooldown). Preferred over suppress_minutes.

    • Optionalsuppress_minutes?: number

      Deprecated

      Deprecated — use suppress instead. Cooldown period in minutes between consecutive exposures to the same entity (e.g. 60 for a 1-hour cooldown).

    • Optionalmax_impressions?: number

      Maximum number of impressions per entity per window. For duration windows, implementations typically use a rolling window; 'campaign' applies a fixed cap across the full flight.

    • Optionalper?: ReachUnit

      Entity granularity for impression counting. Required when max_impressions is set.

    • Optionalwindow?: Duration

      Time window for the max_impressions cap (e.g. {"interval": 7, "unit": "days"} or {"interval": 1, "unit": "campaign"} for the full flight). Required when max_impressions is set.

  • Optionalaudience_summary?: string

    Human-readable summary of the audience the seller will target.

  • Optionalaudience_targeting?: [AudienceSelector, ...AudienceSelector[]]

    Structured audience targeting the seller will activate. Each entry is either a signal reference or a descriptive criterion. When present, governance agents MUST use this for bias/fairness validation and SHOULD ignore audience_summary for validation purposes. The audience_summary field is a human-readable rendering of this array, not an independent declaration.

    Min Items

    1

  • Optionaltotal_budget?: number

    Total budget the seller will deliver against.

  • Optionaldaily_budget_cap?: number

    Hard aggregate daily spend ceiling the seller will enforce. Governance checks compare it with the authorized execution controls; it does not allocate spend to packages.

  • Optionalbudget_cap_timezone?: string

    IANA timezone defining the calendar-day boundary for every daily cap on the planned media buy.

  • Optionalcurrency?: string

    ISO 4217 currency code for the budget. Governance execution checks require it whenever total_budget is present and require it to match the intent-authorized currency.

  • Optionalbudget_allocation?: BudgetAllocation

    Seller-accepted cross-package allocation authority and goals. Presence with seller_optimized mode means automatic within-buy reallocations are part of the committed delivery, not separate modification actions.

  • Optionalpacing?: Pacing

  • Optionalbidding?: {
        automatic?: true;
        bid_amount?: number;
        max_bid?: number;
        cost_per?: { amount: number; strength: "cap" | "target" };
        roas?: { value: number; strength: "target" | "floor" };
    }

    Seller-interpreted media-buy bidding policy used for governance and delivery transparency. Goal-bound controls follow budget-allocation scope semantics and monetary fields use the planned delivery currency. Package-authored overrides, including explicit automatic overrides, remain on packages rather than being copied into this aggregate field.

    • Optionalautomatic?: true

      Explicitly use seller/provider automatic bidding at this authored scope. At package scope this is a complete override of a media-buy policy, not inheritance. It MUST be the only field in the block and MUST be preserved on readback.

    • Optionalbid_amount?: number

      Manual auction bid denominated in the media-buy currency and expressed per the selected pricing option's auction unit. For example, a CPM option interprets the amount per thousand impressions. This is the amount submitted to the auction, not a promise that the clearing price equals it. Requires an auction-priced pricing option whose currency equals the media-buy currency.

    • Optionalmax_bid?: number

      Hard per-auction ceiling denominated in the media-buy currency and expressed per the selected pricing option's auction unit. This is the only canonical hard auction ceiling and MUST NOT be translated into an average outcome-cost control. Requires an auction-priced pricing option whose currency equals the media-buy currency. May stand alone or supplement cost_per/roas only when the relevant scope capability advertises that combination.

    • Optionalcost_per?: { amount: number; strength: "cap" | "target" }

      Average cost control per result of the scope-bound primary optimization goal. At seller-optimized media-buy scope it binds to budget_allocation.optimization_goals; at package scope it binds to that package's optimization_goals; at fixed media-buy scope it binds independently to each inheriting package and is valid only when their primary-goal result units are compatible. Metric goals are compatible only when metric and every result-defining qualifier match; vendor_metric goals only when vendor and metric_id match; event goals only when the event_type/custom_event_name set and resolved attribution_window match. Primary is the earliest array entry among goals tied for the lowest explicit numeric priority; unprioritized goals follow explicitly prioritized goals; when all priorities are absent, the first entry is primary.

      • amount: number

        Average cost amount per scope-bound primary-goal result, denominated in the media-buy currency.

      • strength: "cap" | "target"

        cap optimizes for an average at or below the amount and accepts underdelivery when necessary; target optimizes around the amount while balancing volume and spend. Neither is a per-result or per-auction guarantee.

    • Optionalroas?: { value: number; strength: "target" | "floor" }

      Dimensionless return-on-ad-spend control bound to the same scope-specific primary goal rules as cost_per. The bound goal must be value-bearing; a fixed media-buy default requires a value-bearing primary goal on every inheriting package. Every referenced value-bearing event source MUST declare value_currencies containing the media-buy currency. The seller validates this at buy creation; each buy consumes only exact-currency records, while other declared currencies remain available to other buys. Sellers MUST NOT perform currency conversion.

      • value: number

        Return per unit of ad spend; 4 means 4 units of value per 1 unit spent.

      • strength: "target" | "floor"

        floor prefers underdelivery to knowingly optimizing below the requested return; target optimizes around the requested return. Neither guarantees realized return.

  • Optionalenforced_policies?: string[]

    Registry policy IDs the seller will enforce for this delivery.

  • Optionalext?: ExtensionObject

• Optionaldelivery_metrics?: {
      statement_id?: string;
      statement_digest?: string;
      sequence?: number;
      issued_at?: string;
      reporting_period: { start: string; end: string };
      spend?: number;
      cumulative_spend?: number;
      currency?: string;
      impressions?: number;
      cumulative_impressions?: number;
      geo_distribution?: { [k: string]: number | undefined };
      channel_distribution?: { [k: string]: number | undefined };
      pacing?: "ahead" | "on_track" | "behind";
      audience_distribution?: {
          baseline: "platform" | "custom" | "census";
          baseline_description?: string;
          indices: { [k: string]: number | undefined };
          cumulative_indices?: { [k: string]: number | undefined };
      };
  }

  Seller-attributed canonical delivery statement. MUST be present for 'delivery' phase. The authenticated seller binds one immutable statement_id and digest to a monotonically increasing sequence; the buyer can later submit the copy it received or an independent observation through report_plan_outcome.

  • Optionalstatement_id?: string

    Stable seller-issued identifier for this immutable delivery statement.

    Min Length

    1

    Max Length

    255

  • Optionalstatement_digest?: string

    SHA-256 digest of RFC 8785 JCS over {seller_reference, delivery_metrics}, excluding statement_digest itself. The authenticated submission binds the seller to this digest.

    Pattern

    ^sha256:[a-f0-9]{64}$

  • Optionalsequence?: number

    Monotonically increasing sequence for this governed action. A statement ID or sequence cannot be reused with different content.

    Minimum

    1

  • Optionalissued_at?: string

    When the seller issued the canonical statement.

    Format

    date-time

  • reporting_period: { start: string; end: string }

    Start and end timestamps for the reporting window.

    • start: string

      Format

      date-time

    • end: string

      Format

      date-time

  • Optionalspend?: number

    Total spend during the reporting period.

    Minimum

    0

  • Optionalcumulative_spend?: number

    Total spend since the governed action started.

    Minimum

    0

  • Optionalcurrency?: string

    Currency of spend fields; must match the plan and planned delivery.

    Pattern

    ^[A-Z]{3}$

  • Optionalimpressions?: number

    Impressions delivered during the reporting period.

    Minimum

    0

  • Optionalcumulative_impressions?: number

    Total impressions since the governed action started.

    Minimum

    0

  • Optionalgeo_distribution?: { [k: string]: number | undefined }

    Actual geographic distribution. Keys are ISO 3166-1 alpha-2 codes, values are percentages.

  • Optionalchannel_distribution?: { [k: string]: number | undefined }

    Actual channel distribution. Keys are channel enum values, values are percentages.

  • Optionalpacing?: "ahead" | "on_track" | "behind"

    Whether delivery is ahead of, on track with, or behind the planned pace.

  • Optionalaudience_distribution?: {
        baseline: "platform" | "custom" | "census";
        baseline_description?: string;
        indices: { [k: string]: number | undefined };
        cumulative_indices?: { [k: string]: number | undefined };
    }

    Actual audience composition during the reporting period. Enables mid-flight drift detection when actual delivery skews from planned audience targeting.

    • baseline: "platform" | "custom" | "census"

      Population baseline used for index calculation. 'census': national census or equivalent population data. 'platform': the seller's active user base. 'custom': a custom baseline defined by the seller (describe in baseline_description).

    • Optionalbaseline_description?: string

      Description of the baseline when baseline is 'custom' (e.g., 'US adults 18+ with broadband access').

    • indices: { [k: string]: number | undefined }

      Audience index values for the current reporting period. Keys are seller-defined dimension:value strings (e.g., 'age:25-34', 'gender:female', 'income:high'). The protocol does not mandate a taxonomy — dimensions and value labels vary by seller. Values are index relative to the declared baseline (1.0 = at parity, >1.0 = over-indexed, <1.0 = under-indexed).

    • Optionalcumulative_indices?: { [k: string]: number | undefined }

      Cumulative audience index values since the governed action started. Same key format as indices (dimension:value). Use for detecting sustained bias drift that may not appear in a single reporting period.

• Optionalmodification_summary?: string

  Human-readable summary of what changed. SHOULD be present for 'modification' phase.

  Max Length

  1000

• Optionalruntime_attestations?: (
      {
          issuer: AttestationIssuer;
          claim_type: string;
          subject: AttestationSubject;
          locator?: | AttestationCredentialUriLocator
          | AttestationIssuerCredentialIdLocator;
          embedded_credential?: {
              format: string;
              value: string
              | {};
              ext?: ExtensionObject;
          };
          content_digest?: string;
          credential_version?: string;
          validity_hint?: { not_before?: string; expires_at?: string };
          verify_agent?: { agent_url: string };
          ext?: ExtensionObject;
      } & {
          issuer: AttestationIssuer;
          claim_type: string;
          subject: AttestationSubject;
          locator?: | AttestationCredentialUriLocator
          | AttestationIssuerCredentialIdLocator;
          embedded_credential?: {
              format: string;
              value: string
              | {};
              ext?: ExtensionObject;
          };
          content_digest?: string;
          credential_version?: string;
          validity_hint?: { not_before?: string; expires_at?: string };
          verify_agent?: { agent_url: string };
          ext?: ExtensionObject;
      } & {
          subject?: {
              type: "resource";
              resource_type: "https://adcontextprotocol.org/claims/subjects/signal";
          };
      }
  )[]

  Optional independently issued runtime evidence for an activate_signal intent check whose payload action is activate (or omitted, which defaults to activate). It MUST NOT be supplied for deactivate. Each item is the shared portable AttestationReference from the core #4529 contract; it carries no authoritative buyer-supplied decision or confidence. The governance agent MUST evaluate every item under adcp.attestations plus governance.runtime_attestations capability policy, preserve input order in response runtime_attestation_evaluations[], and reject off-policy issuers, resolvers, credential origins, and verifier nominations without network access. This field is per-check evidence outside the synced plan and therefore outside the plan_hash preimage. Other tools and purchase types cannot carry this field.

• Optionalinvoice_recipient?: BusinessEntity

• Optionalcontext?: ContextObject

• Optionalext?: ExtensionObject