Compare evidence snapshots without turning missing rows into deletion claims

A record vanishes between two exports. Before opening an incident, ask what actually vanished: an entity, a source page, a field, or just a row in a supplied file? A useful snapshot comparison keeps those questions separate. Start with the narrow claim you can reproduce: these two submitted collections differ in these specific places. That gives a reviewer a concrete change list without inventing an explanation for the change.

I maintain the us-brand-evidence-snapshot-diff Actor. This walkthrough describes its published build 0.2.2, inspected on 16 October 2026. The example below is synthetic and reviewed against that contract; it was not executed for this article. AI-assisted drafting was followed by a separate factual and editorial review.

The input contract uses primarySide, a required primary collection, and an optional counterpart. Choose which side your primary collection represents. Matching uses your dedupeKey exactly; the Actor does not discover an identity across two differently named brands. This small example deliberately supplies only a before snapshot. Omitting the counterpart represents an empty after side. It is a compact way to inspect removal semantics, rather than a demonstration of a live brand disappearing.

{
  "schemaVersion": "1.1",
  "primarySide": "before",
  "primary": [
    {
      "dedupeKey": "brand-1",
      "brandName": "Example Brand",
      "country": "US"
    }
  ]
}

The expected interpretation is one removed submitted row. To compare two populated exports, add a nonempty counterpart array with the rows from the other side. An explicitly empty counterpart is invalid under this contract, so omission and invalid input must be handled separately. Each side accepts at most 50 rows, with unique keys within that side. A repeated key across sides identifies the pair to compare; a repeated key within one side is a validation problem.

For changed rows, inspect beforePresent and afterPresent alongside the values in the change record. A missing property and a present property with a value deserve different review notes. Do not substitute a generic null into every absent field before comparing: that preprocessing would erase the very distinction the report exposes.

Read counts with the added, removed, changed, and unchanged collections. Keep both original inputs beside the report. The before and after digests bind the respective normalized snapshots, while inputDigest and the version-specific report digests serve different scopes. Normalization includes NFC text and recursive object-key sorting; declared set-like fields are sorted and deduplicated. It does not make the before and after roles interchangeable.

Version 1.1 adds a decision envelope and separates the current report digest from a legacy report digest. Compare artifacts using the same schema version and digest purpose. A changed digest across two different report contracts is not evidence that the underlying source changed.

In a review pipeline, store the two input file identifiers, the submitted keys, the selected side, and the report together. Let a reviewer follow a removed key back to the export process before assigning a business meaning. An upstream filter, access change, or failed collection could produce the same apparent removal. Investigating that cause belongs outside this deterministic comparison.

The closed row schema and size limits also matter during integration: canonical input is capped at 256 KiB and an individual canonical row at 16 KiB. Oversize input fails rather than quietly dropping records. If your export exceeds those limits, define your own documented partition boundaries and preserve them with each result so a later reviewer can reconstruct which rows were compared.

On the observed FREE pricing tier, one result-found event costs $0.01 for the complete useful report or plan, rather than each input row. FREE is the tier name, not a promise of free execution. Automatic Actor-start pricing is also present at $0.005 per GB, with a minimum of one event. Check the Actor page and your account tier before running; this is not a fixed total invoice, and a failed or repeated run may still incur applicable charges.

To try this deliberately, open the Actor page, select build 0.2.2, and submit the JSON as input. Set an explicit spending ceiling appropriate to your account; for example, $0.05 is a ceiling, not a quoted run price or a guarantee of a delivered report. Save the returned run ID and verify its immutable build ID. A local timeout does not cancel the remote run: inspect that same run before considering another attempt. Read the completed run's Dataset report and its separate OUTPUT receipt together; structural output is not independent source verification.