ContextSeal

Every data change ships with proof, not confidence.

ContextSeal is a DataHub-native certification agent for risky schema changes. It blocks a breaking rename before it reaches GitHub, turns the request into a safe staged migration package, and issues a durable change passport only after a human approves the safe scope.

In the judge path, the first thing you see is the blocked request, the downstream blast radius, the safe review bundle, and the passport payoff. The rest of the product explains why that verdict is grounded.

The final edited public demo video runs approximately 2 minutes 5 seconds: block the rename, inspect the grounded artifact package and evidence trace, approve the safe scope, and end with the passport plus clearly labeled recorded live-local proof.

Open the judge-ready fixture demo · Türkçe README

Final submission

• Public demo: https://zyganali-glitch.github.io/ContextSeal/
• Final demo video: https://www.youtube.com/watch?v=ckhx5X1QQwo (actual edited runtime: approximately 2:05)
• Devpost submission: https://devpost.com/software/contextseal
• Repository: https://github.com/zyganali-glitch/ContextSeal

Built as a clean-room entry for Build with DataHub: The Agent Hackathon. No pre-existing personal-project code is included.

Why the judge path lands

• A risky rename is blocked before merge, not after damage.
• DataHub context shows the exact downstream blast radius and named risk findings.
• The optional AI panel is visible, bounded, and honest about runtime availability.
• ContextSeal generates a safe migration package and a reviewer-ready PR bundle instead of a destructive change.
• Human approval produces a durable passport that the next human or agent can inherit.

What the demo shows

1. The blocked request and downstream blast radius.
2. The deterministic 80 / BLOCKED verdict and named findings.
3. The explanation-only AI boundary and the recorded/local AI separation.
4. The five-file generated safe package and review handoff.
5. Human approval of the safe scope, then the passport payoff and fixture write-back preparation near the end.

Submission gallery

Breaking Change Blocked Before Merge

ContextSeal blocks a risky rename with a deterministic score of 80 after exposing five downstream assets from fixture-backed DataHub context.

Five Evidence-Grounded Review Artifacts

ContextSeal generates five reviewable migration files: a dbt model, schema tests, a rename parity test, rollback SQL, and an impacted-owner brief, all tied to grounding evidence.

Human-Approved SHA-256 Change Passport

Scoped human approval issues a SHA-256 passport binding the request, deterministic evidence, generated artifacts, approval scope, and validity window.

Recorded DataHub Write-Back and Read-Back

Recorded disposable-local DataHub proof shows three bounded writes applied once, the same three skipped on retry, and durable read-back on synthetic metadata.

The problem

Code review and CI can inspect a repository. They usually cannot see that a field feeds a Looker dashboard three hops away, appears in observed production queries, carries a PII glossary term, powers an ML model, or belongs to another team. An AI coding agent can produce syntactically correct data code while still making an organizationally unsafe change.

DataHub already holds that missing context: schemas, lineage, ownership, governance terms, quality signals, incidents, and observed queries. ContextSeal makes that context an enforceable pre-merge decision.

What ContextSeal does

1. Validates a typed change request.
2. Collects target, lineage, usage, ownership, governance, and quality evidence through DataHub MCP.
3. Traces every reachable downstream asset and preserves the path that explains the impact.
4. Calculates deterministic findings such as BREAKING_LINEAGE, SENSITIVE_DATA, LIVE_QUERY_USAGE, and STALE_CONTEXT.
5. Replaces a destructive operation with an expand–migrate–contract strategy.
6. Generates a dbt model, schema tests, a rename parity data test, rollback SQL, and an impacted-owner briefing.
7. Requires a scoped human decision.
8. Creates a SHA-256 change passport covering the request, context, risk, artifacts, evidence, approval, and validity window.
9. Writes certification properties, a description, and a decision document back to DataHub only when every mutation gate is open.

Honest evidence boundary

ContextSeal never collapses these states:

