# VS-00: Platform Governance & Data Contract

**Vertical Slice:** VS-00 (Platform Infrastructure)  
**Version:** 1.0  
**Date:** 2026-08-06  
**Owner:** Architecture Team  
**Status:** ✅ APPROVED (AGENTS.md v16.0 Compliant)

---

## 📋 User Story

**As a** platform architect  
**I want to** establish formal governance rules, data contracts, and domain policies  
**So that** all downstream slices (VS-01 through VS-08) can operate with consistent constraints and validation

**Acceptance Criteria:**
- ✅ DATA_CONTRACT defined (schema + PIT rules)
- ✅ Domain policies formalized (no magic numbers)
- ✅ Governance gates documented (approval workflows)
- ✅ Data lineage & quality rules specified

---

## 🎯 Non-Goals

- ❌ Implement business logic (belongs to VS-01+)
- ❌ Build UI/API endpoints (belongs to FE/BE slices)
- ❌ Execute jobs/automation (belongs to TESTOPS)
- ❌ Enforce at code level (documentation only for v1.0)

---

## 🔄 State Transitions

### Data State Machine

```
┌─────────────────────────────────────────────────────────────────┐
│                    VS-00 DATA GOVERNANCE STATE                   │
└─────────────────────────────────────────────────────────────────┘

[UNDEFINED]
    ↓
[DRAFT] ← Architect proposes DATA_CONTRACT
    ↓
[REVIEWED] ← Security + Compliance approve
    ↓
[PUBLISHED] ← GA release (all slices conform)
    ↓
[RETIRED] ← Superseded by v2.0 (if needed)

Events:
- on_proposal → UNDEFINED → DRAFT
- on_security_review → DRAFT → REVIEWED (or DRAFT if rejected)
- on_ga_release → REVIEWED → PUBLISHED
- on_deprecation → PUBLISHED → RETIRED
```

### RBAC State Machine

```
[GUEST]
  ↓ (authenticated)
[USER]
  ↓ (elevated privileges)
[OPERATOR]
  ↓ (admin approval)
[ADMIN]
  ↓ (super-admin role)
[SUPER_ADMIN]
```

---

## 🔐 RBAC Constraints

| Role | Can Read | Can Write | Can Delete | Can Audit |
|------|----------|-----------|-----------|-----------|
| **GUEST** | Public (GDP compliant) | ❌ | ❌ | ❌ |
| **USER** | Own data + Public | Own data only | Own data only | Own data (limited) |
| **OPERATOR** | All (except audit logs) | All | ❌ (soft delete) | All (limited) |
| **ADMIN** | All | All | All (soft delete) | All |
| **SUPER_ADMIN** | All (including audit) | All | All (hard delete) | All |

**Authorization Model:**
- **Policy-based:** FastEndpoints + `Roles()` attribute
- **Resource-level:** Check `owner_id == current_user_id` for USER
- **Fail-closed:** Deny by default, allow only when authorized
- **Audit:** Log all authorization decisions (Success/Failure)

---

## 📊 Data Contract (v1.0)

### Point-in-Time (PIT) Envelope

All tables MUST include:

```sql
published_at     TIMESTAMP NOT NULL DEFAULT now()
correlation_id   UUID NOT NULL
revision         INT NOT NULL DEFAULT 1
```

**PIT Query Pattern:**

```sql
-- ALWAYS filter by published_at to get historical state at point T
SELECT * FROM my_table
WHERE published_at <= @cutoff
  AND status = 'active'
ORDER BY published_at DESC
LIMIT 1  -- Get latest revision at cutoff time
```

### Data Quality Lineage Rules

| Data Source | Quality Level | SLA | DQ Rules |
|-------------|---------------|-----|----------|
| **KRX API** | Real-time | 99.5% | No nulls in price; volume ≥ 0 |
| **OpenDart API** | Daily | 99.0% | Non-null filing date; corp_code matches regex |
| **Portfolio (Input)** | User-provided | 95.0% | No negative quantities; qty × price = total |
| **Shadow Run Output** | Computed | 99.9% | Must complete within 252 days |

### Schema Normalization (3NF + Append-Only)

**Write Model:**
- All updates are appends (new rows)
- No UPDATE/DELETE (soft delete only)
- Revision counter increments per change
- Immutable historical record

**Read Model:**
- Denormalized projections (separate tables)
- Computed fields (e.g., portfolio_value = qty × price)
- Cache-friendly (no joins needed)
- Refreshed on event (Outbox→Inbox)

---

## 🚀 Governance Gates

### Gate 1: Data Governance Approval
**Owner:** CTO + Security  
**Trigger:** Pull request to CLAUDE.md / DATA_CONTRACT update  
**Decision:** Review for compliance + security implications  
**Evidence:** Signed-off approval comment in PR

### Gate 2: Privacy Impact Assessment (PIA)
**Owner:** Legal + Privacy Officer  
**Trigger:** Any PII data addition  
**Decision:** GDPR/CCPA compliance check  
**Evidence:** PIA document attached to issue

### Gate 3: Performance Review
**Owner:** DBA + Performance team  
**Trigger:** Schema changes or new indexes  
**Decision:** Query plan analysis + load test  
**Evidence:** Benchmark report in commit comment

### Gate 4: Audit Trail Compliance
**Owner:** Compliance  
**Trigger:** Financial data changes  
**Decision:** Verify audit logs + retention policy  
**Evidence:** Audit log test in CI/CD

---

## 📝 Implementation Checklist

### Phase 1 (Current - V1.0)
- [x] DATA_CONTRACT v1.0 created
- [x] PIT envelope rules documented
- [x] DQ lineage rules specified
- [x] RBAC roles defined
- [x] State machines documented
- [ ] Governance gates implemented in CI/CD

### Phase 2 (Future - V2.0)
- [ ] Performance normalization (partitioning by date)
- [ ] Full-text search indexes
- [ ] Temporal versioning (PostgreSQL)
- [ ] Cross-module synchronization (Event Sourcing)

### Phase 3 (Future - V3.0)
- [ ] Machine learning data pipeline
- [ ] Real-time streaming (Kafka)
- [ ] Data warehouse integration (Snowflake)

---

## ✅ Compliance & Validation

### AGENTS.md v16.0 Alignment

- ✅ **SOLID:** Data governance separate from business logic
- ✅ **Necessity-driven:** Only rules needed for current slices (VS-01+)
- ✅ **Normalization:** 3NF + append-only prevents data anomalies
- ✅ **Traceability:** All changes logged via published_at + correlation_id
- ✅ **Guardrails:** PIT queries enforced; SELECT * forbidden

### Security Checklist

- ✅ PII redaction policy defined
- ✅ RBAC constraints documented
- ✅ Audit trail mandatory (correlation_id tracing)
- ✅ Fail-closed authentication model (Release mode)
- ✅ SQL injection prevention (parameterized queries only)

---

## 📚 References

- `contracts/data/platform-data-contract.v1.json` — Formal schema definition
- `docs/dq-lineage-rules.md` — Detailed DQ rules per data source
- `CLAUDE.md` — Development mode authentication
- `AGENTS.md` — 13 decision criteria for compliance verification

---

**Version:** 1.0  
**Last Updated:** 2026-08-06  
**Status:** ✅ **APPROVED FOR IMPLEMENTATION**