kbdb-graph-plugin/src/types.ts

// KBDB Worker 型別定義

export type Bindings = {
  // 插件不碰 DB/Vectorize/AI — 全走基本盤 API（API-as-Wall）。
  // 語意搜尋/embedding 屬基本盤 optional embed 模組，不在插件。
  KBDB_BASE_URL?: string;     // 基本盤 arcrun/kbdb API 網址（leo: 可設定，先留空）
  KBDB_INGEST_URL?: string;   // ingest 服務網址（refresh 代轉對象；T4 就緒前留空）
  KBDB_INTERNAL_TOKEN?: string;
  ENVIRONMENT: string;
  API_KEY?: string;
};

// Hono Context 變數：auth middleware 設定，route handler 使用
export type Variables = {
  namespace: string | null;  // null = internal（無限制），string = partner 的 org_namespace
  partner_id: string;        // 'internal' 或 partner record_id
};

export type EntityType = 'person' | 'event' | 'product' | 'market' | 'org';

export type TripletStatus = 'active' | 'deprecated';

export type Triplet = {
  id: string;
  subject: string;
  predicate: string;
  object: string;
  source_block_id: string | null;
  confidence: number;
  clusters: string[];           // 所屬的知識群集，用於跨領域偵測
  bridge_score: number;         // 跨越的 cluster 數量，Scout 發現指標
  subject_entity_type: EntityType | null;  // 主體 entity 類型（人格疊加局勢分析用）
  object_entity_type: EntityType | null;   // 客體 entity 類型
  status: TripletStatus;        // active（進圖遍歷）| deprecated（被取代，可查/可 rollback）
  superseded_by: string | null; // 取代它的新 record id（active 時為 null）
  source_uri: string | null;    // ingest 來源穩定識別（idempotency 分組鍵 + get_source 指標）
  content_hash: string | null;  // 來源快照 hash（idempotency 比對鍵）
  source_anchor: string | null; // 檔內定位（heading slug / block id），get_source 精準回跳
  created_at: number;
  updated_at: number;
};

// 圖遍歷結果
export type GraphNode = {
  node: string;
  level: number;
  edges: Triplet[];
};

// --- Entity Normalization 型別 ---

export type Entity = {
  id: string;
  canonical: string;
  aliases: string[];
};

export type PendingAlias = {
  id: string;
  raw_name: string;
  candidate_entity_id: string;
  candidate_canonical: string;
  similarity: number;
  created_at: number;
};