KArtSell.Aegis/docs/CURRENT/VS-02_DATA_GOVERNANCE_POLICY.md

VS-02: Financial Security Master Data Governance Policy

Date: 2026-08-07
Version: 1.0 (COMPLETE)
Owner: Data Governance + Compliance
Status: ✅ READY FOR IMPLEMENTATION

---

Executive Summary

Formal governance policy for KRX financial security master data (listing status, delisting dates, product structure, trading availability). Resolves all data governance unknowns identified in VS-02-SLICE_SPEC.md by referencing AEG-X-009 consolidated source catalog.

---

Data Source Authority

Source: Korea Exchange (KRX) OpenAPI
Base URL: https://openapi.krx.co.kr
Endpoints:

• /svc/apis/idx/krx_dd_trd — Index/stock trading data (OHLCV)
• /svc/apis/sco/stk_bnd_isfl — Stock trading volume

Authentication: AUTH_KEY (provided by KRX)
Frequency: Daily (T+0, end of business day)
Import Window: Within 4 hours of market close
SLA: 99.5% availability (support: weekdays 9 AM-5 PM KST)

Reference: docs/CURRENT/CATALOGS/source-catalog.md v2.0 + contracts/data/source-approval.v1.json

---

Import & Refresh Procedure

Daily Import Schedule

Time	Action	Owner	Status	Notes
16:30 KST	Market closes	KRX	Automatic	Korean market hours end
16:30-17:30	KRX publishes data	KRX	External	Prices, volumes, restrictions
17:30-18:00	Fetch via OpenAPI	Backend Service	✅ Primary	Retry if 429 (rate limit)
18:00-18:30	Validate + Transform	Data Validation	✅ Primary	DQ checks (see below)
18:30-19:00	Upsert + Append	Database (append-only)	✅ Primary	No UPDATE; only INSERT new revision
19:00+	Notify consumers	Outbox/Inbox	✅ Event-driven	Shadow runs, sell decisions

Fallback Procedure (If Primary Fails)

Condition	Trigger	Action	Max Age	Escalation
API timeout (503)	3+ retries fail	Use cached LKG data	1 trading day	Alert Ops
Rate limit (429)	1000 req/day exceeded	Queue for retry (Hangfire q-backfill)	24 hours	Standard backoff
Auth failure (401)	Token expired	Refresh credentials	—	Retrieve new AUTH_KEY
Data quality fail	DQ rule violated	Quarantine + alert + manual review	—	Escalate to risk team
Network unreachable	10+ retries fail	Use last-known-good (LKG) snapshot	1 day	24-hour retry loop

---

Data Quality Rules

Validation Checks (Pre-Insert)

Schema Completeness:

• All required columns populated (krx_code, security_name, security_type, trading_status)
• No NULL values in primary key fields

Business Logic:

IF delisting_date IS NOT NULL THEN
  delisting_date >= listing_date (logical ordering)
  trading_status = 'DELISTED' (consistency)
ENDIF

IF trading_status = 'SUSPENDED' THEN
  suspend_reason IS NOT NULL (audit requirement)
ENDIF

IF product_category NOT IN ('STOCK', 'BOND', 'DERIVATIVE', 'FUND') THEN
  REJECT with alert
ENDIF

Reconciliation (Daily):

• Count securities in KRX data vs. system database (within 1% variance acceptable)
• Flag any security marked DELISTED that was active yesterday (reactivation alert)

Failure Response

Severity	Condition	Response
CRITICAL	>10% data missing	Reject import, revert to LKG, alert risk team
SEVERE	DQ rule fails on >50 rows	Quarantine failing rows, manual review, retry tomorrow
MEDIUM	Single row fails DQ	Quarantine row, skip import for that security, continue batch
LOW	Schema version mismatch	Log warning, inspect KRX schema update, notify data gov

---

Audit & Correction Handling

Revision History (PIT Tracking)

Immutable Design:

• No UPDATE or DELETE operations
• All corrections = new INSERT with incremented revision number
• Each revision tagged with published_at (when KRX published) + correlation_id (trace)

Example Flow:

2026-08-07 10:00 KRX: Samsung (005930) delisting_date = 2026-12-31
  → INSERT: revision=1, published_at=2026-08-07 10:00, delisting_date=2026-12-31

2026-08-10 15:00 KRX: Samsung correction — delisting_date = 2026-01-15 (moved up)
  → INSERT: revision=2, published_at=2026-08-10 15:00, delisting_date=2026-01-15
  → Outbox event: "security_correction" → Inbox → shadow_runs consumer
  → Consumer: Revalidate all in-flight shadow runs that reference Samsung

Correction Notification

Downstream Notification: When KRX publishes correction, Outbox/Inbox pipeline notifies:

1. Shadow Run Engine: Revalidate active runs (check if sell decision impacted)
2. Sell Decision Engine: Re-evaluate if delisting date affects threshold
3. Portfolio Reconciliation: Recompute holdings if trading_status changed
4. Audit Trail: Log correction with date, old value, new value, correlation_id

Consumer Idempotency: All consumers use correlation_id + revision to prevent duplicate processing

---

Governance Checkpoints

Pre-Implementation Gates

• Source Authority Confirmed: KRX OpenAPI v1.0, endpoints live, auth key obtained
• SLA Signed: Ops team commits to 4-hour import window, 99.5% uptime target
• DQ Rules Approved: Risk team reviews and signs off on completeness/accuracy rules
• Audit Trail Planned: correlation_id + revision tracking + Outbox/Inbox verified
• Downstream Consumers Ready: Shadow run + sell decision engines support correction events

Post-Implementation Monitoring

• Daily: Import success rate, row counts vs. KRX (reconciliation)
• Weekly: Correction event frequency, consumer lag (Inbox processing time)
• Monthly: Data freshness SLA, fallback usage (LKG cache frequency)
• Quarterly: DQ rule effectiveness (false positives, false negatives)

---

Risk Mitigation

Risk	Probability	Impact	Mitigation
KRX API down	1%	High	Fallback to cache (up to 1 day old), alert ops, resume next market day
Data quality violation	2%	High	Quarantine failing rows, retry next cycle, manual review by risk team
Correction not propagated	<1%	High	Outbox/Inbox idempotent; re-run notification consumer if failed
Shadow run invalidated	<1%	Medium	Revalidate on correction event; flag if sell decision changed
Duplicate events	<1%	Low	correlation_id deduplication prevents re-processing

---

Compliance & Audit

Regulatory Adherence:

• ✅ Data retention: 5 years (regulatory requirement)
• ✅ Audit trail: All changes logged with correlation_id (FSS compliance)
• ✅ Access control: Read-only to authorized consumers (shadow runs, sell decisions)
• ✅ Data lineage: KRX → system → downstream consumers traced via correlation_id

Audit Requirements:

• Weekly reconciliation report (vs. KRX published data)
• Monthly DQ metrics (pass rate, failure reasons)
• Quarterly gap analysis (missing/late imports)

---

Contact & Escalation

Issue	Owner	Contact	Escalation
Data source questions	Data Gov Lead	data-gov-team@company	Chief Data Officer
Import failures	SRE/Backend Lead	ops-team@company	VP Engineering
DQ violations	Risk Team Lead	risk-team@company	Chief Risk Officer
Compliance audit	Compliance Officer	compliance@company	Legal

---

Co-Authored-By: Claude Haiku 4.5 noreply@anthropic.com
Status: ✅ READY FOR ACTIVATION
Reference: AEG-X-009 (Source Catalog), VS-02-SLICE_SPEC.md (Design), source-approval.v1.json (Contract)