feat: campaign matcher source, the first fan-in over every campaigns asset

[aaaaahaaaaa]

Summary

CampaignMatcher is a new interloper-assets source with one asset, campaign_matches,
declaring relations={"campaigns": il.Relation("asset", "*.campaigns", many=True)}: a many-valued
wildcard relation that binds every campaigns asset a DAG holds, from any source, without either
connector knowing the matcher exists. It is the first asset in the codebase to fan a whole class of
upstreams into one downstream node.

The matcher is a naive but working one. Each campaign name is reduced to a normalised key
(Unicode folded, case-folded, punctuation dropped, whitespace collapsed), optionally through a
key_pattern on the source, a regular expression whose key group selects the part of the name that
identifies the campaign under a naming convention. Campaigns sharing a key share a match_id, a
uuid5 of the key so it is stable across daily snapshots and runs. A similarity_threshold below
1.0 also merges keys that merely resemble each other (difflib ratio), and every row reports its
own similarity to the canonical key. Each row names its platform (the connector key) and account
(the connector's discriminator), since campaign ids collide across platforms. Since connectors name
the same fields differently (Facebook and Snapchat: id/name; TikTok: campaign_id/campaign_name),
a small helper tries the spellings in turn and falls back

The fan-in is declared exactly once, on the asset's relations= kwarg; wiring it into a DAG is
ordinary construction (il.DAG(fb, tt, matcher)), an explicit bind("campaigns", ...), or a
manifest where each connector overrides its campaigns asset to materializable: false and
campaign_matches names both by {ref: ...}. docs/guide/dependencies.md ("Many upstreams" /
"Fan-in across sources") and examples/campaign_matcher.yaml cover both forms.

What was proven

A platform run built the manifest end to end: two connectors (Facebook, TikTok) each held one
campaigns asset, both bound by name into the matcher's campaigns relation with no shared
vocabulary beyond the wildcard key. Both connector assets ran read-only
(materializable: false); only the matcher's own asset actually materialized. The run produced
four rows, one per upstream campaign, each naming its platform and account. The manifest (examples/campaign_matcher.yaml) builds into a runnable DAG from a
YAML file with no Python.

Fixes found by the run

• CSV and file destinations now signal a missing scope as DataNotFoundError.
  CSVDestination already raised it; FileDestination._read_scope still raised a bare
  FileNotFoundError, so the "an upstream leg with no data resolves to None" contract
  (asset/base.py, matching on DataNotFoundError) never engaged for a file-backed destination.
  Both now agree.
• The matcher reads both campaign field spellings. The first version read only id/name; TikTok's campaign_id/campaign_name schema produced empty matches. _first
  now tries both spellings for id and name.
• Dev seed binds the demo job target by relation name, matching the platform's by-name wiring
  instead of the retired (type, slot) shape, so make dev builds again.

Stack

Phase 3 of the relation model. Phases 1 (#321, core) and 2 (#323, platform) are merged, and this
branch is rebased onto main with main as its base: the commit list is the matcher work alone.
Phase 4 (app, #325) follows, stacked on this one; retarget it to main once this merges.

Verification

• uv run --frozen ruff check: all checks passed.
• uv run --frozen ty check: all checks passed.
• uv run --frozen pytest -q: 2761 passed, 0 failed
  (interloper-core 1476, interloper-db 452, interloper-api 388, interloper-google-cloud 123,
  interloper-scheduler 107, interloper-assets 96, interloper-pandas 37, interloper-slack 23,
  interloper-agent 17, interloper-toolkit 16, interloper-mcp 8, interloper-k8s 8,
  interloper-app 6, interloper-docker 4).

Follow-ups

• DatabaseDestination._read_scope has no existence check at all (unlike CSV and file); it needs a
  driver-level probe rather than a path check, and is left for its own change.
• The run summary's denominator counts read-only nodes: runner/state.py:160 divides by
  len(self.dag.operations) (every operation, materializable or not), while :325 marks read-only
  operations SKIPPED rather than QUEUED. A fan-in run over two read-only connectors and one
  materializing matcher reports "1/3 succeeded" even when everything that could run did.
• A CI guard that builds every examples/*.yaml (construct the DAG, don't execute it) would have
  caught the manifest's earlier unquoted ${VAR} YAML error before review.
• _first's falsy fallback ("" treated the same as absent) is pinned by a test; whether an empty
  string should count as "no match" the way None does is worth a second look.
• Only facebook_ads, snapchat_ads and tiktok_ads ship a campaigns entity today; seven more
  connectors carry campaign ids only inside stats reports and six carry none. Coverage is the
  next step, not the matcher.

By Digitl

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!