Ripplecheck

Ripplecheck is a counterfactual schema migration compiler powered by the DataHub MCP Server. Paste breaking warehouse DDL and it projects the metadata graph, proves a bounded release policy, routes an executable migration DAG to owners, writes a hash-sealed decision capsule back to DataHub, and generates a merge-ready PR evidence pack.

It runs with no API key, no paid billing, no network, and no Python dependencies. A synthetic DataHub snapshot makes the judge path deterministic and fully offline. Live mode swaps in the official DataHub MCP Server without changing the orchestration path.

Hackathon category: Agents That Do Real Work

Why: Ripplecheck does more than retrieve or summarize metadata. It makes a release decision, compiles owner-assigned migration work and code artifacts, and persists the result for the next engineer or agent.

Live judge demo: https://ripplecheck-datahub.vercel.app

Run the judge path

python3 main.py web --host 127.0.0.1 --port 8000

Open http://127.0.0.1:8000, leave the default DDL unchanged, and click Compile migration plan.

ALTER TABLE warehouse.analytics.customer_360
RENAME COLUMN customer_tier TO loyalty_tier;

Expected output:

• release gate CLOSED with risk 10/10;
• 5 broken lineage edges across a dbt model, Airflow flow, ML model, and 2 dashboards;
• 4 failed policy rules, 1 ownership warning, and 80% owner coverage;
• exact source-to-consumer lineage paths through 2 hops;
• a 10-node zero-downtime execution DAG from freeze gate G0 to retirement approval G1;
• an exact 5-call DataHub MCP trace and hash-sealed writeback;
• a downloadable 6-file PR pack containing compatibility SQL, dbt contract YAML, a parity test, review evidence, owner routing, and a hash-addressed change capsule.

For recording, use the exact click-and-say demo runbook. It includes every click, screen state, narration line, timing, recovery step, architecture answer, and the requested tech-stack table in one document.

Judges can use the dedicated testing instructions, inspect the extracted generated examples, and review the project disclosures.

Real DataHub proof: the live transport was also verified end to end against DataHub OSS 1.6.0, the official showcase-ecommerce datapack, and mcp-server-datahub. It read 23 downstream assets and completed a real update_description writeback. See the reproducible live proof and machine-readable result.

Why this is not a generic blast-radius bot

A blast-radius bot ends with a list. Ripplecheck compiles a controlled migration:

1. Parse real DDL. Snowflake ALTER TABLE renames, drops, and type changes are accepted alongside natural language.
2. Ground the change. search and list_schema_fields resolve the exact DataHub entity, field, type, tags, and description.
3. Project the after-state. get_lineage and get_entities produce exact paths, predicted failure modes, ownership coverage, critical consumers, and hop depth without executing DDL.
4. Prove policy. Stable rules RC-001 through RC-044 return PASS, WARN, or FAIL with evidence and a measurable gate-open condition.
5. Compile work. The execution DAG sequences freeze, expand, compatibility, consumer migrations, convergence proof, and human-approved retirement.
6. Create the handoff. A deterministic ZIP contains code, tests, decision evidence, owner routing, and SHA-256 provenance.
7. Persist memory. update_description appends the capsule, evidence hash, blockers, affected URNs, and owners to the source column.

The release authority is deterministic. A model can later broaden request parsing or propose remediation, but it cannot silently override graph evidence or policy.

DataHub MCP flow

Call	Evidence loaded	Used by the compiler
search	Exact source entity and URN	Dataset resolution
list_schema_fields	Field type, documentation, and governance tags	Before-state and governed-field proof
get_lineage	Column-level downstream graph through 3 hops	Broken edges and exact failure paths
get_entities	Owners, asset types, domains, platforms, and criticality	Owner routing, ML protection, coverage, and risk
update_description	Mutation result	Hash-sealed, durable decision capsule

Offline mode implements these official names over data/catalog.json. Live mode speaks MCP JSON-RPC over stdio to the official server. Live errors never fall back silently to fixtures.

Architecture

flowchart LR
    D["Warehouse DDL"] --> P["Constrained parser"]
    P --> A["Ripplecheck compiler"]
    A --> M["DataHub MCP transport"]
    M --> F["Offline metadata graph"]
    M --> L["Official DataHub MCP Server"]
    A --> C["Counterfactual projection"]
    C --> R["Stable policy proof"]
    R --> G["Release gate and migration DAG"]
    G --> W["Hash-sealed DataHub writeback"]
    G --> Z["Six-file PR evidence pack"]

See docs/ARCHITECTURE.md for the transport boundary, capsule schema, policies, and safety properties.

Run modes

Web demo

python3 main.py web

Endpoints:

