EvidenceBound DataHub Gate

Fail-Closed Read → Verify → Write-Back Governance for Data Agents.

This repository is the newly authored DataHub hackathon vertical slice of the broader EvidenceBound design. It is intentionally independent of SignalReview production, private enterprise workers, customer code, billing, authentication, and proprietary sports logic.

How judges can verify the evidence

The fastest controlled path does not require a running DataHub instance:

git clone https://github.com/moneyparking/evidencebound-datahub-gate.git
cd evidencebound-datahub-gate
make test-repro

make test-repro creates a local virtual environment, installs the development dependencies, runs the deterministic validation suite, regenerates the controlled VERIFIED and stale-schema BLOCKED Proof Packs, and reproduces both packs.

Expected terminal states include:

VERIFIED
BLOCKED: SCHEMA_MISMATCH
REPRODUCED
ARTIFACT_TAMPERING_DETECTED  # required by the retained mutation test
SIGNATURE_VALID              # retained Ed25519-sealed packs

To reproduce only the retained packs after installation:

make verify-packs

To verify the retained detached Ed25519 seals against the repository-published public key:

evidencebound-datahub verify-seal \
  evidence/controlled-verified \
  --public-key docs/judge/keys/evidencebound-datahub-hackathon-public.pem

evidencebound-datahub verify-seal \
  evidence/controlled-blocked \
  --public-key docs/judge/keys/evidencebound-datahub-hackathon-public.pem

Expected for both packs:

SIGNATURE_VALID
trusted_public_key_matched: true
PINNED_KEY_MATCHED

To run the same process from a fresh clone in a temporary directory and emit an independent report:

make independent-repro

To inspect the static public judge journey locally:

make serve-judge
# open http://localhost:8000

Public Judge Explorer:

https://moneyparking.github.io/evidencebound-datahub-gate/

The static judge journey is an editorial proof explorer. It does not execute DataHub, represent live DataHub UI, create new acceptance evidence, or authorize deployment. No fixed clean-install duration is claimed because dependency download time varies.

Reproduce the complete DataHub MCP loop

Prerequisites: Linux/WSL, Docker, Python 3.11+, network access for the first install, and sufficient Docker memory.

git clone https://github.com/moneyparking/evidencebound-datahub-gate.git
cd evidencebound-datahub-gate

python3 -m venv .venv
source .venv/bin/activate

./scripts/run-local-datahub-smoke.sh

The first run downloads and starts DataHub containers, so completion time depends on network speed and available system resources. No fixed clean-install duration is claimed.

The problem

Agents can read metadata and still take unsafe actions when generated code is bound to a stale schema, incomplete lineage, or unsupported claims. A successful tool call is not proof that the intended action is safe.

What it does

Read Context → Restricted AST Gate → Tamper-Evident Proof Pack → Native DataHub Write-Back

DataHub MCP
  ├─ dataset identity
  ├─ schema fields
  └─ bounded one-hop lineage edge
          ↓
EvidenceBound deterministic gate
  ├─ dataset identity binding
  ├─ schema + lineage digests
  ├─ Restricted AST Policy
  ├─ Fail-Closed Bounded Interpreter
  ├─ claim-to-evidence binding
  └─ VERIFIED / BLOCKED receipt
          ↓
Tamper-Evident Content-Addressed Proof Pack
          ↓
Native DataHub Description Receipt
          ↓
Mandatory Human Review

Two paths are mandatory:

1. VERIFIED — current schema and the bounded lineage evidence match the candidate contract.
2. BLOCKED — a stale schema digest fails closed before runtime interpretation.

Both outcomes are appended to the same DataHub dataset through the official native update_description MCP mutation. The write-back is metadata evidence, not production approval, transaction authorization, or permission to deploy.

Read-only verification and governed write-back

Read-only and write-back executions are intentionally distinct evidence classes.

• A read-only recording can prove MCP read, the current-context VERIFIED path, the stale-schema BLOCKED path, and fresh Proof Pack generation without mutating DataHub metadata.
• Native write-back is executed only in the explicit live acceptance path and appends evidence through the official update_description MCP mutation.
• The write-back receipt records promotion_authorized=false; Mandatory Human Review remains outside automation.

This separation is a fail-closed operating policy, not a claim that the read-only recording performed write-back.

Why native description write-back

The hackathon criterion rewards contributing knowledge back to the graph. update_description is an official DataHub MCP mutation, visible in DataHub OSS, and requires no custom schema registration. This project does not claim a custom DataHub badge or aspect.

Quick controlled proof without Docker

python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
./scripts/validate.sh

This generates two controlled Proof Packs under evidence/ and reproduces both.

You can also reproduce the retained packs directly:

evidencebound-datahub verify-pack evidence/controlled-verified
evidencebound-datahub verify-pack evidence/controlled-blocked

Live local DataHub acceptance

The live script:

1. installs DataHub and the official DataHub MCP server;
2. runs datahub docker quickstart;
3. loads the Apache-2.0 showcase ecommerce datapack;
4. discovers a dataset through MCP;
5. reads the dataset entity, schema, and a bounded one-hop lineage edge through DataHub MCP;
6. runs the current-context VERIFIED candidate and stale-schema BLOCKED candidate;
7. appends both Native DataHub Description Receipts through MCP update_description;
8. reproduces each Proof Pack;
9. prints DATAHUB_MCP_READ_WRITE_ACCEPTANCE=PASS only when every required gate passes.

The accepted live dataset was:

