Bản ghi và sai lệch

Bản ghi (Record) là một sự kiện thực tế từ một nguồn đã xác định. Sự kiện sai lệch (Drift Event) là một diễn giải theo mục tiêu định hướng (Vision Target), có bằng chứng (Evidence) tường minh hỗ trợ. Tạo Record không bao giờ tự động tạo diễn giải sai lệch.

Bản ghi

function createRecord(
  input: Omit<RecordEvent, 'type' | 'schema_version'>
): RecordEvent

Bên gọi cung cấp:

id và kind có thể mở rộng
occurred_at ở dạng ngày giờ
source.integration, source.external_id và source.repository tùy chọn
actors là người hoặc tác tử
references tường minh
đối tượng data tương thích JSON chứa dữ kiện nguồn

createRecord chỉ thêm type: 'record' và schema_version: 1, rồi kiểm tra toàn bộ vỏ bọc. Nó không tạo dấu thời gian hay lấy chi tiết từ nguồn.

Để có định danh sự kiện ổn định của nhà cung cấp, SDK còn xuất:

recordId(integration: string, sourceId: string, eventId: string): string

Hàm băm định danh ba phần có thứ tự và trả về ID có tiền tố REC-. Bên gọi nên dùng định danh bất biến của nhà cung cấp, không dùng tiêu đề.

Sự kiện sai lệch

function createDrift(
  input: Omit<DriftEvent, 'type' | 'schema_version'>
): DriftEvent

Một Drift Event yêu cầu:

id và vision_target_id
state: 'expected' | 'unexpected'
impact với unit, before, delta và after
actors là người hoặc tác tử
references tường minh
reasoning có phiên bản
created_at tùy chọn

Các đơn vị tác động là percentage_points, ratio và score_points. impact.after phải bằng impact.before + impact.delta trong phạm vi độ chính xác dấu phẩy động.

Các phương pháp lập luận là human, deterministic và llm. Mỗi mục reasoning.evidence_refs phải xác định một mục trong references. Lập luận LLM còn yêu cầu danh sách bằng chứng không rỗng và model; khi có model_version, cũng phải có model. Vỏ bọc lập luận dùng schema_version: 1.

createDrift chỉ thêm kiểu và phiên bản lược đồ ở cấp cao nhất rồi kiểm tra kết quả. Nó không quyết định thay đổi có đúng dự kiến không, tính tác động, chọn đơn vị, tìm bằng chứng hay chạy bộ máy lập luận.

SDK chủ ý không định nghĩa công thức Product Vision. Lưu trữ, phân quyền định danh và chính sách diễn giải thuộc về một môi trường chạy được thiết kế riêng.