Interface BuildGovernanceExecutionRequestInput

interface BuildGovernanceExecutionRequestInput {
    caller: string;
    governanceContext: string;
    plannedDelivery: {
        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;
    };
    phase?: GovernancePhase;
    executionCommitment?: GovernanceCommitment;
    deliveryMetrics?: {
        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 };
        };
    };
    modificationSummary?: string;
}

Index

Properties

caller governanceContext plannedDelivery phase? executionCommitment? deliveryMetrics? modificationSummary?

Properties

caller

caller: string

governanceContext

governanceContext: string

plannedDelivery

plannedDelivery: {
    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;
}

Type Declaration

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

`Optional`phase

phase?: GovernancePhase

`Optional`executionCommitment

executionCommitment?: GovernanceCommitment

`Optional`deliveryMetrics

deliveryMetrics?: {
    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 };
    };
}

Type Declaration

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.

`Optional`modificationSummary

modificationSummary?: string

Interface BuildGovernanceExecutionRequestInput

Index

Properties

Properties

caller

governanceContext

plannedDelivery

Type Declaration

Optionalmedia_buy_id?: string

Optionalproposal_id?: string

Optionalproposal_terms_digest?: string

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

Optionalcountries?: string[]

Optionalregions?: string[]

Optionalchannels?: MediaChannel[]

Optionalstart_time?: string

Optionalend_time?: string

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

Optionalsuppress?: Duration

Optionalsuppress_minutes?: number

Deprecated

Optionalmax_impressions?: number

Optionalper?: ReachUnit

Optionalwindow?: Duration

Optionalaudience_summary?: string

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

Min Items

Optionaltotal_budget?: number

Optionaldaily_budget_cap?: number

Optionalbudget_cap_timezone?: string

Optionalcurrency?: string

Optionalbudget_allocation?: BudgetAllocation

Optionalpacing?: Pacing

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

Optionalautomatic?: true

Optionalbid_amount?: number

Optionalmax_bid?: number

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

amount: number

strength: "cap" | "target"

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

value: number

strength: "target" | "floor"

Optionalenforced_policies?: string[]

Optionalext?: ExtensionObject

Optionalphase

OptionalexecutionCommitment

OptionaldeliveryMetrics

Type Declaration

Optionalstatement_id?: string

Min Length

Max Length

Optionalstatement_digest?: string

Pattern

Optionalsequence?: number

Minimum

Optionalissued_at?: string

Format

reporting_period: { start: string; end: string }

start: string

Format

end: string

Format

Optionalspend?: number

Minimum

Optionalcumulative_spend?: number

Minimum

Optionalcurrency?: string

Pattern

Optionalimpressions?: number

Minimum

Optionalcumulative_impressions?: number

Minimum

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

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

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

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

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

Optionalbaseline_description?: string

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

`Optional`media_buy_id?: string

`Optional`proposal_id?: string

`Optional`proposal_terms_digest?: string

`Optional`geo?: { countries?: string[]; regions?: string[] }

`Optional`countries?: string[]

`Optional`regions?: string[]

`Optional`channels?: MediaChannel[]

`Optional`start_time?: string

`Optional`end_time?: string

`Optional`frequency_cap?: {
suppress?: Duration;
suppress_minutes?: number;
max_impressions?: number;
per?: ReachUnit;
window?: Duration;
}

`Optional`suppress?: Duration

`Optional`suppress_minutes?: number

`Optional`max_impressions?: number

`Optional`per?: ReachUnit

`Optional`window?: Duration

`Optional`audience_summary?: string

`Optional`audience_targeting?: [AudienceSelector, ...AudienceSelector[]]

`Optional`total_budget?: number

`Optional`daily_budget_cap?: number

`Optional`budget_cap_timezone?: string

`Optional`currency?: string

`Optional`budget_allocation?: BudgetAllocation

`Optional`pacing?: Pacing

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

`Optional`automatic?: true

`Optional`bid_amount?: number

`Optional`max_bid?: number

`Optional`cost_per?: { amount: number; strength: "cap" | "target" }

`Optional`roas?: { value: number; strength: "target" | "floor" }

`Optional`enforced_policies?: string[]

`Optional`ext?: ExtensionObject

`Optional`phase

`Optional`executionCommitment

`Optional`deliveryMetrics

`Optional`statement_id?: string

`Optional`statement_digest?: string

`Optional`sequence?: number

`Optional`issued_at?: string

`Optional`spend?: number

`Optional`cumulative_spend?: number

`Optional`currency?: string

`Optional`impressions?: number

`Optional`cumulative_impressions?: number

`Optional`geo_distribution?: { [k: string]: number | undefined }

`Optional`channel_distribution?: { [k: string]: number | undefined }

`Optional`pacing?: "ahead" | "on_track" | "behind"

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

`Optional`baseline_description?: string

`Optional`cumulative_indices?: { [k: string]: number | undefined }

`Optional`modificationSummary