LINEAGE_INDEX_SPEC.md

Lineage Index Specification

เอกสารนี้กำหนด index กลางสำหรับเชื่อม correlation_id, policy_trace_id, และ memory commit hash (hash_self) ให้อยู่ในเส้นทาง query เดียว เพื่อรองรับงาน audit, replay, และ incident forensics

Objective

• ให้ operator หา lineage ของคำสั่งหนึ่งชุดได้จากคีย์ใดคีย์หนึ่ง (correlation_id หรือ policy_trace_id)
• ลดการไล่ข้อมูลข้ามตาราง/ข้ามระบบแบบ manual
• รองรับ deterministic replay checks จาก governance decision ไปยัง memory commit

Logical model

flowchart LR
    A[governance.approved\npolicy_trace_id] --> B[lineage_index]
    C[execution.completed\ncorrelation_id] --> B
    D[memory.committed\nhash_self/hash_prev] --> B
    B --> E[audit query path]

Loading

Canonical relational projection (SQL)

-- 1) Landing table สำหรับ projection จาก canonical envelope events
CREATE TABLE IF NOT EXISTS lineage_index (
    lineage_id TEXT PRIMARY KEY,                 -- deterministic: sha256(correlation_id|policy_trace_id|memory_hash)
    tenant_id TEXT NOT NULL,
    correlation_id TEXT NOT NULL,
    policy_trace_id TEXT NOT NULL,
    directive_id TEXT,
    execution_id TEXT,
    memory_id TEXT,
    memory_commit_hash TEXT NOT NULL,            -- maps to memory.committed.data.hash_self
    memory_prev_hash TEXT,
    governance_event_id TEXT,
    execution_event_id TEXT,
    memory_event_id TEXT NOT NULL,
    governance_occurred_at TEXT,
    execution_occurred_at TEXT,
    memory_occurred_at TEXT NOT NULL,
    committed_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(tenant_id, correlation_id, policy_trace_id, memory_commit_hash),
    CHECK (length(trim(tenant_id)) > 0),
    CHECK (length(trim(correlation_id)) > 0),
    CHECK (length(trim(policy_trace_id)) > 0),
    CHECK (length(trim(memory_commit_hash)) > 0),
    CHECK (memory_prev_hash IS NULL OR memory_prev_hash <> memory_commit_hash),
    CHECK (
        governance_occurred_at IS NULL
        OR memory_occurred_at >= governance_occurred_at
    ),
    CHECK (
        execution_occurred_at IS NULL OR (
            execution_occurred_at <= memory_occurred_at AND
            (governance_occurred_at IS NULL OR execution_occurred_at >= governance_occurred_at)
        )
    )
);

-- 2) Indexes สำหรับ one-query-path lookups
CREATE INDEX IF NOT EXISTS idx_lineage_tenant_correlation
    ON lineage_index (tenant_id, correlation_id);

CREATE INDEX IF NOT EXISTS idx_lineage_tenant_policy
    ON lineage_index (tenant_id, policy_trace_id);

CREATE INDEX IF NOT EXISTS idx_lineage_tenant_memory_hash
    ON lineage_index (tenant_id, memory_commit_hash);

CREATE INDEX IF NOT EXISTS idx_lineage_tenant_time
    ON lineage_index (tenant_id, memory_occurred_at DESC);

One query path (correlation ↔ policy ↔ memory)

-- Input: tenant_id + (correlation_id OR policy_trace_id OR memory_commit_hash)
SELECT
    li.tenant_id,
    li.correlation_id,
    li.policy_trace_id,
    li.directive_id,
    li.execution_id,
    li.memory_id,
    li.memory_commit_hash,
    li.memory_prev_hash,
    li.governance_event_id,
    li.execution_event_id,
    li.memory_event_id,
    li.governance_occurred_at,
    li.execution_occurred_at,
    li.memory_occurred_at
FROM lineage_index li
WHERE li.tenant_id = :tenant_id
  AND (
       li.correlation_id = :lookup_key
    OR li.policy_trace_id = :lookup_key
    OR li.memory_commit_hash = :lookup_key
  )
ORDER BY li.memory_occurred_at DESC;

Projection mapping rules

1. governance.approved เติม policy_trace_id, governance_event_id, governance_occurred_at
2. execution.completed เติม execution_id, execution_event_id, execution_occurred_at
3. memory.committed เติม memory_id, memory_commit_hash, memory_prev_hash, memory_event_id, memory_occurred_at
4. ต้อง reject record ถ้าไม่มี tenant_id, correlation_id, policy_trace_id, หรือ memory_commit_hash (รวมถึงกรณีเป็นค่าว่าง)
5. ถ้ามี retry/duplicate event ให้ upsert ตาม UNIQUE(tenant_id, correlation_id, policy_trace_id, memory_commit_hash)

Integrity checks

• memory_occurred_at >= governance_occurred_at เมื่อมี governance event
• execution_occurred_at ควรอยู่ระหว่าง governance และ memory commit (ถ้ามี execution event)
• memory_prev_hash ควรเทียบได้กับ commit ก่อนหน้าใน correlation เดียวกัน เพื่อยืนยัน continuity chain

Rollout notes

1. เริ่มจาก materialized projection ภายใน Governance/Audit boundary ก่อน
2. backfill จาก event log ย้อนหลังตามช่วงเวลา (latest N days แล้วค่อยขยาย)
3. เพิ่ม dashboard query preset: by correlation_id, by policy_trace_id, by memory_commit_hash
4. ผูก incident playbook ให้ใช้ query เดียวนี้เป็นจุดเริ่มต้น