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 matching logic itself is a placeholder, documented as such in the module docstring: it
lower-cases and strips each upstream campaign's name into a canonical_name and always reports
similarity: 1.0. It exists only to prove the fan-in mechanics; a real fuzzy-matching strategy is
future work. Since different connectors name the same fields differently (Facebook: id/name;
TikTok: campaign_id/campaign_name), a small helper tries both spellings in turn and falls back
to an empty string rather than filtering a row that matches neither.

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 carrying the originating connector's source_key and
source_id. 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 placeholder matching logic first 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

Stacked on PR #323 (phase 2, platform relations by name). Base branch is
feat/relation-model-platform; retarget as the stack merges. Phase 4 (app) follows, stacked on
this one.

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 now, but if the
  placeholder matching logic outlives phase 3, it is worth revisiting whether an empty string
  should still count as "no match" the way None does.

By Digitl

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!