• GET /health
• GET /api/scenarios
• POST /api/analyze
• GET /api/evidence-pack/<run_id>

CLI

python3 main.py assess \
  "ALTER TABLE warehouse.analytics.customer_360 RENAME COLUMN customer_tier TO loyalty_tier;"

Use --no-writeback for a read-only run.

MCP server

Ripplecheck is itself an MCP stdio server:

• assess_schema_change
• list_demo_scenarios

python3 main.py mcp

Copy .mcp.json.example and replace its repository path to use it from an MCP-compatible client.

Live DataHub

Start DataHub OSS with the official Quickstart, create a personal access token, install uv, and then select the live transport:

export DATAHUB_GMS_URL="http://localhost:8080"
export DATAHUB_GMS_TOKEN="<your-local-datahub-token>"
export RIPPLECHECK_MODE=live
export DATAHUB_MCP_COMMAND="uvx mcp-server-datahub@latest"
export TOOLS_IS_MUTATION_ENABLED=true
python3 main.py web

The official DataHub Quickstart runs DataHub locally; the official MCP guide documents the uvx server and required environment variables. Mutation tools require MCP server v0.5.0+ and are opt-in. Clear TOOLS_IS_MUTATION_ENABLED and uncheck writeback for a read-only live assessment.

This exact path was verified on August 10, 2026 with DataHub OSS 1.6.0 and its official showcase-ecommerce datapack. The live proof records the input, observed metrics, five MCP calls, and successful writeback without publishing credentials.

Demo scenarios

Proposed change	Expected	Distinct proof
Rename customer_tier to loyalty_tier	BLOCK	Five consumers, production ML risk, one ownership gap, generated compatibility pack
Rename finance net_revenue	BLOCK	Critical executive finance dashboard and accountable finance owner
Drop unused sandbox legacy_bucket	SAFE	No downstream consumer edge, open gate, normal contract validation

Checked-in deterministic outputs:

• Production contract rename
• Finance metric rename
• Safe sandbox cleanup
• Verified DataHub OSS + official MCP result

Regenerate through the real compiler path:

make samples

Fixture names and email addresses are synthetic. All addresses use the reserved .example domain. Offline writebacks are saved to the gitignored data/run-state.json and reapplied for the current server.

Generated PR pack

The default ZIP is generated in memory and contains:

migration/compatibility_view.sql
models/customer_360/schema.yml
tests/assert_customer_tier_compatibility.sql
review/ripplecheck-decision.md
review/owner-routing.json
manifest/change-capsule.json

The ZIP is byte-for-byte deterministic for the same assessment. Its fixed timestamps and canonical JSON make review diffs stable.

Verify

make samples
make verify

Verification covers parsing, decisions, graph paths, policy rules, execution gates, durable writeback, MCP handshake, deterministic ZIP bytes, ZIP members, generated SQL, Python compilation, required files, sample shape, and public-copy checks. GitHub Actions runs the same path.

Deploy

Vercel production

The public judge deployment runs as a static frontend plus a dependency-free Python service:

vercel deploy --prod

Production URL: https://ripplecheck-datahub.vercel.app. The Vercel adapter preserves the local API contract and rebuilds evidence packs statelessly across serverless invocations. No secret or paid resource is required.

Docker

docker build -t ripplecheck .
docker run --rm -p 8000:8000 ripplecheck

Render Blueprint

Push the repository publicly, create a Render Blueprint from it, and use the generated onrender.com URL. render.yaml selects the free web plan, fixture mode, the native Python runtime, and /health; no secret is required.

Submission package

• One-document demo runbook and tech stack
• Public Vercel demo
• Devpost copy
• Architecture
• Deadline-focused checklist
• Checked-in sample outputs
• Extracted generated artifacts
• Judge testing instructions
• Exact Devpost form answers
• Official-rules compliance matrix
• Project disclosures
• Verified live DataHub proof
• Apache License 2.0

The deadline is August 10, 2026 at 5:00 PM EDT, or August 11 at 2:30 AM IST. The submission checklist targets an earlier upload window.

Scope and honesty

• Fixture mode is a deterministic metadata snapshot, not a DataHub Cloud connection.
• Live mode invokes the official DataHub MCP Server and uses its real results; the checked-in proof records a completed read-and-write run against DataHub OSS 1.6.0.
• Ripplecheck never executes the submitted DDL.
• Generated SQL and contracts are review artifacts, not automatically applied changes.
• The risk score is an explainable bounded score, not a probability.
• The default path uses no LLM, OpenAI API key, or paid service.

License

Apache License 2.0. See LICENSE.

For security reports and supported judge-testing dates, see SECURITY.md.