@ssheleg/sheleg-dev 0.6.0 → 0.7.0

package/plugins/sheleg-dev/skills/ad-tracking/fixtures/README.md

@@ -0,0 +1,76 @@
+# Deduplication fixtures and the assertion pack
+
+**Copy this whole directory into your repository.** It is the executable half of what
+`SKILL.md` → *E-commerce* and `references/meta-linkedin.md` →
+*Deduplication with the Conversions API* state in prose: the three payloads one purchase
+produces, six assertions a correct emitter must pass, and a self-test that breaks the
+emitter one rule at a time so you can watch every assertion fail.
+
+```bash
+node assert-dedup-contract.mjs              # 6 assertions against the reference emitter
+node assert-dedup-contract.mjs --self-test  # break one rule at a time; every assertion must go red
+```
+
+No dependencies, no network, **no access token anywhere in this directory** — the sink
+collects what would have been sent.
+
+## Contents
+
+- [The fixtures](#the-fixtures)
+- [The assertions](#the-assertions)
+- [What each mutant deletes](#what-each-mutant-deletes)
+- [Why the browser side is read from the fixture](#why-the-browser-side-is-read-from-the-fixture)
+- [Placeholders](#placeholders)
+
+## The fixtures
+
+| File | What it is |
+|---|---|
+| `purchase-pixel-browser.json` | the four arguments of the browser call: `fbq('track', 'Purchase', custom_data, { eventID })` |
+| `purchase-capi-server.json` | the Conversions API request body the **webhook** sends for the same purchase |
+| `purchase-capi-from-thank-you-page.json` | the body a thank-you-page-sourced emitter sends for a session whose charge never cleared — **the payload that must never exist**, kept so the assertion can name it |
+
+The first two carry the same `event_id` and the byte-equal `event_name`, which is the
+contract. The third is the defect, recorded rather than described: it was produced by
+running the reference emitter with `webhook-sourced` removed.
+
+## The assertions
+
+| Assertion | What a wrong emitter does |
+|---|---|
+| `pixel-and-capi-carry-one-event-id` | generates an id per emission, so Meta counts one purchase twice |
+| `pixel-and-capi-carry-one-event-name` | sends `Purchase` from the browser and `purchase` from the server: a shared id that deduplicates nothing |
+| `no-purchase-reported-before-the-charge-cleared` | reports the purchase from the one place that cannot know the money moved |
+| `the-browser-event-is-kept` | drops the browser event, losing the click id, the consent state and the session |
+| `identifiers-reach-the-server-hashed` | puts the address itself in `user_data.em` |
+| `the-shipped-capi-fixture-is-what-a-correct-emitter-sends` | anything that changes the body — a ratchet, so the fixtures you copy are the reference output |
+
+## What each mutant deletes
+
+| Rule | The code it removes | The integration that ships without it |
+|---|---|---|
+| `shared-event-id` | reading the id written once at session creation | `crypto.randomUUID()` at each emission |
+| `exact-event-name` | the one `event_name` constant used by both sides | `'Purchase'` in the browser, a lowercased variant on the server |
+| `webhook-sourced` | the gate that keeps the thank-you page from reporting | fires the conversion where the redirect lands |
+| `keep-browser-event` | the pixel call | server-only, and blind to everything the browser carries |
+| `hashed-identifiers` | the SHA-256 of the identifier | hands the raw address to the wrapper, which hashes whatever it is given |
+
+## Why the browser side is read from the fixture
+
+`pixel-and-capi-carry-one-event-id` and `pixel-and-capi-carry-one-event-name` compare the
+server's output against `purchase-pixel-browser.json` rather than against the pixel call the
+same emitter just made. That is deliberate, and it is the correction of a first pass:
+reading both sides out of one emitter meant deleting `keep-browser-event` also turned those
+two assertions red, so neither the id rule nor the name rule was proven on its own. Two
+mechanisms that both explain a passing fixture leave both untested. The fixture is the
+browser's contract, held at a boundary the server does not control.
+
+`--self-test` fails if any rule has no fixture that isolates it, so this stays true.
+
+## Placeholders
+
+`usr_PLACEHOLDER_carol`, `prod_PLACEHOLDER_pro`, `fb.1.…PLACEHOLDERCLICKID`,
+`203.0.113.10` (a documentation address). The email is `placeholder@example.invalid` and
+the 64-hex string is its SHA-256 — a hash of a published placeholder, not of a person. No
+pixel id, no dataset id and no access token appear here: the token is a runtime secret and
+`references/performance-security.md` is where it belongs.

package/plugins/sheleg-dev/skills/ad-tracking/fixtures/assert-dedup-contract.mjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+// The assertions a correct purchase emitter must pass, and the proof that each one can
+// fail.
+//
+//   node assert-dedup-contract.mjs              # run them against the reference emitter
+//   node assert-dedup-contract.mjs --self-test  # break the emitter one rule at a time
+//
+// `--self-test` is what makes this evidence: for every assertion it deletes the rule whose
+// removal MUST turn that assertion red, and fails if the assertion still passes. It then
+// prints which fixture ISOLATES each rule — because two rules that both explain a passing
+// fixture mean neither is tested.
+//
+// The runner is duplicated from `stripe-billing/fixtures/assert-money-invariants.mjs` on
+// purpose. A reader installs one skill, not six, so a shared import would resolve to
+// nothing in the common case; this pack has to run from its own directory alone.
+//
+// No network, no filesystem writes, no clock, and no access token anywhere in this
+// directory — the sink collects what WOULD have been sent.
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import assert from 'node:assert/strict';
+import { createSink, createEmitter, RULES, EVENT_NAME } from './reference-emitter.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const fixture = (name) => JSON.parse(readFileSync(path.join(HERE, name), 'utf8'));
+
+const PIXEL_BROWSER = 'purchase-pixel-browser.json';
+const CAPI_SERVER = 'purchase-capi-server.json';
+const CAPI_FORBIDDEN = 'purchase-capi-from-thank-you-page.json';
+
+/** The purchase is read OUT of the fixture, so the values have one home. */
+function purchaseFrom(name, cleared) {
+  const event = fixture(name).data[0];
+  return {
+    conversionEventId: event.event_id,
+    value: event.custom_data.value,
+    currency: event.custom_data.currency,
+    contentIds: event.custom_data.content_ids,
+    numItems: event.custom_data.num_items,
+    externalId: event.user_data.external_id[0],
+    emailSha256: event.user_data.em[0],
+    // The raw address a wrong emitter would send instead. sha256 of this string is the
+    // `em` above, so the two fixtures are consistent and neither is a real person.
+    email: 'placeholder@example.invalid',
+    clientIpAddress: event.user_data.client_ip_address,
+    clientUserAgent: event.user_data.client_user_agent,
+    fbp: event.user_data.fbp,
+    fbc: event.user_data.fbc,
+    eventTime: event.event_time,
+    eventSourceUrl: event.event_source_url,
+    cleared,
+  };
+}
+
+/** Carol paid by card: the charge cleared, and the webhook says so. */
+const CLEARED = () => purchaseFrom(CAPI_SERVER, true);
+/** Bob chose a bank debit: the session completed, the money has not moved and may not. */
+const NOT_CLEARED = () => purchaseFrom(CAPI_FORBIDDEN, false);
+
+function harness(without = []) {
+  const sink = createSink();
+  return { sink, emitter: createEmitter(sink, { without }) };
+}
+
+/** The real sequence: the browser fires on the thank-you page, the webhook lands when it lands. */
+function runPurchase({ sink, emitter }, purchase) {
+  emitter.onThankYouPage(purchase);
+  if (purchase.cleared) emitter.onChargeCleared(purchase);
+  return sink;
+}
+
+export const INVARIANTS = [
+  {
+    id: 'pixel-and-capi-carry-one-event-id',
+    fixtures: [PIXEL_BROWSER, CAPI_SERVER],
+    states: 'one id, generated once and used by both sides, or the revenue counts twice',
+    breaks: ['shared-event-id'],
+    run({ sink, emitter }) {
+      runPurchase({ sink, emitter }, CLEARED());
+      // The browser side is read from the SHIPPED fixture rather than from the sink. That
+      // is deliberate: it keeps this assertion independent of whether the browser event
+      // fired at all, which is a different rule with its own fixture. Reading both sides
+      // out of one emitter is how the two got tangled on the first pass.
+      const pixelId = fixture(PIXEL_BROWSER)[3].eventID;
+      const serverId = sink.capi[0].data[0].event_id;
+      assert.equal(serverId, pixelId,
+        `the pixel carries ${pixelId} and the server sent ${serverId} — nothing will ever `
+        + 'deduplicate these two, and one purchase is two conversions');
+    },
+  },
+  {
+    id: 'pixel-and-capi-carry-one-event-name',
+    fixtures: [PIXEL_BROWSER, CAPI_SERVER],
+    states: 'Meta compares the name as well as the id, and the name is the half that is missed',
+    breaks: ['exact-event-name'],
+    run({ sink, emitter }) {
+      runPurchase({ sink, emitter }, CLEARED());
+      const pixelName = fixture(PIXEL_BROWSER)[1];   // the browser contract, not the sink
+      const serverName = sink.capi[0].data[0].event_name;
+      assert.equal(serverName, pixelName,
+        `'${pixelName}' in the browser and '${serverName}' on the server: a shared id `
+        + 'deduplicates nothing when the names differ');
+      assert.equal(serverName, EVENT_NAME);
+    },
+  },
+  {
+    id: 'no-purchase-reported-before-the-charge-cleared',
+    fixtures: [CAPI_FORBIDDEN],
+    states: 'the thank-you page has no idea whether the money moved, so it reports nothing',
+    breaks: ['webhook-sourced'],
+    run({ sink, emitter }) {
+      runPurchase({ sink, emitter }, NOT_CLEARED());
+      assert.equal(sink.capi.length, 0,
+        'a Conversions API purchase was sent for a charge that has not cleared — this is '
+        + 'the event that exists for every session that reached the page and for no refund');
+      assert.equal(sink.pixel.length, 0,
+        'a Purchase pixel fired for a session whose payment is still pending');
+      assert.notDeepEqual(sink.capi[0], fixture(CAPI_FORBIDDEN));
+    },
+  },
+  {
+    id: 'the-browser-event-is-kept',
+    fixtures: [PIXEL_BROWSER],
+    states: 'the browser event stays and stays subordinate — it carries the click ids',
+    breaks: ['keep-browser-event'],
+    run({ sink, emitter }) {
+      runPurchase({ sink, emitter }, CLEARED());
+      assert.equal(sink.pixel.length, 1,
+        'no browser event fired: the click id, the consent state and the session are lost, '
+        + 'and only the browser had them');
+      assert.equal(sink.pixel[0][0], 'track');
+    },
+  },
+  {
+    id: 'identifiers-reach-the-server-hashed',
+    fixtures: [CAPI_SERVER],
+    states: 'advanced matching sends hashes, never the address itself',
+    breaks: ['hashed-identifiers'],
+    run({ sink, emitter }) {
+      runPurchase({ sink, emitter }, CLEARED());
+      const userData = sink.capi[0].data[0].user_data;
+      for (const value of userData.em) {
+        assert.match(value, /^[0-9a-f]{64}$/,
+          `user_data.em carried ${JSON.stringify(value)} — a raw identifier, not a sha256`);
+      }
+      assert.ok(!JSON.stringify(userData).includes('@'),
+        'user_data carries something with an @ in it');
+    },
+  },
+  {
+    id: 'the-shipped-capi-fixture-is-what-a-correct-emitter-sends',
+    fixtures: [CAPI_SERVER, PIXEL_BROWSER],
+    states: 'the fixtures are the reference output, byte for byte — not an illustration',
+    // Broad by construction: it compares the whole body, so every rule that changes any
+    // field turns it red. It is here so a reader can trust the fixtures they copy.
+    breaks: ['shared-event-id', 'exact-event-name', 'hashed-identifiers', 'keep-browser-event'],
+    run({ sink, emitter }) {
+      runPurchase({ sink, emitter }, CLEARED());
+      assert.deepEqual(sink.capi[0], fixture(CAPI_SERVER));
+      assert.deepEqual(sink.pixel[0], fixture(PIXEL_BROWSER));
+    },
+  },
+];
+
+// ------------------------------------------------------------------------- runners
+
+async function runOne(invariant, without) {
+  const context = harness(without);
+  try {
+    await invariant.run(context);
+    return null;
+  } catch (error) {
+    return error.message.split('\n')[0];
+  }
+}
+
+async function runAll() {
+  let failed = 0;
+  for (const invariant of INVARIANTS) {
+    const why = await runOne(invariant, []);
+    if (why) {
+      failed += 1;
+      console.error(`FAIL ${invariant.id}\n     ${why}`);
+    } else {
+      console.log(`pass ${invariant.id} — ${invariant.states}`);
+    }
+  }
+  if (failed) {
+    console.error(`\n${failed} of ${INVARIANTS.length} deduplication assertions failed`);
+    return 1;
+  }
+  console.log(`\nOK: ${INVARIANTS.length} deduplication assertions hold against the emitter`);
+  return 0;
+}
+
+async function selfTest() {
+  const problems = [];
+  const matrix = [];
+  for (const invariant of INVARIANTS) {
+    const broke = [];
+    for (const rule of RULES) {
+      if (await runOne(invariant, [rule])) broke.push(rule);
+    }
+    matrix.push({ id: invariant.id, broke });
+    const expected = [...invariant.breaks].sort().join(', ');
+    const measured = [...broke].sort().join(', ');
+    if (expected !== measured) {
+      problems.push(`${invariant.id}: declares breaks [${expected || '-'}], measured [${measured || '-'}]`);
+    }
+    if (broke.length === 0) {
+      problems.push(`${invariant.id}: no mutant breaks it — the assertion cannot fail`);
+    }
+  }
+
+  const width = Math.max(...matrix.map((row) => row.id.length));
+  console.log(`\nassertion x mutant — ${RULES.length} mutants, `
+    + 'and which removed rule turns each assertion red\n');
+  for (const row of matrix) {
+    console.log(`  ${row.id.padEnd(width)}  ${row.broke.join(', ') || '(nothing)'}`);
+  }
+
+  console.log('\nisolation — the fixture that separates each rule from every other\n');
+  for (const rule of RULES) {
+    const isolating = matrix.filter((row) => row.broke.length === 1 && row.broke[0] === rule);
+    if (isolating.length) {
+      console.log(`  ${rule.padEnd(20)} ${isolating.map((r) => r.id).join(', ')}`);
+    } else {
+      problems.push(`no fixture isolates ${rule} — every assertion it breaks is also broken `
+        + 'by another rule, so neither is proven');
+    }
+  }
+
+  if (problems.length) {
+    console.error(`\nFAIL: ${problems.length} problem(s) with the assertion pack itself`);
+    for (const p of problems) console.error(`  - ${p}`);
+    return 1;
+  }
+  console.log(`\nOK: ${INVARIANTS.length} assertions, each watched failing; `
+    + `${RULES.length} rules, each isolated by a fixture`);
+  return 0;
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const mode = process.argv.includes('--self-test') ? selfTest : runAll;
+  process.exit(await mode());
+}

package/plugins/sheleg-dev/skills/ad-tracking/fixtures/manifest.json

@@ -0,0 +1,75 @@
+{
+  "skill": "ad-tracking",
+  "assertionPack": "assert-dedup-contract.mjs",
+  "referenceHandler": "reference-emitter.mjs",
+  "runbook": "README.md",
+  "note": "The single home of the invariant -> fixture -> document mapping. test/validate.py in this repository reads it: every fixture must be claimed by a row, every row's fixtures must exist, and every claiming document must still carry its phrase, name the invariant id, and name a path under fixtures/. A claim whose fixture is gone and a fixture nobody claims are both failures.",
+  "invariants": [
+    {
+      "id": "pixel-and-capi-carry-one-event-id",
+      "isolates": "shared-event-id",
+      "fixtures": ["purchase-pixel-browser.json", "purchase-capi-server.json"],
+      "claimedBy": [
+        {
+          "document": "SKILL.md",
+          "phrase": "carry the SAME `event_id` / `transaction_id`, or both are counted."
+        }
+      ]
+    },
+    {
+      "id": "pixel-and-capi-carry-one-event-name",
+      "isolates": "exact-event-name",
+      "fixtures": ["purchase-pixel-browser.json", "purchase-capi-server.json"],
+      "claimedBy": [
+        {
+          "document": "references/meta-linkedin.md",
+          "phrase": "**Two fields must match, not one.**"
+        }
+      ]
+    },
+    {
+      "id": "no-purchase-reported-before-the-charge-cleared",
+      "isolates": "webhook-sourced",
+      "fixtures": ["purchase-capi-from-thank-you-page.json"],
+      "claimedBy": [
+        {
+          "document": "SKILL.md",
+          "phrase": "**A purchase is not a browser event, and that decides where it comes from.**"
+        }
+      ]
+    },
+    {
+      "id": "the-browser-event-is-kept",
+      "isolates": "keep-browser-event",
+      "fixtures": ["purchase-pixel-browser.json"],
+      "claimedBy": [
+        {
+          "document": "SKILL.md",
+          "phrase": "**The browser event stays, and it stays subordinate.**"
+        }
+      ]
+    },
+    {
+      "id": "identifiers-reach-the-server-hashed",
+      "isolates": "hashed-identifiers",
+      "fixtures": ["purchase-capi-server.json"],
+      "claimedBy": [
+        {
+          "document": "references/meta-linkedin.md",
+          "phrase": "SHA-256 does **not** make a value safe to send"
+        }
+      ]
+    },
+    {
+      "id": "the-shipped-capi-fixture-is-what-a-correct-emitter-sends",
+      "isolates": null,
+      "fixtures": ["purchase-capi-server.json", "purchase-pixel-browser.json"],
+      "claimedBy": [
+        {
+          "document": "references/meta-linkedin.md",
+          "phrase": "the fixtures are the reference output rather than an illustration"
+        }
+      ]
+    }
+  ]
+}

package/plugins/sheleg-dev/skills/ad-tracking/fixtures/purchase-capi-from-thank-you-page.json

@@ -0,0 +1,32 @@
+{
+  "data": [
+    {
+      "event_name": "Purchase",
+      "event_time": 1767312000,
+      "event_id": "evtid_PLACEHOLDER_purchase_bob",
+      "event_source_url": "https://example.invalid/after",
+      "action_source": "website",
+      "user_data": {
+        "em": [
+          "34aeb9fb3be8b407bdd0beb712d571974bbddbb5bfc0e41cb666331ee5fcc47b"
+        ],
+        "external_id": [
+          "usr_PLACEHOLDER_bob"
+        ],
+        "client_ip_address": "203.0.113.10",
+        "client_user_agent": "Mozilla/5.0 (PLACEHOLDER user agent)",
+        "fbp": "fb.1.1767312000.9876543210",
+        "fbc": "fb.1.1767312000.PLACEHOLDERCLICKID"
+      },
+      "custom_data": {
+        "value": 29,
+        "currency": "USD",
+        "content_ids": [
+          "prod_PLACEHOLDER_pro"
+        ],
+        "content_type": "product",
+        "num_items": 1
+      }
+    }
+  ]
+}

package/plugins/sheleg-dev/skills/ad-tracking/fixtures/purchase-capi-server.json

@@ -0,0 +1,26 @@
+{
+  "data": [
+    {
+      "event_name": "Purchase",
+      "event_time": 1767398400,
+      "event_id": "evtid_PLACEHOLDER_purchase_carol",
+      "event_source_url": "https://example.invalid/after",
+      "action_source": "website",
+      "user_data": {
+        "em": ["34aeb9fb3be8b407bdd0beb712d571974bbddbb5bfc0e41cb666331ee5fcc47b"],
+        "external_id": ["usr_PLACEHOLDER_carol"],
+        "client_ip_address": "203.0.113.10",
+        "client_user_agent": "Mozilla/5.0 (PLACEHOLDER user agent)",
+        "fbp": "fb.1.1767398400.1234567890",
+        "fbc": "fb.1.1767398400.PLACEHOLDERCLICKID"
+      },
+      "custom_data": {
+        "value": 29.0,
+        "currency": "USD",
+        "content_ids": ["prod_PLACEHOLDER_pro"],
+        "content_type": "product",
+        "num_items": 1
+      }
+    }
+  ]
+}

package/plugins/sheleg-dev/skills/ad-tracking/fixtures/purchase-pixel-browser.json

@@ -0,0 +1,12 @@
+[
+  "track",
+  "Purchase",
+  {
+    "value": 29.0,
+    "currency": "USD",
+    "content_ids": ["prod_PLACEHOLDER_pro"],
+    "content_type": "product",
+    "num_items": 1
+  },
+  { "eventID": "evtid_PLACEHOLDER_purchase_carol" }
+]

package/plugins/sheleg-dev/skills/ad-tracking/fixtures/reference-emitter.mjs

@@ -0,0 +1,129 @@
+// A purchase emitter that satisfies the deduplication contract this skill states, and the
+// same emitter with one rule removed at a time.
+//
+// Two call sites, and which one may report a purchase is the whole invariant:
+//
+//   onChargeCleared(purchase)  <- the webhook handler, the only place that knows the money
+//                                 moved. Sends the Conversions API event.
+//   onThankYouPage(purchase)   <- the browser. Fires the pixel with the id the server will
+//                                 reuse, and reports nothing on its own authority.
+//
+// `without: ['shared-event-id']` and friends delete the lines a generated integration
+// routinely omits; `fixtures/README.md` shows the code each flag removes. Nothing here
+// reaches the network — the sink collects what WOULD have been sent, which is what the
+// assertions read. No access token appears in this directory at all.
+
+export const RULES = Object.freeze([
+  'shared-event-id',
+  'exact-event-name',
+  'webhook-sourced',
+  'keep-browser-event',
+  'hashed-identifiers',
+]);
+
+/** Meta compares `event_name` as well as the id, and it is the half that gets missed. */
+export const EVENT_NAME = 'Purchase';
+
+export function createSink() {
+  return { pixel: [], capi: [] };
+}
+
+function customData(purchase) {
+  return {
+    value: purchase.value,
+    currency: purchase.currency,
+    content_ids: purchase.contentIds,
+    content_type: 'product',
+    num_items: purchase.numItems,
+  };
+}
+
+export function createEmitter(sink, options = {}) {
+  const without = new Set(options.without || []);
+  for (const rule of without) {
+    if (!RULES.includes(rule)) throw new Error(`unknown rule: ${rule}`);
+  }
+  const has = (rule) => !without.has(rule);
+  let generated = 0;
+
+  /** One id, generated once at session creation, carried by both sides. */
+  function eventIdFor(purchase) {
+    if (has('shared-event-id')) return purchase.conversionEventId;
+    generated += 1;
+    return `evtid_generated_at_emission_${generated}`;
+  }
+
+  function eventNameFor(side) {
+    if (has('exact-event-name')) return EVENT_NAME;
+    // The trap: an id that matches and a name that does not deduplicates nothing.
+    return side === 'server' ? EVENT_NAME.toLowerCase() : EVENT_NAME;
+  }
+
+  function userData(purchase) {
+    const identifiers = has('hashed-identifiers')
+      ? { em: [purchase.emailSha256], external_id: [purchase.externalId] }
+      : { em: [purchase.email], external_id: [purchase.externalId] };
+    return {
+      ...identifiers,
+      client_ip_address: purchase.clientIpAddress,
+      client_user_agent: purchase.clientUserAgent,
+      fbp: purchase.fbp,
+      fbc: purchase.fbc,
+    };
+  }
+
+  function capiBody(purchase) {
+    return {
+      data: [{
+        event_name: eventNameFor('server'),
+        event_time: purchase.eventTime,
+        event_id: eventIdFor(purchase),
+        event_source_url: purchase.eventSourceUrl,
+        action_source: 'website',
+        user_data: userData(purchase),
+        custom_data: customData(purchase),
+      }],
+    };
+  }
+
+  return {
+    /** The webhook handler. `cleared` is the provider's word, not the browser's. */
+    onChargeCleared(purchase) {
+      if (purchase.cleared !== true) {
+        // Reached only by a caller that guessed. The gate below is the one that matters.
+        return { sent: false, why: 'the charge has not cleared' };
+      }
+      sink.capi.push(capiBody(purchase));
+      return { sent: true };
+    },
+
+    /**
+     * The thank-you page. It fires the pixel and NOTHING ELSE: a browser cannot know
+     * whether the charge cleared, and for an async method it usually has not.
+     */
+    onThankYouPage(purchase) {
+      if (!has('webhook-sourced')) {
+        // The defect: reporting the purchase from the one place with no idea whether the
+        // money moved. `purchase-capi-from-thank-you-page.json` is what this sends.
+        sink.capi.push(capiBody(purchase));
+      }
+      if (has('webhook-sourced') && purchase.cleared !== true) {
+        // Not even the pixel: a Purchase fired here exists for every session that reached
+        // the page, including the ones that never paid.
+        return { fired: false, why: 'the charge has not cleared' };
+      }
+      if (!has('keep-browser-event')) {
+        // The other direction: dropping the browser event loses the click ids, the consent
+        // state and the session that only the browser carries.
+        return { fired: false, why: 'browser event removed' };
+      }
+      sink.pixel.push([
+        'track',
+        eventNameFor('browser'),
+        customData(purchase),
+        { eventID: eventIdFor(purchase) },
+      ]);
+      return { fired: true };
+    },
+  };
+}

package/plugins/sheleg-dev/skills/ad-tracking/references/meta-linkedin.md

@@ -100,7 +100,10 @@ export function setFbAdvancedMatching(data: { em?: string; fn?: string }) {
 Advanced Matching is the one place a tracking integration can breach Meta's terms
 by accident, because the wrapper accepts whatever you hand it and hashes it
 without judgement. SHA-256 does **not** make a value safe to send: hashing is a
-matching mechanism, not a permission.
+matching mechanism, not a permission. That the wrapper receives a hash at all is checkable:
+`identifiers-reach-the-server-hashed` in `fixtures/assert-dedup-contract.mjs` requires every
+`user_data.em` entry to be 64 hex characters and refuses anything with an `@` in it. What may
+be hashed in the first place is the table below, and no assertion decides it.
 
 Meta's Business Tools Terms prohibit sharing data that "includes or is based on"
 any of these, and the prohibition covers the Pixel, the Conversions API, the
@@ -184,6 +187,15 @@ the server event usually arrives first, and this method then does nothing. Use
 Neither method deduplicates within a single source: two pixel fires of the same
 purchase are two conversions no matter what.
 
+**Proved, not asserted.** `fixtures/purchase-pixel-browser.json` and
+`fixtures/purchase-capi-server.json` are the two payloads one purchase produces, and
+`fixtures/assert-dedup-contract.mjs` compares them: `pixel-and-capi-carry-one-event-name`
+fails an emitter that sends `Purchase` from the browser and a lowercased variant from the
+server, which is the half of this contract that gets missed. The shape itself is a ratchet —
+`the-shipped-capi-fixture-is-what-a-correct-emitter-sends` requires the emitted body to equal
+the fixture byte for byte, so **the fixtures are the reference output rather than an
+illustration**.
+
 Source: [Deduplicate pixel and Conversions API
 events](https://developers.facebook.com/docs/marketing-api/conversions-api/deduplicate-pixel-and-server-events),
 read 2026-08-16.