Arcrun/kbdb/src/types.ts

// KBDB Base types. Base depends on D1 only.
// Optional modules add their own bindings (embed: VECTORIZE+AI). Base never references them.

export type Bindings = {
  DB: D1Database;
  ENVIRONMENT: string;
  // Auth guard (t115 二修, fail-closed): provisioned by the installer automatically.
  // NOT set → writes (POST/PATCH/DELETE/PUT) rejected 401; reads pass with a warning
  //   (upgrade-window grace so read-only workflows don't break before both workers are
  //   updated together).
  // SET     → all non-health routes require `Authorization: Bearer <token>`.
  //   cypher-executor sends this via kbdbBase(); portal/webhooks/recipes send it inline.
  KBDB_INTERNAL_TOKEN?: string;
  // Optional embed module (issue #7 / SDD T2.4). Present ONLY when the self-host opened
  // semantic search (kbdb_embed:true → deploy injects [[vectorize]] + [ai]). Base never
  // requires them; code checks `if (env.VECTORIZE && env.AI)` before touching embed.
  VECTORIZE?: VectorizeIndex;
  AI?: Ai;
  // 嵌入模型（Arcrun#59）。未設＝用 embed.ts 的預設。設成別的模型時，**Vectorize index 的
  // dimensions 必須跟著對**（維度不合 upsert 會被 CF 拒絕），且換模型必須換 index：
  // 不同模型的向量不可共存於同一個 index（比對出來是垃圾），詳見 embed.ts 檔頭。
  EMBED_MODEL?: string;
  // execution_log 每日軟上限（KV 額度事故修復，2026-08-07；A2 自我降級，見
  // kbdb/src/actions/execution-log.ts DEFAULT_DAILY_LIMIT 說明）。未設 → 20000
  // （D1 100,000 rows written/日的 20%，留 80% 給知識卡 entries）。
  EXECUTION_LOG_DAILY_WRITE_LIMIT?: string;
  // embed backfill 每日軟上限（D68，2026-08-11：補算向量照時間新到舊、且每天有額度上限）。
  // backfill 與「寫入即嵌」「萃取」共用同一份 Workers AI 每日 10,000 免費 neurons（見頂層
  // wiki ops-facts.md）；backfill 是背景低優先動作，自設軟上限不把當天額度燒光。未設 → 見
  // kbdb/src/embed.ts DEFAULT_BACKFILL_DAILY_LIMIT 說明（含選值算式，非拍腦袋）。
  EMBED_BACKFILL_DAILY_LIMIT?: string;
  // 背景維護寫入（reconcile 世代核對 + 標庫 backfill）共用的 D1 每日寫入軟上限
  // （Arcrun#85 D69 修法，2026-08-11：兩者都是「多筆 D1 row write、不打 AI」的操作，
  // 各自不設防都會單獨燒穿 D1 100,000 rows/日免費額度——reconcile 47 萬筆 candidate
  // ≈ 4.7 倍全日額度，已在票上實測；標庫 backfill 同樣是逐筆 D1 write，若各管各的，
  // 補標庫時會把 reconcile 的閘繞過去。兩者共用同一顆「今天還剩多少」計數器。
  // 未設 → 見 kbdb/src/actions/maintenance-quota.ts DEFAULT_MAINTENANCE_DAILY_WRITE_LIMIT。
  KBDB_MAINTENANCE_DAILY_WRITE_LIMIT?: string;
};

export type EntryType =
  | 'block'
  | 'value'
  | 'template'
  | 'slot'
  | 'project'
  | 'workflow'
  | 'recipe_stat'
  | 'execution_log'
  | 'execution_log_usage'
  | 'embed_backfill_usage'
  | 'kbdb_maintenance_usage'
  // 樹狀 record 模型（0007，v7 定稿 2026-08-15）：機制節點與關係列。
  // 誠實註記：entry_type 在 v7 §7 的白名單終局裡會整欄消失（型別只能由關係推導），
  // 這裡先沿用它做遷移期的機制列標記——程式邏輯一律以指標欄（src_id IS NOT NULL）判斷
  // 「是不是關係列」，不依賴這個標記。
  | 'relation'   // 一列關係：src ─rel→ dst（池上型別化指標欄）
  | 'record'     // record 的裸身分 entry（block 即 record 時身分是那顆 block，不是這個型別）
  | 'sheet'      // 一張表（template 在池中的身分，id 沿用 template id）
  | 'field'      // 一個欄位（欄名＝關係的謂詞）
  | 'system';    // 啟動常數（sys_root / sys_belongs / sys_field_of）

export interface Entry {
  id: string;
  content: string | null;
  entry_type: EntryType | string;
  owner_id: string | null;
  parent_id: string | null;
  page_name: string | null;
  refs_json: string;
  tags_json: string;
  task_status: string | null;
  content_hash: string | null;
  is_embedded: number;
  confidence: number | null;
  metadata_json: string | null;
  // 關係的物理載體（0007）：池上型別化指標欄。內容 entry 三欄全 NULL；
  // 關係列三欄全非 NULL（src ─rel→ dst）。紅線：指標永不塞回 content/JSON（D91）。
  src_id: string | null;
  rel_id: string | null;
  dst_id: string | null;
  created_at: number;
  updated_at: number;
}

export interface Template {
  id: string;
  name: string;
  description: string | null;
  slots_json: string;
  created_by: string | null;
  created_at: number;
  updated_at: number;
}

export interface EntryValue {
  id: string;
  record_id: string;
  template_id: string;
  slot_name: string;
  entry_id: string;
  created_at: number;
}