State	Meaning
PASS	A named check or operation completed successfully.
WARN	Evidence exists but needs attention.
FAIL	A named check completed and failed.
NOT_RUN	The check or mutation did not run.
STALE	Context is older than policy allows.
FIXTURE	The result came from the public, synthetic judge fixture.

The hosted/local fixture demo is real application execution against synthetic metadata. It is not presented as a live DataHub tenant. Live MCP capture and mutations are separately gated and recorded.

Architecture

flowchart LR
    R["Schema change request"] --> C["DataHub MCP context"]
    C --> I["Lineage impact trace"]
    I --> P["Deterministic policy gate"]
    P --> G["Safe dbt artifacts"]
    G --> H{"Human decision"}
    H -->|Approve safe scope| S["SHA-256 passport"]
    H -->|Reject| X["Rejected record"]
    S --> W["DataHub write-back"]
    W --> C

Loading

See Architecture, Evidence Boundary, and Threat Model.

Sixty-second local demo

Requirements: Node.js 20 or newer.

npm install
npm test
npm run demo
npm start

Open http://127.0.0.1:4173, then:

1. Select Analyze change.
2. Inspect the fixture-backed five-hop downstream impact trace and risk findings.
3. Select Approve safe scope.
4. Inspect the passport ID and evidence states.
5. Select Prepare write-back. In fixture mode, the application proves that operations were prepared while keeping write-back NOT_RUN.

Or use Docker:

docker compose up --build

Live DataHub mode

1. Start DataHub and install the MCP launcher

Follow the official DataHub Quickstart and MCP documentation. DataHub Core exposes GMS at http://localhost:8080; the official open-source MCP server is launched locally with uvx, using stdio transport. DataHub Cloud uses its streamable HTTP MCP endpoint instead.

2. Configure ContextSeal

Copy .env.example to .env, then set:

CONTEXTSEAL_MODE=datahub
DATAHUB_MCP_TRANSPORT=stdio
DATAHUB_MCP_COMMAND=uvx
DATAHUB_MCP_ARGS=["mcp-server-datahub@0.6.0"]
DATAHUB_GMS_URL=http://localhost:8080
DATAHUB_GMS_TOKEN=your-local-token
DATAHUB_MCP_MUTATIONS_ENABLED=false
CONTEXTSEAL_OPERATOR_TOKEN=<generate-a-random-token>
CONTEXTSEAL_ALLOWED_TARGET_URNS=["urn:li:dataset:(urn:li:dataPlatform:snowflake,retail.gold.customers,PROD)"]

Keep mutations disabled while validating search, entity, lineage, and query evidence. Enable them only for the final, approved write-back demonstration:

DATAHUB_MCP_MUTATIONS_ENABLED=true

In CONTEXTSEAL_MODE=datahub, live API startup also requires CONTEXTSEAL_OPERATOR_TOKEN and a non-empty JSON CONTEXTSEAL_ALLOWED_TARGET_URNS allowlist. Every live POST request must send Authorization: Bearer <CONTEXTSEAL_OPERATOR_TOKEN>, and the request target must appear in the allowlist.

ContextSeal launches the official local MCP process for each bounded operation and passes the mutation setting explicitly. Credentials must never be committed. For DataHub Cloud, set DATAHUB_MCP_TRANSPORT=http and provide the tenant MCP URL.

3. Install ContextSeal structured properties

datahub properties upsert -f config/contextseal-structured-properties.yml
npm run datahub:seed

4. Run

npm start

The application calls DataHub MCP tools for entity context, downstream lineage, observed dataset queries, and bounded metadata mutations. The default judge path keeps the exact graph view fixture-backed unless a target-derived graph contract is exported separately. See Live DataHub Setup for the exact verification path and limitations.

The repository includes a recorded disposable-local PASS bundle under examples/outputs/, sourced from commit baa61387324868b39427030c447b94c2b9599c03. It binds ten MCP reads across five tool types to six downstream assets (DATASET, DATA_JOB, and DASHBOARD counts of two each), then records three APPLIED bounded write-backs, three SKIPPED verify-then-skip retries, and durable exact-one read-back checks. It remains synthetic-local evidence, not a live dashboard connection, production evidence, or a final-head submission freeze.

