Explainability reference

What every bid looks like. Who can change the rules.

Two things the Provespend agent always ships: an immutable ledger behind every decision, and a human-readable policy file a compliance team can edit without paging the agency. This page is the reference for both.

Read the ledger specRead the policy spec
Ledger
SHA-256 chained
Policy file
YAML, versioned
Editor roles
4
Override
<30 s
audit.provespend.app
reference excerpt

One ledger entry, annotated

ts
2026-08-15T03:14:09Z
channel
Google
campaign
Brand-Lift-APAC
decision
bid
cpa
$8.30
policy_version
policy.yaml@v18.4
reasoning
Auction position falling without bid lift
rationale
impr_share_loss=$0.12; +14% bid floor

Section 1 of 2

An immutable ledger behind every bid.

Every auction the agent touches is recorded: timestamp, channel, campaign, decision, the dollar amount that resulted, and the rationale the policy produced. Compliance teams replay it like a git log.

Every entry, every field

A single ledger row carries the decision shape, plus the policy version the decision was evaluated against. Same vocabulary as the live audit stream.

  • tsUTC timestamp of the auction evaluation.
  • channelMeta, Google, TikTok, LinkedIn, or programmatic.
  • campaignThe named campaign that owned the spend.
  • decisionBID, HOLD, or ROTATE — the only three states the agent writes.
  • cpaThe cost-per-acquisition landed, in dollars. Em-dash on HOLD.
  • reasoningOne-line plain-English justification.
  • rationaleThe named signal and threshold from the policy file that produced the decision.
  • policy_versionWhich version of policy.yaml the decision was evaluated against.
audit.provespend.app
illustrative rows
tschannelcampaigndecisioncparationale
03:14:07[Meta]Q4-Retention-EUbid$14.20last_3d_cpa=$13.80 < $18 floor; signal_ctr=+0.42σ
03:14:08[TikTok]SMB-Trial-UShold—7d_avg_cpa=$42.10 > $35 ceiling; pause 6h, re-evaluate
03:14:09[Google]Brand-Lift-APACbid$8.30impr_share_loss=$0.12 to rank; +14% bid floor
03:14:11[LinkedIn]Awareness-Considerrotate$31.05ctr_z=-1.8 / 7d; swap to creative_E
03:14:13[Programmatic]Reactivation-Lapsedbid$6.10predicted_roas=4.2; shift +$1.2k/day from TikTok
03:14:15[TikTok]SMB-Trial-UShold—daily_pacing=+38%; cap +14% until reset
03:14:18[Meta]Lookalike-1P-LALbid$11.95audience_signal=green; bid at floor
Each row above is illustrative copy of the schema the live ledger writes when it ships — same field names, same decision values, same rationale style.

Section 2 of 2

A bidding policy you can actually read.

The agent operates under a human-readable policy.yaml. Compliance teams, legal, and the client all read the same file. Edits are diffed before saving and enforced in under thirty seconds.

Targets

Quarterly ROAS floors per channel, monthly CPA ceilings per campaign, plus soft-launch curves for new SKUs. Each target is a named rule with a version, author, and last-edit timestamp — the agent cites the rule by name in every ledger rationale.

3.4× ROAS

default floor

Annotated policy.yaml

Three rules lifted from a real Provespend customer — one target, one override, one exclusion. Every rule carries the author who wrote it.

illustrative
# Provespend bidding policy — illustrative excerpt.
# Every rule carries: who wrote it, when, and under which policy version.
policy_version: v18.4
last_edited_by: mara.chen@provespend.app
last_edited_at: 2026-08-12T14:08:00Z

targets:
  - id: meta_roas_floor
    author: mara.chen@provespend.app
    rule:
      channel: Meta
      metric: roas
      floor: 3.4
      window: 7d

overrides:
  - id: pin_creative_C_off
    author: compliance@client.example
    rule:
      campaign: SMB-Trial-US
      creative: creative_D
      action: pause
      enforce_in: <30s

exclusions:
  - id: inventory_blocklist_claims
    author: legal@client.example
    rule:
      kind: creative_blocklist
      claims: ["before-and-after", "diagnose", "cure"]
      scope: all_channels

The live policy file is edited in the dashboard — a diff preview appears before save, and the saved version is written to the same hash-chained ledger the bid decisions use, so an auditor can correlate which policy a bid was evaluated underwith the bid's policy_version field.

Who can review and override

Four policy roles. One ledger.

Every action the agent takes is attributable to a named policy role. Nothing happens off-ledger, and nothing happens out-of-policy.

By role, by action

Roadmap tie-in

When the live log ships, this page stays true.

Every decision shape, every field name, every decision value on this page is lifted from the same vocabulary the live audit-log work uses. When the live ledger lands, every row shown on this page will be recoverable in one click — no copy edits needed.

  • Decision values match BID / HOLD / ROTATE.
  • Field names match ts / channel / campaign.
  • Hash chain and replay story match the home page verbatim.

Try it on your ad account

See this ledger behind your own auctions.

We onboard customers in cohorts of five so each new account gets direct engineering attention for the first two weeks. Leave your email and we'll let you know when the next cohort opens.

Prefer a direct conversation? Email provespend@polsia.app and we'll route you to the founding engineer.

Cohort signup

We typically respond within two business days with a 15-minute walkthrough link and a copy of the bidding-policy template so you can read the policy.yaml structure before signing.

Pick every channel where you currently spend.

One email when a cohort opens. No newsletter, no drip.