KArtSell.Aegis/docs/CURRENT/SLICE_SPECS/VS-00-SLICE_SPEC.md

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:

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

PIT Query Pattern:

-- 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)

• DATA_CONTRACT v1.0 created
• PIT envelope rules documented
• DQ lineage rules specified
• RBAC roles defined
• 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