Search ads run a keyword auction over a campaign catalog for a query: match (broad / phrase / exact), exclude on negative keywords, drop invalid bids, rank by ad-rank, and clear each slot at a price capped by the winner's max CPC. Module: wal-sh.adtech.search-ads.core (pure) + ...browser (DOM).

ORACLE: src/wal_sh/adtech/search_ads/core.cljc (pure), browser.cljs (window._searchAds).

Behavioral guarantees:

• Totality: every public fn returns; no exceptions on adversarial inputs.
• Determinism: pure on inputs; no rand, no now, no env reads in core.
• Monotonicity (in bid): bid-raise on a campaign that already ranked → same-or-better position.
• Idempotency: (= (auction q o) (auction q o)) ∀ q, o.
• Render safety: all user-controlled strings (headline, description, display-url, campaign-id) are HTML-escaped before injection.

Input / output domains:

• query: string (nil/non-string/empty → []).
• :max-cpc: finite double ≥ 0. Inf / NaN / negative → campaign dropped.
• :quality-score (catalog field, JS-compat): integer ∈ [0,10]; OOR → dropped.
• :reserve-price, :epsilon: positive doubles; defaults 0.01.
• :max-results: positive int; default 3.

Spec note (tightening): PLANS.org defines quality-score as a 3-factor composite (CTR × landing-page × relevance). The JS catalog stores it as a single int 1..10. We expose BOTH: the quality-score fn for the composite (per PLANS), and the integer :quality-score field on the campaign row (per JS). The ad-rank calc uses the integer field for JS-parity, not the composite. Documented for downstream callers.

Pure (core.cljc):

Browser surface: window._searchAds (set by browser/init!) exposes:

{ campaigns : Array,                       // clj->js campaign rows
  query     : (q [, max]) → Array,         // run auction, return JS array
  render    : (results, container-id) → DOMElement,
  show      : (q) → Array,                 // auction + render combined
  escapeHtml: (s) → String,
  keywords  : (s) → Array<String> }

• ∀ valid opts, query: (auction query opts) is a vector? (totality).
• ∀ entry e ∈ slate: 0 ≤ :actual-cpc e ≤ :max-cpc (:campaign e) (Vickrey cap).
• ∀ permutations π of :campaigns: (auction q (assoc opts :campaigns (π cs))) returns IDs in the same order (deterministic tiebreaks: [-ad-rank, -max-cpc, :campaign-id]).
• ∀ campaign c: raising (:max-cpc c) never demotes c from a previously-occupied slot (monotonic in bid).
• Idempotency: pure; same inputs always return = outputs (no atoms, no time, no rand).

Failure modes the implementation must reject or handle safely. Each row maps input → expected behavior → the property test that proves it.

Disambiguation: "negative keywords" in search-ads parlance are EXCLUDE filters (advertiser opts out of queries containing a term). They are not negative test cases. This catalog covers genuine adversarial / boundary inputs.

Decisions flagged:

• Single bid with QS=0: valid-bid? accepts QS=0 (matches JS) but ad-rank = 0, so the entry is filtered before sorting. Effectively shown only if reserve also allows; in practice never shown. JS behaviour preserved.
• reserve-price semantics: inclusive of equal; :max-cpc > reserve= passes; only strictly-below is rejected. Matches the (>)= predicate in the implementation; documented in the auction docstring.
• Negative-keyword match: broad (substring), not phrase. A negative keyword "free" blocks queries "free trial" AND "freelance". Future improvement: emit phrase negatives if false-positives accumulate.

• The per-slot clearing price capped at the winner's own bid is the Vickrey second-price rule (Vickrey 1961); the ad-rank ordering with quality-score weighting is the generalized second-price auction of Edelman, Ostrovsky and Schwarz (Edelman, Ostrovsky, and Schwarz 2007).
• Google's 2019 move to first-price (Google Ad Manager Team 2019) is the industry direction this module deliberately does not follow; the :actual-cpc ≤ :max-cpc invariant is the second-price posture.

• ab-engine/spec.org: the auction-disclosure experiment (exp-104) that surfaces bid arithmetic to the reader.
• pricing-engine/spec.org: the sibling module where a floor binds on a price; here the reserve binds on a bid.
• pocket-es-integration/spec.org: the search surface the auctioned slate is interleaved into.
• ORACLE:
  • src/wal_sh/adtech/search_ads/core.cljc (pure)
  • src/wal_sh/adtech/search_ads/browser.cljs (window._searchAds)
  • test/wal_sh/adtech/search_ads/core_prop_test.cljc (properties)

• Phrase negatives. Broad (substring) negative-keyword matching blocks "freelance" on a "free" negative; a phrase negative type is the known fix if false positives accumulate.
• Composite vs integer quality score. ad-rank uses the integer catalog field for JS parity; switching to the 3-factor composite would change every ranking and is a breaking change for downstream callers.