foxhunt/migrations/014_transaction_audit_events.sql

-- 014_transaction_audit_events.sql
-- Comprehensive Transaction Audit Events Table
-- Persistence layer for AuditTrailEngine - regulatory compliance (SOX, MiFID II)
-- CRITICAL: This table provides immutable audit trail for all trading system events

-- Transaction audit events table with immutability constraints
CREATE TABLE IF NOT EXISTS transaction_audit_events (
    -- Primary key
    id BIGSERIAL PRIMARY KEY,

    -- Event identification
    event_id VARCHAR(255) NOT NULL UNIQUE,
    event_type VARCHAR(100) NOT NULL,

    -- Timestamps (microsecond precision for MiFID II compliance)
    timestamp TIMESTAMPTZ NOT NULL,
    timestamp_nanos BIGINT NOT NULL,

    -- Transaction tracking
    transaction_id VARCHAR(255) NOT NULL,
    order_id VARCHAR(255) NOT NULL,

    -- Actor information
    actor VARCHAR(255) NOT NULL,
    session_id VARCHAR(255),
    client_ip INET,

    -- Event details (JSONB for structured data)
    details JSONB NOT NULL,
    before_state JSONB,
    after_state JSONB,

    -- Compliance metadata
    compliance_tags TEXT[] NOT NULL,
    risk_level VARCHAR(50) NOT NULL,

    -- Tamper detection and integrity
    digital_signature TEXT,
    checksum VARCHAR(64) NOT NULL,

    -- System timestamp (immutable)
    created_at TIMESTAMPTZ DEFAULT NOW() NOT NULL
);

-- Performance indexes for fast regulatory queries
CREATE INDEX IF NOT EXISTS idx_audit_timestamp ON transaction_audit_events(timestamp DESC);
CREATE INDEX IF NOT EXISTS idx_audit_event_type ON transaction_audit_events(event_type, timestamp DESC);
CREATE INDEX IF NOT EXISTS idx_audit_transaction_id ON transaction_audit_events(transaction_id);
CREATE INDEX IF NOT EXISTS idx_audit_order_id ON transaction_audit_events(order_id);
CREATE INDEX IF NOT EXISTS idx_audit_actor ON transaction_audit_events(actor, timestamp DESC);
CREATE INDEX IF NOT EXISTS idx_audit_compliance_tags ON transaction_audit_events USING GIN(compliance_tags);
CREATE INDEX IF NOT EXISTS idx_audit_risk_level ON transaction_audit_events(risk_level, timestamp DESC);
CREATE INDEX IF NOT EXISTS idx_audit_checksum ON transaction_audit_events(checksum);

-- Composite index for common query patterns
CREATE INDEX IF NOT EXISTS idx_audit_actor_event_time ON transaction_audit_events(actor, event_type, timestamp DESC);
CREATE INDEX IF NOT EXISTS idx_audit_transaction_event ON transaction_audit_events(transaction_id, event_type);

-- Immutability enforcement (SOX compliance requirement)
-- Prevent updates to audit records
CREATE OR REPLACE RULE no_update_audit_events AS
    ON UPDATE TO transaction_audit_events
    DO INSTEAD NOTHING;

-- Prevent deletes to audit records (regulatory requirement)
CREATE OR REPLACE RULE no_delete_audit_events AS
    ON DELETE TO transaction_audit_events
    DO INSTEAD NOTHING;

-- Table partitioning for performance (daily partitions)
-- Note: Partitioning will be implemented via application logic or manual partition creation
-- Example for future reference:
-- CREATE TABLE transaction_audit_events_2025_10 PARTITION OF transaction_audit_events
--     FOR VALUES FROM ('2025-10-01') TO ('2025-11-01');

-- Grant permissions to application roles
GRANT SELECT, INSERT ON transaction_audit_events TO authenticated_users;
GRANT USAGE, SELECT ON SEQUENCE transaction_audit_events_id_seq TO authenticated_users;

-- Table and column comments for documentation
COMMENT ON TABLE transaction_audit_events IS
    'Immutable audit trail for all trading system events - SOX and MiFID II compliance. ' ||
    'Provides microsecond-precision timestamps, tamper detection, and comprehensive event tracking.';

COMMENT ON COLUMN transaction_audit_events.event_id IS 'Unique event identifier (UUID-based)';
COMMENT ON COLUMN transaction_audit_events.event_type IS 'Type of audit event (OrderCreated, OrderExecuted, etc.)';
COMMENT ON COLUMN transaction_audit_events.timestamp IS 'Event timestamp with timezone (microsecond precision)';
COMMENT ON COLUMN transaction_audit_events.timestamp_nanos IS 'Nanosecond precision timestamp for HFT operations';
COMMENT ON COLUMN transaction_audit_events.transaction_id IS 'Transaction identifier for event correlation';
COMMENT ON COLUMN transaction_audit_events.order_id IS 'Order identifier';
COMMENT ON COLUMN transaction_audit_events.actor IS 'User or system that initiated the event';
COMMENT ON COLUMN transaction_audit_events.session_id IS 'Session identifier for user tracking';
COMMENT ON COLUMN transaction_audit_events.client_ip IS 'Client IP address for security audit';
COMMENT ON COLUMN transaction_audit_events.details IS 'Structured event details (symbol, quantity, price, etc.)';
COMMENT ON COLUMN transaction_audit_events.before_state IS 'State before event (for modifications)';
COMMENT ON COLUMN transaction_audit_events.after_state IS 'State after event (for modifications)';
COMMENT ON COLUMN transaction_audit_events.compliance_tags IS 'Compliance framework tags (SOX, MIFID2, etc.)';
COMMENT ON COLUMN transaction_audit_events.risk_level IS 'Risk assessment level (Low, Medium, High, Critical)';
COMMENT ON COLUMN transaction_audit_events.digital_signature IS 'Digital signature for enhanced tamper detection (optional)';
COMMENT ON COLUMN transaction_audit_events.checksum IS 'SHA-256 checksum for tamper detection (required)';
COMMENT ON COLUMN transaction_audit_events.created_at IS 'System insertion timestamp (immutable)';