# PingCAP Datalake

This repo contains the first-version design package for a TiDB Cloud Lake-first lakehouse and data-agent mesh.

The work is currently architecture/design, not implementation. The goal is to define the durable concepts, boundaries, schemas, and open questions before building services.

## Start Here

Read in this order:

1. [CONTEXT.md](./CONTEXT.md) — shared glossary and current decisions.
2. [docs/design/v1-lakehouse-architecture.md](./docs/design/v1-lakehouse-architecture.md) — main architecture narrative.
3. [docs/design/README.md](./docs/design/README.md) — map of supporting design docs.
4. [docs/adr/README.md](./docs/adr/README.md) — decision log.

## Core Posture

- TiDB Cloud Lake is the product and platform anchor.
- Databend is underlying engine context, not a peer product target for v1.
- Data products are the primary unit of ownership and architecture.
- Raw, staging, curated, and service are logical layers, not a mandatory lifecycle progression.
- Contracts are mandatory, versioned, Git-authored, and runtime-served.
- Runtime contract views are denormalized snapshots for agents and platform clients.
- Governance is classification-driven and inheritable.
- Agent autonomy is in scope for the lakehouse design, but detailed permission and approval workflows are deferred.

## Current Artifacts

- [V1 architecture](./docs/design/v1-lakehouse-architecture.md)
- [V0 authored contract schema](./docs/design/v0-authored-contract-schema.md)
- [V0 runtime-served contract view schema](./docs/design/v0-runtime-served-contract-view-schema.md)
- [V0 contract engine](./docs/design/v0-contract-engine.md)
- [V0 governance classifications](./docs/design/v0-governance-classifications.md)
- [V0 agent runtime API](./docs/design/v0-agent-runtime-api.md)
- [Machine-readable schemas](./schemas/)

## Validation

Validate JSON schemas with:

```bash
jq empty schemas/data-product-contract.authored.v0.schema.json schemas/data-product-contract.runtime-view.v0.schema.json
```