urn:li:dataset:(urn:li:dataPlatform:dbt,b2fd91.ORDER_ENTRY_DB.analytics.order_history,PROD)

The read is deliberately bounded to one hop and at most five results. The adapter checks upstream first and skips the opposite direction after a visible lineage edge is found. Missing lineage still blocks verification.

Stop condition

If the live smoke cannot prove all four states, preserve the logs and fail closed:

• MCP read: PASS
• current-context path: VERIFIED
• stale-schema path: BLOCKED
• MCP description write-back: PASS

A controlled fixture is never presented as live DataHub acceptance.

Proof Pack

Each path contains:

candidate.json
datahub-context.json
gate-receipt.json
mcp-read.json
mcp-write.json
manifest.json
SHA256SUMS
ed25519-seal.json  # optional contract; present in the retained controlled packs

evidence_root_sha256 deterministically binds the candidate, DataHub context, receipt, and MCP read evidence. manifest_body_sha256 additionally binds the MCP write result.

Reproduction rejects modified artifacts, non-canonical JSON, symlinks, missing files, and unexpected files. The retained test mutates gate-receipt.json by one byte and requires ARTIFACT_TAMPERING_DETECTED.

The Proof Pack remains tamper-evident and content-addressed through SHA-256. When ed25519-seal.json is present, a separate verification step validates the detached Ed25519 signature over the verified manifest subject.

Retained Ed25519 release key

The retained controlled VERIFIED and BLOCKED packs are signed with the same owner-controlled key:

key_id: evidencebound-datahub-hackathon-2026
public_key_sha256: fdf31b458136d39b3c22fe041e9ae7c986365c40275383d09e8a38ae81f0680d
public_key: docs/judge/keys/evidencebound-datahub-hackathon-public.pem

The private key is not stored in the repository. A valid signature proves possession of the matching private key. The repository-published public key makes verification reproducible, but independent signer identity still requires comparison of the fingerprint through a separately trusted channel. See docs/judge/SECURITY_AND_TRUST.md.

How it was built

Built with the official DataHub MCP server via FastMCP, the DataHub SDK, a restricted AST policy, a bounded no-exec interpreter, a Python verification core, and optional detached Ed25519 attestation. The public repository is Apache-2.0 licensed.

Validation uses pytest, Ruff, Mypy, and GitHub Actions.

Claim boundary

VERIFIED means only that the exact candidate matched the observed DataHub context, passed the Restricted AST Policy, executed in the Fail-Closed Bounded Interpreter, and bound every material claim to schema or lineage evidence.

It does not mean production approval, production authorization, data truth, regulatory certification, model accuracy, financial safety, customer acceptance, or permission to deploy. promotion_authorized is always false; Mandatory Human Review always remains required.

No LLM integration is claimed in this repository.

Hackathon positioning

• Track: Agents That Do Real Work
• DataHub technologies: DataHub OSS + official DataHub MCP server
• Judge-visible loop: Read Context → Restricted AST Gate → Tamper-Evident Proof Pack → Native DataHub Write-Back
• Public repository and deterministic GitHub Actions gates
• Submission disclosure: the EvidenceBound concept and earlier private/open-core work predate this hackathon; this DataHub adapter, bounded demo runtime, MCP workflow, and shared evidence pack were newly authored during the submission period.

Submission media integrity — V12

The recommended Devpost/YouTube master is:

EvidenceBound_DataHub_Hackathon_FINAL_MASTER_V12_JUDGE_CAPTIONED.mp4
SHA-256: e51fbd9d9ddf69d87d7754be05f80f765cf05f768d63aff21c854c5815bd2a9a
Duration: 169.813000 seconds
Resolution: 1920×1080
Frame rate: 30 fps
Release source commit: 9f39bcf2498a05a47dd7b0a82049e95893770642

The master contains burned English narration captions; do not overlay a second subtitle track. V12 shows the redesigned Judge Explorer, detached Ed25519 verification for the retained controlled VERIFIED and BLOCKED packs, the repository-published key fingerprint, release-source identity, successful deterministic and independent-reproduction gates, successful Pages deployment, and the Mandatory Human Review boundary.

The retained controlled sealed packs are distinct from the accepted live DataHub MCP dataset and native description write-back evidence. V12 does not claim that the separate live acceptance packs were signed.

YouTube V12 video: https://youtu.be/dEWJ2eGiDO8

The video is now available as a standard public YouTube video. Independent verification returned HTTP 200 for YouTube oEmbed, the embeddable player endpoint, and the max-resolution thumbnail. Full start-to-finish playback and Devpost embed acceptance remain external gates.

Full V12 media evidence, the clean alternative, hashes, audio QA, release acceptance, and publication gates are recorded in:

• submission/datahub-v12-video-proof.json;
• submission/DATAHUB_DEVPOST_MEDIA_V12.md;
• docs/media/VIDEO_MASTER.md.

Historical V7.1 media records remain in submission/ as audit history and are not the recommended final submission master.

Final Devpost submission

The canonical final second-page copy, Built With tags, public links, gallery order, and V12 video identity are recorded in DEVPOST_SUBMISSION_V12.md.

Grant synchronization

grant-sync/claim-map.json is the single claim boundary for Startup EDGE and Microsoft for Startups materials. It distinguishes controlled evidence, live MCP acceptance, and prohibited claims. A hackathon demo alone does not establish TRL level, funding, certification, production readiness, or customer acceptance.

License

Apache License 2.0 applies to this published repository. It does not automatically relicense all transitive dependencies. See LICENSE and dependency licenses.