`nx_ad_meter.nx` source

1// nx_ad_meter.nx -- LIB: per-advertiser FIRST-PARTY outcome MEASUREMENT for the "Brought to you
2// by" performance ad engine (ADS-007, CALLOUT-004). The keystone that turns honest measurement
3// into a billable verdict. NO-FLOATING: composes the two DONE foundations -- conversions via
4// nx_ad_conversion (ADS-018: consent-gate -> bot-filter -> aggregate -> k-anon) and impressions
5// via nx_ad_botfilter (ADS-019) -- and reads the goal target + exceed multiple from the SOVEREIGN
6// STORE (ADS-006 schema: adgoal:/adpricing:), never TSV.
7//
8// THE VERDICT (per campaign-period, measured against THEIR chosen goal target):
9//   UNDER   result <  target                          -> downstream bill = $0
10//   PERFORM target <= result < target*exceed_mult      -> flat perform fee
11//   EXCEED  result >= target*exceed_mult               -> flat fee + ONE flat capped bonus
12//
13// HONEST-BILLING LAW MADE LOAD-BEARING: if the target or exceed_mult is not a real number yet
14// (PENDING-CENSUS / PENDING-COSPEC in the store -- figures are sponsor co-spec, ADS-005/ADS-001),
15// the meter returns UNMEASURABLE. "We cannot bill what we cannot measure" -- the default is no
16// charge, and a verdict requires real, store-resident figures. license_tier: ORIGINAL
17import "nx_ad_conversion.nx"
18import "nx_ad_botfilter.nx"
19import "nx_kanon.nx"
20import "nx_ad_store.nx"
21import "nx_syscalls.nx"
22
23const AM_UNMEASURABLE: i64 = 0 - 1
24const AM_UNDER:        i64 = 0
25const AM_PERFORM:      i64 = 1
26const AM_EXCEED:       i64 = 2
27
28// extract the tab-delimited field `fi` (0-based) of a store value and parse it as a non-negative
29// int. Returns -1 if the field is missing, empty, or NON-NUMERIC (e.g. "PENDING-CENSUS") -- the
30// signal that the figure is not yet set and the campaign is therefore UNMEASURABLE.
31func am_field_int(val: *u8, vlen: i64, fi: i64) -> i64 {
32    var i: i64 = 0
33    var f: i64 = 0
34    while f < fi {
35        if i >= vlen { return 0 - 1 }
36        if val[i] == (9 as u8) { f = f + 1 }
37        i = i + 1
38    }
39    if i >= vlen { return 0 - 1 }
40    var v: i64 = 0
41    var any: i64 = 0
42    var go: i64 = 1
43    while go == 1 {
44        if i >= vlen { go = 0 } else {
45            let c: i64 = val[i] as i64
46            if c == 9 { go = 0 } else {
47                if c >= 48 { if c <= 57 { v = v * 10 + (c - 48); any = 1; i = i + 1 } else { return 0 - 1 } } else { return 0 - 1 }
48            }
49        }
50    }
51    if any == 0 { return 0 - 1 }
52    return v
53}
54
55// goal target from the store: adgoal:<goal> = goal\tmetric\tTARGET\tperiod (field 2). -1 if PENDING/absent.
56func am_target_of(goal_key: *u8) -> i64 {
57    let pq: *i64 = sys_mmap(16) as *i64
58    let lq: *i64 = sys_mmap(16) as *i64
59    if ads_get(goal_key, pq, lq) != 1 { return 0 - 1 }
60    return am_field_int(pq[0] as *u8, lq[0], 2)
61}
62
63// exceed multiple from the store: adpricing:<goal> = goal\tperform_fee\tEXCEED_MULT\texceed_bonus\tcurrency
64// (field 2). -1 if PENDING/absent.
65func am_exceed_mult_of(price_key: *u8) -> i64 {
66    let pq: *i64 = sys_mmap(16) as *i64
67    let lq: *i64 = sys_mmap(16) as *i64
68    if ads_get(price_key, pq, lq) != 1 { return 0 - 1 }
69    return am_field_int(pq[0] as *u8, lq[0], 2)
70}
71
72// THE VERDICT. UNMEASURABLE unless BOTH target and exceed_mult are real (> 0). This is the honest-
73// billing guard: a PENDING figure (-1 / 0) can never yield a billable PERFORM/EXCEED.
74func am_verdict(result: i64, target: i64, exceed_mult: i64) -> i64 {
75    if target <= 0 { return AM_UNMEASURABLE }
76    if exceed_mult <= 0 { return AM_UNMEASURABLE }
77    if result < target { return AM_UNDER }
78    if result >= target * exceed_mult { return AM_EXCEED }
79    return AM_PERFORM
80}
81
82// RESULT for a conversion goal: the consented, bot-filtered, k-anon-floored count (ADS-018). A
83// count suppressed below the k-anon floor (-1) is treated as 0 measurable conversions -> UNDER,
84// never a charge for a campaign too small to measure honestly.
85func am_result_conversions(ev: *i64, m: i64, rules: *i64, nrules: i64, k: i64) -> i64 {
86    let r: i64 = cv_release(ev, m, rules, nrules, k)
87    if r < 0 { return 0 }
88    return r
89}
90
91// RESULT for a reach (impression) goal: the bot-filtered valid impression count (ADS-019).
92func am_result_impressions(ev: *i64, m: i64, rules: *i64, nrules: i64) -> i64 {
93    let ov: *i64 = sys_mmap(8) as *i64
94    let oi: *i64 = sys_mmap(8) as *i64
95    bf_tally(ev, m, rules, nrules, ov, oi)
96    return ov[0]
97}
nx_ad_meter.nx source

`nx_ad_meter.nx` source