MCP tools used

Read path:

• get_entities
• list_schema_fields
• get_lineage
• get_lineage_paths_between
• get_dataset_queries

Approved write-back path:

• add_structured_properties
• update_description
• save_document

The canonical reusable workflow is datahub-schema-change-certification, designed for contribution to the DataHub Skills ecosystem. contextseal-change-certification remains a legacy compatibility alias only.

Repository map

src/core/       deterministic contracts, impact, risk, artifacts, passport
src/datahub/    MCP client, live evidence capture, bounded write-back
public/         dependency-free judge dashboard
config/         policy and DataHub structured-property definitions
examples/       synthetic graph, request, and generated evidence
skills/         reusable DataHub change-certification skill
tests/          contract, risk, lineage, passport, and MCP safety tests
docs/           architecture, judging, evidence, security, submission guides
docs/tr/        beginner-safe Turkish operator, Devpost, and video guides

Validation

npm run validate

For submission review, npm run validate is the read-only confidence gate for the committed repo surfaces and dry-run delivery request.

Optional local AI copilot

The repo now ships an optional local Ollama adapter, a visible Local AI Copilot panel, and inspectable grounded AI artifacts. The deterministic verdict is still computed first. If AI is disabled or Ollama is unavailable, ContextSeal records NOT_ENABLED or UNAVAILABLE instead of inventing text.

npm run ai:probe

See AI Runtime Decision for the exact runtime and fallback contract.

Committed AI artifacts:

• examples/outputs/generated/ai/contextseal-ai-input.json
• examples/outputs/generated/ai/contextseal-ai-output.json
• examples/outputs/generated/ai/contextseal-ai-output.md
• examples/outputs/proofs/ollama-ai-proof.json

The deterministic demo artifacts stay reproducible without Ollama. The separate examples/outputs/proofs/ollama-ai-proof.json file is the durable recorded local-model PASS capture that GitHub Pages replays with the label RECORDED LOCAL OLLAMA PROOF.

PR review handoff contract

ContextSeal now includes a reviewer-ready PR handoff contract in PR Review Packet. The default path stays offline and token-free: npm run pr:bundle refreshes the committed PR body, checklist, and payload under examples/outputs/pr/.

npm run pr:bundle
npm run pr:draft -- --dry-run

npm run pr:draft -- --dry-run prepares the exact GitHub draft-PR request without using a token. A live draft PR call remains optional and explicit: the branch named in examples/outputs/pr/pr-payload.json must already exist on GitHub, and GITHUB_TOKEN is required before running npm run pr:draft without --dry-run.

This runs repository-integrity checks, the deterministic Node test suite, and a fresh end-to-end fixture certification. CI also builds the container.

Judge paths

• Two-minute judge test path
• Official criteria mapping
• Claim-by-claim evidence map
• Build-period disclosure
• Demo script
• PR review packet contract
• Devpost submission draft

Turkish beginner guides:

• What the operator must do
• Devpost submission guide
• Demo recording guide

Current scope

Implemented:

• Three change contracts: rename, drop, and type change
• Multi-hop downstream path reconstruction
• Deterministic risk policy
• Safe dbt artifact generation
• Human approval contract
• Hash-bound change passport
• MCP client, live evidence capture, and gated write-back operations
• Persistent local run/event records
• Responsive no-dependency dashboard
• Automated tests, CI, Docker, and complete judging documentation

Explicitly not claimed:

• Automatic production merge or deployment
• A hosted live DataHub tenant connection from GitHub Pages
• Production or customer DataHub evidence
• Production warehouse SQL execution
• Comprehensive SQL parsing
• Security certification
• Customer adoption or incident-reduction metrics

License

Apache License 2.0. See LICENSE.