Skip to content

Layer-2 metric: claim→claim data lineage (input_claims) - #27

Merged
nyashkn merged 3 commits into
mainfrom
claude/session-03914w
Jul 23, 2026
Merged

nyashkn merged 3 commits into
mainfrom
claude/session-03914w

Conversation

@nyashkn

@nyashkn nyashkn commented Jul 22, 2026

Copy link
Copy Markdown
Owner

What

Adds a worked example of a derived metric — one whose inputs are the values of upstream claims, not raw rows — and wires the Hamilton adapter to record the claim→claim data lineage the gate schema already models (input_claims, T29).

This lands the one salvageable nugget from #6 on a live edge. The rest of #6 is superseded by item 7 (the DAG backward walk is the lineage capture, and better — it's override-aware), and its AST-reject-rogue-I/O half conflicts with the "surface, never block" doctrine (the registered_input→payload downgrade already gives the semantic guarantee).

The edge a flat DAG can't express

The existing growth_demo metrics (blended_cac, demo_mer, naive_cac) are a flat layer — siblings over shared transforms, each tracing back to data. A Layer-2 metric consumes other metrics' claim values:

arpu         (DEMO-D-013) ─┐
                           ├─ cac_payback_ratio  (Layer 2, DEMO-D-020)
blended_cac  (DEMO-D-010) ─┘

A derived metric has no live input rows of its own, so it can't earn a row fingerprint — it lands as payload provenance. Without a claim→claim edge that leaves it orphaned. input_claims is the provenance it carries in place of extracted rows.

Changes

examples/growth_demo/dag.py

  • arpu (DEMO-D-013) — a second Layer-1 base metric (revenue / new customers).
  • cac_payback_ratio (DEMO-D-020) — Layer-2: arpu / blended_cac; kwargs bind to the two upstream claim nodes.

integrations/hamilton/adapter.py

  • Track node_name → emitted-claim RecordRef per run. When a metric node's kwargs are upstream claim-emitting nodes (Hamilton binds a kwarg to the node of the same name), record those claims as input_claims. Topological execution guarantees the upstream refs exist by the time the node runs. Populates the existing schema field (check_input_claims_exist-enforced) — nothing new on the record type.
  • Note: the edge lives on input_claims, not cites — cites is knowledge-provenance only (research/skill_use), and the gate rejects a claim there.

Tests — tests/integrations/test_layered_metrics.py

  • Layer-2 claim's input_claims == {arpu_rid, cac_rid}; cites == [].
  • data_fingerprint_source == "payload" on the derived metric vs registered_input on its Layer-1 source arpu — the contrast is the point.
  • Ground-truth identity: cac_payback_ratio == (revenue / new_customers) / cac.
  • Guard: flat sibling metrics declare no input_claims (adapter doesn't over-attach).

918 passed, 1 deselected; ruff clean on touched files.

Follow-up this unlocks

With claim→claim edges present, the republish guard's question extends from "was this exact claim refuted?" to "does this claim derive from anything refuted?" — refutation contagion, now a real graph traversal rather than an unexpressible one. Left as a separate change.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Joez4MiYjd6owPcRQNcKrv


Generated by Claude Code

claude added 3 commits July 22, 2026 23:36
Adds a worked example of a derived metric — one whose inputs are the values
of upstream claims, not raw rows — and wires the adapter to record the
claim->claim data lineage the gate schema already models (input_claims, T29).

growth_demo/dag.py
  * arpu (DEMO-D-013): a second Layer-1 base metric.
  * cac_payback_ratio (DEMO-D-020): a Layer-2 metric = arpu / blended_cac.
    Its kwargs bind to the two upstream claim nodes, so it has no live input
    rows of its own.

hamilton/adapter.py
  * track node_name -> emitted claim RecordRef per run; when a metric node's
    kwargs are upstream claim-emitting nodes (Hamilton binds a kwarg to the
    node of the same name), record those claims as input_claims. Topological
    execution guarantees the upstream refs exist by the time the node runs.

This populates issue #6's salvageable nugget on a live edge: a derived metric
lands as payload provenance (no row fingerprint to earn) yet is not orphaned —
it traces back to the claims it was computed from. The reconciliation/republish
machinery now has a claim->claim graph to traverse (refutation contagion is the
natural follow-up).

Tests (tests/integrations/test_layered_metrics.py): the Layer-2 claim's
input_claims == {arpu_rid, cac_rid} and cites == [] (cites is knowledge-only);
payload fingerprint on the derived metric vs registered_input on its Layer-1
sources; ground-truth identity payback == (revenue/new_customers)/cac; and a
guard that flat sibling metrics declare no input_claims. 918 passed.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Joez4MiYjd6owPcRQNcKrv
…e DAG

Adds catalog([modules]) — the interface an ephemeral analyst agent reads to
know what measures it can stand on before authoring a new one. Built purely
from @tag metadata + the compiled dependency graph (no execution, no data).

integrations/hamilton/catalog.py
  * MeasureSpec: per ik_emit="metric" node — measure name (what you reference
    in a signature to reuse it), the claim_id it emits (explicit or minted
    identically to the adapter), metric_field, grain, filters, statement, tier,
    kind (base|derived), direct_upstream, and derives_from (the upstream deps
    that are themselves measures — the input_claims edges a derived measure
    carries).
  * Catalog: by_name / names / base() / derived() + raw external inputs.
  * format_catalog: the agent-readable brief.

This is the discovery half of "leverage the measures that are there": pair a
measure name from the catalog into a new node's signature and the adapter's
input_claims wiring gives you claim->claim provenance for free. Dimensions are
surfaced per-measure as grain/filters (not yet first-class).

Tests (tests/integrations/test_catalog.py): lists all 5 growth_demo measures
with ids/grain; flags cac_payback_ratio derived <- (arpu, blended_cac) and the
flat siblings base; proves the catalog's advertised claim_id equals the id a
run actually emits (no drift); readable render. 922 passed.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Joez4MiYjd6owPcRQNcKrv
…gonomics gap)

An analyst-agent E2E (discover from catalog -> compose a new derived measure ->
run over sample data -> verify provenance) confirmed the loop works: the agent
composed cac_inflation_ratio = naive_cac / blended_cac from catalog discovery
alone, and its emitted claim carried input_claims resolving to exactly the two
base measures. But it surfaced one real friction: the catalog told the agent
WHAT measures exist, not HOW to author a new tagged node — the ik_* contract
lived only in adapter docstrings, so the agent had to read adapter internals.

Closes that gap next to discovery:
  * MEASURE_TAG_REFERENCE — the @tag contract (each ik_* tag, required/optional,
    one-line description).
  * authoring_guide() — renders the contract plus the composition rule that
    matters most: reference an existing measure BY NAME in the new node's
    signature and the adapter records it as input_claims for free; only compose
    same-grain measures.
  * format_catalog(cat, authoring=True) — default render now appends the guide,
    so the one brief an agent reads covers both discovery and authoring.

Tests: authoring guide names the key tags + the by-name/input_claims/same-grain
rule; default render is self-contained and the opt-out is honored. 924 passed.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Joez4MiYjd6owPcRQNcKrv
@nyashkn
nyashkn merged commit d8c57d5 into main Jul 23, 2026
6 checks passed
@nyashkn
nyashkn deleted the claude/session-03914w branch July 23, 2026 00:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants