// library-map（藏書地圖）— 聚合 SQL 的家（SDD system-dev/docs/3-specs/library-map/design.md §2）。
// D6 鐵律推論：degree 排序／predicate 統計／跨庫 join 是聚合 SQL，插件與 workflow 全程禁 SQL，
// 所以重算只能住 kbdb base 本體（本檔）。三表不變量不破：地圖＝library_map template 的 record
//（每庫一個 map block）＋slots，零建表零 ALTER。
//
// triplet 按庫定位現況（2026-07-19 對 prod 核實，design §1 的「先核實」）：
//   - triplet template（prod 名 'triplet'，kbdb-graph 建）有 source_uri slot、無 library slot；
//   - entries 的 metadata.library 機制在（portal-auth P1）但既有資料未標記（?library=kb → 0 筆）。
//   → 依 SDD 預案：在 triplet template schema 加 optional `library` slot（改 template 不動表，
//     見 ensureTripletLibrarySlot）；ingest 端補寫值屬 M3。過渡期（舊 triplet 沒有 library slot 值）
//     recompute 可帶 source_prefix 參數用 source_uri 前綴當 fallback 過濾——由 caller 提供前綴，
//     base 不寫死任何 URI 格式語意（base 對內容語意無知的既有原則）。
import { createEntry, getEntry } from './entry-crud';
import { createRecord, createTemplate, getTemplate, updateRecord, updateTemplate } from './record-crud';

export const LIBRARY_MAP_TEMPLATE_ID = 'tpl-library-map';
export const LIBRARY_MAP_TEMPLATE_NAME = 'library_map';
// 與 migrations/0003_library_map.sql 的 seed 同一份定義（兩邊必須一致）。
export const LIBRARY_MAP_SLOTS = [
  'library',
  'narrative',
  'top_entities',
  'relation_profile',
  'bridges',
  'triplet_count',
  'commit_hash',
  'status',
];
// prod 實際部署的 triplet template 名（kbdb_list_templates 核實）；caller 可用參數覆蓋。
export const DEFAULT_TRIPLET_TEMPLATE = 'triplet';

export interface TopEntity { name: string; degree: number }
export interface RelationStat { predicate: string; count: number }
export interface Bridge { entity: string; libraries: string[] }

export interface LibraryMapRow {
  library: string;
  narrative: string | null;
  top_entities: string[]; // 全館視圖只回 top 3 名字（數百 token 內，design §4 MCP instructions 用）
  triplet_count: number;
  // Arcrun#87 三次收尾（2026-08-13，「藏書地圖說實話」）：triplet_count＝0 不等於「這庫沒有知識」——
  // entries（ingest 進來的原始卡片/skill 內容）與 triplet（從 entries 萃取出的三元組）是兩件事，
  // 一個庫可能有大量 entries、但三元組萃取從沒對它跑過（實測：kb 以外 7 庫皆此況，entries 存在
  // 且 library 標記正確，triplet 一筆都沒有）。entry_count 讓讀端（AI／MCP 渲染層）分得清
  // 「真的沒東西」與「有東西但還沒被萃取成三元組」，不再把後者誤讀成前者、誤判庫是空的而放棄查詢
  // （見本檔 liveEntryCountsByLibrary 的計數口徑）。
  entry_count: number;
  updated_at: number;
}

export interface LibraryMapDetail {
  record_id: string;
  library: string;
  narrative: string | null;
  content: string | null; // map block 的可嵌人話（design §5，M6 semantic 路由直接用）
  top_entities: TopEntity[];
  relation_profile: RelationStat[];
  bridges: Bridge[];
  triplet_count: number;
  entry_count: number; // 同 LibraryMapRow.entry_count（見該欄位註解）
  commit_hash: string | null;
  status: string;
  updated_at: number;
}

export interface RecomputeInput {
  library: string;
  narrative?: string;      // wiki 首段抽取屬 ingest 端（M3）——base 只收值不抽取
  commit_hash?: string;
  owner_id?: string;
  source_prefix?: string;  // 過渡 fallback：library slot 缺值的舊 triplet 以 source_uri LIKE 前綴歸庫
  triplet_template?: string;
  top_n?: number;          // top_entities 取幾個（預設 10、上限 50）
}

export interface RecomputeResult {
  map: LibraryMapDetail;
  superseded: string[];            // 被標 superseded 的舊 map record ids
  triplet_template: string;
  triplet_library_slot_added: boolean; // 本次是否幫 triplet template 補上 optional library slot
}

// ---- template ensure（M1） ----

// library_map template 若不存在就走既有 createTemplate 路徑補建（migration 0003 的 runtime 保險）。
// UNIQUE(name) 撞到（並發/半套 seed）→ 重讀即可，冪等。
export async function ensureLibraryMapTemplate(db: D1Database): Promise<void> {
  const existing = await getTemplate(db, LIBRARY_MAP_TEMPLATE_NAME);
  if (existing) return;
  try {
    await createTemplate(db, {
      id: LIBRARY_MAP_TEMPLATE_ID,
      name: LIBRARY_MAP_TEMPLATE_NAME,
      description: 'per-library map block（藏書地圖：graph 機械導出，零 LLM 生成；Arcrun#39）',
      slots: LIBRARY_MAP_SLOTS,
      created_by: 'system',
    });
  } catch {
    if (!(await getTemplate(db, LIBRARY_MAP_TEMPLATE_NAME))) throw new Error('ensureLibraryMapTemplate failed');
  }
}

// triplet template schema 加 optional `library` slot（design §1 預案：改 template 不動表）。
// 只增不減、冪等；ingest 端（M3）開始寫值後，recompute 就能按 slot 精準歸庫，不再靠 source_prefix。
export async function ensureTripletLibrarySlot(db: D1Database, tripletTemplate: string): Promise<boolean> {
  const tpl = await getTemplate(db, tripletTemplate);
  if (!tpl) throw new Error(`triplet template not found: ${tripletTemplate}`);
  const slots: string[] = JSON.parse(tpl.slots_json);
  if (slots.includes('library')) return false;
  await updateTemplate(db, tpl.id, { slots: [...slots, 'library'] });
  return true;
}

// ---- 聚合 SQL（M2 recompute） ----

// record → 一列一 triplet 的 pivot（0007 樹狀 record 模型：格子＝關係列）。
// b＝歸屬關係列（rel=sys_belongs, dst=template 的 sheet entry）＝record 成員名單；
// r＝該 record 的格子關係列；v＝格子指到的內容 entry。欄位謂詞 id 決定性衍生
// （fld_<template>_<slot>，與 0007 遷移、record-crud fieldEntryId 同一條規則）⇒
// 直接用字串串接比對，不必 JOIN field entry。MAX(CASE …) 縱轉橫慣用法照舊；
// owner filter 下在歸屬關係列的 owner_id（createRecord 寫入時同值，0007 遷移同一推導）。
// 參數簽名與舊版逐字相同：[template_id, owner?]。
function tripletPivotSql(ownerFiltered: boolean): string {
  return `SELECT b.src_id AS rid,
       MAX(CASE WHEN r.rel_id = 'fld_' || b.dst_id || '_subject' THEN v.content END) AS subject,
       MAX(CASE WHEN r.rel_id = 'fld_' || b.dst_id || '_object' THEN v.content END) AS object,
       MAX(CASE WHEN r.rel_id = 'fld_' || b.dst_id || '_predicate' THEN v.content END) AS predicate,
       MAX(CASE WHEN r.rel_id = 'fld_' || b.dst_id || '_status' THEN v.content END) AS status,
       MAX(CASE WHEN r.rel_id = 'fld_' || b.dst_id || '_library' THEN v.content END) AS library,
       MAX(CASE WHEN r.rel_id = 'fld_' || b.dst_id || '_source_uri' THEN v.content END) AS source_uri
     FROM entries b
     LEFT JOIN entries r ON r.src_id = b.src_id AND r.rel_id != 'sys_belongs'
     LEFT JOIN entries v ON v.id = r.dst_id
     WHERE b.rel_id = 'sys_belongs' AND b.dst_id = ?${ownerFiltered ? ' AND b.owner_id = ?' : ''}
     GROUP BY b.src_id`;
}

// library_map 自身 record 的 pivot（讀端＋supersede 查找共用；同上 0007 形狀）。
function mapPivotSql(ownerFiltered: boolean): string {
  return `SELECT b.src_id AS rid,
       MAX(CASE WHEN r.rel_id = 'fld_' || b.dst_id || '_library' THEN v.content END) AS library,
       MAX(CASE WHEN r.rel_id = 'fld_' || b.dst_id || '_narrative' THEN v.content END) AS narrative,
       MAX(CASE WHEN r.rel_id = 'fld_' || b.dst_id || '_top_entities' THEN v.content END) AS top_entities,
       MAX(CASE WHEN r.rel_id = 'fld_' || b.dst_id || '_relation_profile' THEN v.content END) AS relation_profile,
       MAX(CASE WHEN r.rel_id = 'fld_' || b.dst_id || '_bridges' THEN v.content END) AS bridges,
       MAX(CASE WHEN r.rel_id = 'fld_' || b.dst_id || '_triplet_count' THEN v.content END) AS triplet_count,
       MAX(CASE WHEN r.rel_id = 'fld_' || b.dst_id || '_commit_hash' THEN v.content END) AS commit_hash,
       MAX(CASE WHEN r.rel_id = 'fld_' || b.dst_id || '_status' THEN v.content END) AS status,
       MAX(r.created_at) AS ts
     FROM entries b
     LEFT JOIN entries r ON r.src_id = b.src_id AND r.rel_id != 'sys_belongs'
     LEFT JOIN entries v ON v.id = r.dst_id
     WHERE b.rel_id = 'sys_belongs' AND b.dst_id = ?${ownerFiltered ? ' AND b.owner_id = ?' : ''}
     GROUP BY b.src_id`;
}

function parseJsonArray<T>(raw: string | null | undefined): T[] {
  if (!raw) return [];
  try {
    const v = JSON.parse(raw);
    return Array.isArray(v) ? (v as T[]) : [];
  } catch {
    return [];
  }
}

export async function recomputeLibraryMap(db: D1Database, input: RecomputeInput): Promise<RecomputeResult> {
  const library = input.library.trim();
  if (!library) throw new Error('library required');
  const tripletTemplateName = input.triplet_template ?? DEFAULT_TRIPLET_TEMPLATE;
  const topN = Math.min(Math.max(Math.floor(input.top_n ?? 10), 1), 50);

  await ensureLibraryMapTemplate(db);
  // 順手把 optional library slot 補進 triplet template（M1；冪等，不動表）。
  const librarySlotAdded = await ensureTripletLibrarySlot(db, tripletTemplateName);
  const tripletTpl = await getTemplate(db, tripletTemplateName);
  if (!tripletTpl) throw new Error(`triplet template not found: ${tripletTemplateName}`);

  const owner = input.owner_id || undefined;
  const pivot = tripletPivotSql(!!owner);
  const pivotParams: unknown[] = owner ? [tripletTpl.id, owner] : [tripletTpl.id];

  // 歸庫謂詞：library slot 優先；caller 給了 source_prefix 才對「沒有 library 值的舊 triplet」
  // 啟用 source_uri 前綴 fallback（M3 backfill 完成前的過渡；base 不解析 URI 語意）。
  const libCond = input.source_prefix
    ? `(t.library = ? OR (t.library IS NULL AND t.source_uri LIKE ? || '%'))`
    : `t.library = ?`;
  const libParams: unknown[] = input.source_prefix ? [library, input.source_prefix] : [library];
  // 只算 active triplet（superseded/deprecated 不進地圖；沒有 status slot 的舊資料視同 active）。
  const withLib = `WITH t AS (${pivot}), lib AS (
     SELECT * FROM t WHERE COALESCE(t.status, 'active') = 'active' AND ${libCond})`;
  const baseParams = [...pivotParams, ...libParams];

  const [countRow, topRes, relRes, bridgeRes] = await Promise.all([
    db.prepare(`${withLib} SELECT COUNT(*) AS n FROM lib`).bind(...baseParams).first<{ n: number }>(),
    // degree＝entity 在該庫 active triplet 的出現次數（subject＋object 兩側都算；同名並列取名字序穩定輸出）
    db
      .prepare(
        `${withLib} SELECT name, COUNT(*) AS degree FROM (
           SELECT subject AS name FROM lib UNION ALL SELECT object AS name FROM lib)
         WHERE name IS NOT NULL GROUP BY name ORDER BY degree DESC, name ASC LIMIT ?`,
      )
      .bind(...baseParams, topN)
      .all<{ name: string; degree: number }>(),
    // predicate 分布＝庫的「性格」（spec §3 relation_profile）
    db
      .prepare(
        `${withLib} SELECT predicate, COUNT(*) AS n FROM lib
         WHERE predicate IS NOT NULL GROUP BY predicate ORDER BY n DESC, predicate ASC LIMIT 100`,
      )
      .bind(...baseParams)
      .all<{ predicate: string; n: number }>(),
    // bridges＝本庫 entity 同時出現在其他庫（跨庫 join）。對面那側只能靠 library slot 標記值
    //（source_prefix 只描述本庫的前綴，無法反推他庫）→ M3 backfill 前 bridges 會偏稀疏，誠實現況。
    db
      .prepare(
        `${withLib}, labeled AS (
           SELECT DISTINCT name, library FROM (
             SELECT subject AS name, library FROM t WHERE COALESCE(status,'active') = 'active'
             UNION SELECT object AS name, library FROM t WHERE COALESCE(status,'active') = 'active')
           WHERE name IS NOT NULL AND library IS NOT NULL AND library != ?),
         mine AS (
           SELECT DISTINCT subject AS name FROM lib WHERE subject IS NOT NULL
           UNION SELECT DISTINCT object AS name FROM lib WHERE object IS NOT NULL)
         SELECT l.name AS entity, l.library AS library FROM labeled l
         JOIN mine m ON m.name = l.name ORDER BY l.name ASC, l.library ASC`,
      )
      .bind(...baseParams, library)
      .all<{ entity: string; library: string }>(),
  ]);

  const tripletCount = countRow?.n ?? 0;
  const topEntities: TopEntity[] = (topRes.results ?? []).map((r) => ({ name: r.name, degree: r.degree }));
  const relationProfile: RelationStat[] = (relRes.results ?? []).map((r) => ({ predicate: r.predicate, count: r.n }));
  // GROUP_CONCAT 不用（entity 名可能含逗號）→ 取 (entity, library) 對在 JS 聚合，上限 50 個橋接點。
  const bridgeMap = new Map<string, string[]>();
  for (const r of bridgeRes.results ?? []) {
    if (!bridgeMap.has(r.entity) && bridgeMap.size >= 50) continue;
    const libs = bridgeMap.get(r.entity) ?? [];
    if (!libs.includes(r.library)) libs.push(r.library);
    bridgeMap.set(r.entity, libs);
  }
  const bridges: Bridge[] = [...bridgeMap.entries()].map(([entity, libraries]) => ({ entity, libraries }));

  // map block 的 content＝可嵌人話（design §5：之後 M6 semantic 路由第一跳直接嵌這句做庫路由）。
  // narrative：caller 有給才覆蓋；沒給 → 沿用上一版現有 narrative（若有）。
  // 2026-08-08 修正：這欄原本「沒給就清空」，會被下面新增的即時新鮮度層
  // （ensureFreshLibraryMaps，讀端自動重算、天生不帶 narrative）每次呼叫都靜默洗掉
  // ingest 端/人工填過的 narrative——沒給值＝維持現狀，不是重置成空字串。
  let narrative = input.narrative?.trim();
  if (!narrative) {
    const prev = await getLibraryMapDetail(db, library, owner);
    narrative = prev?.narrative?.trim() || '';
  }
  const coreNames = topEntities.slice(0, 3).map((t) => t.name);
  const content = `${library}：${narrative || '（narrative 待 ingest 補寫）'}。核心：${
    coreNames.length ? coreNames.join('、') : '（尚無 entities）'
  }`;

  // 寫入順序安全（design §2「交易式或至少順序安全」；D1 無跨語句交易）：
  // 先建新 active block＋record，成功後才把舊的標 superseded——中途失敗最壞是多一個 active，
  // 讀端一律取最新 active，不會出現「地圖真空」。
  const blockEntry = await createEntry(db, {
    content,
    entry_type: 'block',
    owner_id: owner ?? null,
    page_name: `library-map:${library}`,
    metadata_json: JSON.stringify({ kind: 'library_map', library }),
  });
  const values: Record<string, string> = {
    library,
    narrative,
    top_entities: JSON.stringify(topEntities),
    relation_profile: JSON.stringify(relationProfile),
    bridges: JSON.stringify(bridges),
    triplet_count: String(tripletCount),
    status: 'active',
  };
  if (input.commit_hash) values.commit_hash = input.commit_hash;
  // record_id＝map block entry 的 id：block（人話 content）與 record（結構化 slots）同一身分，
  // 讀端一次定位、embed 模組（M6）也直接嵌這顆 entry。
  await createRecord(db, {
    template: LIBRARY_MAP_TEMPLATE_NAME,
    record_id: blockEntry.id,
    values,
    owner_id: owner ?? null,
  });

  // 舊 active map（同庫、非本次新建）→ 標 superseded（沿用既有 status slot 語意，R6）。
  const mapTpl = await getTemplate(db, LIBRARY_MAP_TEMPLATE_NAME);
  const oldParams: unknown[] = owner ? [mapTpl!.id, owner, library, blockEntry.id] : [mapTpl!.id, library, blockEntry.id];
  const oldRes = await db
    .prepare(
      `WITH m AS (${mapPivotSql(!!owner)})
       SELECT rid FROM m WHERE m.library = ? AND COALESCE(m.status, 'active') = 'active' AND m.rid != ?`,
    )
    .bind(...oldParams)
    .all<{ rid: string }>();
  const superseded: string[] = [];
  for (const row of oldRes.results ?? []) {
    await updateRecord(db, row.rid, { status: 'superseded' });
    superseded.push(row.rid);
  }

  // entry_count（Arcrun#87 三次收尾）：recompute 只重算三元組那一半，entry_count 是即時算的
  // 另一半，兩者同樣的道理一起回傳（見 LibraryMapDetail.entry_count 欄位註解）。
  const entryCount = (await liveEntryCountsByLibrary(db, owner)).get(library) ?? 0;

  return {
    map: {
      record_id: blockEntry.id,
      library,
      narrative: narrative || null,
      content,
      top_entities: topEntities,
      relation_profile: relationProfile,
      bridges,
      triplet_count: tripletCount,
      entry_count: entryCount,
      commit_hash: input.commit_hash ?? null,
      status: 'active',
      updated_at: blockEntry.created_at,
    },
    superseded,
    triplet_template: tripletTemplateName,
    triplet_library_slot_added: librarySlotAdded,
  };
}

// ---- 即時新鮮度（M3 收尾，2026-08-08） ----
//
// 真因（總管實測＋wiki system-dev/wiki/mistakes.md「08-08」段）：design §3 原訂「ingest 完成 →
// 逐庫呼 POST /map/recompute」，但 repo 內查無任何呼叫點——三週沒接上，導致沒手動 backfill 過的
// 租戶（絕大多數）GET /map 恆回空，且 M4 的 MCP 說明文字還宣稱「地圖由 ingest 尾端自動重算」
// （不存在的事）。leo 拍板此功能是 arcrun 最重要的入口（「讓 AI 一眼看到所有庫的摘要」），
// 且明確否決「降級成只算 count 的即時聚合」（那樣會丟失 narrative／relation_profile／bridges
// 這些 summary 本體，narrative 沒辦法從純聚合 SQL 現算出來）。
//
// 解法：不再依賴任何外部呼叫者記得呼 /map/recompute，改成讀端（GET /map、GET /map/:library）
// 自己核對即時三元組數，落差就地呼叫既有的 recomputeLibraryMap 補算——聚合 SQL 沒有第二套，
// 只是觸發時機從「等外部呼叫」改成「讀的當下順手核對」。這同時解掉三件事：
//   一、全租戶自動 backfill（不需要用戶或任何人做任何事，第一次讀就會補齊）
//   二、跟得上資料（下一筆 ingest 進來，觸發計數變化，下一次讀就重算，不是靜態快照）
//   三、不依賴 ingest workflow 那端的接鏈（那條線跨 repo／跨租戶天生脆弱，已證實三週沒人接上）
// narrative／relation_profile／bridges 這些「摘要」欄位仍走 recomputeLibraryMap 原封不動的邏輯，
// 不是砍成只算數字——與 leo 否決的「降級方案」不同款。

// 型別別名：避免巢狀泛型連寫（Map/Set 的收尾兩個角括號會被 workflow 意圖語法的三段箭頭規則
// 誤判成 `>> `），純粹是繞開該 lint 的寫法選擇，語意不變。
type LibraryCountMap = Map<string, number>;
type LibraryNameSet = Set<string>;

// 這個 owner 底下、依 triplet 自身 'library' slot 分組的即時三元組數（缺 library slot 值的舊
// triplet 歸 'general'）——與 GET /records/triplet-stats（t142）同一套分組語意，兩處數字對得上。
//
// 2026-08-11 修根因（Arcrun#87，動工前量測 comment 第四節）：這裡原本完全不過濾 status，
// 而 recomputeLibraryMap（上方 withLib）只算 COALESCE(status,'active')='active'。兩邊判準不
// 一致，只要有一筆 superseded triplet，這裡的即時計數就會跟重算後的快取對不上，
// ensureFreshLibraryMaps 判定 stale，每次讀地圖都觸發重算，每次都新建一筆 library_map
// record（superseded 舊的），無止盡寫 D1，且加劇 recomputeLibraryMap 本身非原子 supersede
// 的競態（另一個已知病，wiki 08-10 條目）。實測：間隔數秒連讀兩次地圖、中間無任何寫入動作，
// updated_at 仍前進。修法：這裡的 status 判準改成與 recomputeLibraryMap 逐字一致，兩邊算出
// 的計數才會在資料未變動時相等，stale 判定回歸「真的有資料變動才 stale」。
async function liveTripletCountsByLibrary(
  db: D1Database,
  tripletTemplateId: string,
  owner_id?: string,
): Promise<LibraryCountMap> {
  const params: unknown[] = owner_id ? [tripletTemplateId, owner_id] : [tripletTemplateId];
  const res = await db
    .prepare( // kbdb-sql-ok：牆內本體（kbdb/src/actions/），checkout 開在巢狀 worktree matrix/arcrun/.worktree-fix-87/（避免打斷另一 session 佔用中的 matrix/arcrun 主 checkout），hook 逐字比對 matrix/arcrun/kbdb/src/ 吃不到中間多出的 worktree 目錄層，非繞牆
      `SELECT COALESCE(NULLIF(tr.library, ''), 'general') AS library, COUNT(*) AS n
       FROM (
         SELECT b.src_id AS rid,
              MAX(CASE WHEN r.rel_id = 'fld_' || b.dst_id || '_status' THEN v.content END) AS status,
              MAX(CASE WHEN r.rel_id = 'fld_' || b.dst_id || '_library' THEN v.content END) AS library
         FROM entries b
         LEFT JOIN entries r ON r.src_id = b.src_id AND r.rel_id != 'sys_belongs'
         LEFT JOIN entries v ON v.id = r.dst_id
         WHERE b.rel_id = 'sys_belongs' AND b.dst_id = ?${owner_id ? ' AND b.owner_id = ?' : ''}
         GROUP BY b.src_id
       ) AS tr
       WHERE COALESCE(tr.status, 'active') = 'active'
       GROUP BY COALESCE(NULLIF(tr.library, ''), 'general')`,
    )
    .bind(...params)
    .all<{ library: string; n: number }>();
  const m: LibraryCountMap = new Map();
  for (const r of res.results ?? []) m.set(r.library, r.n);
  return m;
}

// 這個 owner 底下、依 entries 自己的 metadata_json.$.library 分組的即時「原始內容」數
//（Arcrun#87 三次收尾，2026-08-13）——與 liveTripletCountsByLibrary 算的是兩張完全不同的帳：
// 那個算「萃取出幾條三元組」，這個算「ingest 進來幾筆原始卡片/skill/block」。兩者天生會不一樣
// （萃取是下游、有延遲甚至從沒對某些庫跑過），刻意分開算、分開回傳，不是同一數字的兩種寫法。
//
// 排除口徑（都是結構性排除，不是內容語意判斷——沒有違反「base 對內容語意無知」）：
//   - entry_type='value'：record-crud.ts 的通用機制，任何 template（含 triplet 本身）建 record
//     時每個 slot 值都會落一筆這種 entry，是儲存實作細節，不是使用者看得到的「一筆知識」。
//   - metadata.kind='library_map' 的 block：地圖自己每次 recompute 產出的摘要 block（含歷史
//     superseded 的），算進去會自我膨脹、且無限接近雞生蛋——地圖不該把自己算進地圖裡。
async function liveEntryCountsByLibrary(db: D1Database, owner_id?: string): Promise<LibraryCountMap> {
  const params: unknown[] = owner_id ? [owner_id] : [];
  const res = await db
    .prepare( // kbdb-sql-ok：牆內本體（kbdb/src/actions/），checkout 開在巢狀 worktree /private/tmp/wt-arcrun-library-map-honesty-87/（同 962d863/5919c6b 已記載的假警報成因：hook 逐字比對 matrix/arcrun/kbdb/src/ 吃不到中間多出的 worktree 目錄層，非繞牆）
      `SELECT COALESCE(NULLIF(json_extract(metadata_json, '$.library'), ''), 'general') AS library,
              COUNT(*) AS n
       FROM entries
       WHERE ${owner_id ? 'owner_id = ? AND ' : ''}entry_type != 'value'
         AND src_id IS NULL
         AND entry_type NOT IN ('record', 'sheet', 'field', 'system')
         AND NOT (entry_type = 'block' AND COALESCE(json_extract(metadata_json, '$.kind'), '') = 'library_map')
       GROUP BY COALESCE(NULLIF(json_extract(metadata_json, '$.library'), ''), 'general')`,
    )
    .bind(...params)
    .all<{ library: string; n: number }>();
  const m: LibraryCountMap = new Map();
  for (const r of res.results ?? []) m.set(r.library, r.n);
  return m;
}

// 「已知庫名」集合：即使目前三元組數是 0，只要蓋過章（entries metadata.library，t52 慣例）或
// 登記過（portal_library record），就不算「查無此庫」——用來分辨 GET /map/:library 的
// 「這庫是空的」（回 200＋triplet_count:0）vs「查無此庫」（回 404）。kbdb base 對 portal_library
// 的語意無知，只是把它當一個普通 template 讀 name slot（不違反 D6 base 對內容語意無知的既有原則）。
async function knownLibraryNames(db: D1Database, owner_id?: string): Promise<LibraryNameSet> {
  const names: LibraryNameSet = new Set();
  const entryParams: unknown[] = owner_id ? [owner_id] : [];
  const entryRows = await db
    .prepare(
      `SELECT DISTINCT json_extract(metadata_json, '$.library') AS library FROM entries
       WHERE ${owner_id ? 'owner_id = ?' : '1=1'} AND json_extract(metadata_json, '$.library') IS NOT NULL`,
    )
    .bind(...entryParams)
    .all<{ library: string | null }>();
  for (const r of entryRows.results ?? []) if (r.library) names.add(r.library);

  const libTpl = await getTemplate(db, 'portal_library');
  if (libTpl) {
    const libParams: unknown[] = owner_id ? [libTpl.id, owner_id] : [libTpl.id];
    const libRows = await db
      .prepare(
        `SELECT MAX(CASE WHEN r.rel_id = 'fld_' || b.dst_id || '_name' THEN v.content END) AS name
         FROM entries b
         LEFT JOIN entries r ON r.src_id = b.src_id AND r.rel_id != 'sys_belongs'
         LEFT JOIN entries v ON v.id = r.dst_id
         WHERE b.rel_id = 'sys_belongs' AND b.dst_id = ?${owner_id ? ' AND b.owner_id = ?' : ''}
         GROUP BY b.src_id`,
      )
      .bind(...libParams)
      .all<{ name: string | null }>();
    for (const r of libRows.results ?? []) if (r.name) names.add(r.name);
  }
  return names;
}

// 核對＋補算：這個 owner 底下所有「即時有三元組」或「已知但地圖過期/缺失」的庫，一次核對、
// 只對真的落差的庫重算（平行跑，單庫失敗不擋其他庫、不擋讀取——地圖是加分不是硬依賴）。
// 沒有 triplet template（這顆 KBDB 從沒建過任何三元組）→ 無地圖可算，直接返回，不報錯。
export async function ensureFreshLibraryMaps(
  db: D1Database,
  owner_id?: string,
  tripletTemplateName: string = DEFAULT_TRIPLET_TEMPLATE,
): Promise<void> {
  const tripletTpl = await getTemplate(db, tripletTemplateName);
  if (!tripletTpl) return;

  const [liveCounts, cached, known] = await Promise.all([
    liveTripletCountsByLibrary(db, tripletTpl.id, owner_id),
    listLibraryMaps(db, owner_id),
    knownLibraryNames(db, owner_id),
  ]);
  const cachedByLib = new Map(cached.map((m) => [m.library, m]));

  const stale = new Set<string>();
  for (const [library, count] of liveCounts) {
    const c = cachedByLib.get(library);
    if (!c || c.triplet_count !== count) stale.add(library);
  }
  // 已知庫但目前沒有三元組、也從沒算過地圖 → 補算一次讓它以「空庫」現身（triplet_count:0），
  // 不是完全消失；已經算過的空庫不重複補（避免對永遠空的庫每次都白重算）。
  for (const name of known) {
    if (!liveCounts.has(name) && !cachedByLib.has(name)) stale.add(name);
  }

  await Promise.all(
    [...stale].map((library) =>
      recomputeLibraryMap(db, { library, owner_id, triplet_template: tripletTemplateName }).catch(() => {
        // 單庫重算失敗（如聚合 SQL 撞到髒資料）不擋其他庫、不擋讀取——鐵律：地圖是加分不是依賴。
      }),
    ),
  );
}

// ---- 讀端（M2 GET） ----

interface MapPivotRow {
  rid: string;
  library: string | null;
  narrative: string | null;
  top_entities: string | null;
  relation_profile: string | null;
  bridges: string | null;
  triplet_count: string | null;
  commit_hash: string | null;
  status: string | null;
  ts: number;
}

// 全館地圖：每庫一行（library＋narrative＋top 3 entities＋triplet_count＋entry_count），MCP
// instructions 直接嵌用（設計上限＝數百 token，R3）。template 還不存在（從未 recompute）→
// 誠實回空清單。entry_count 與 triplet_count 並排回傳（Arcrun#87 三次收尾）：一個查「原始內容
// 有沒有」、一個查「萃取出幾條三元組」，兩者不同源、允許不一致（見 liveEntryCountsByLibrary
// 註解），讀端不該把其中一個的 0 當成另一個的答案。
export async function listLibraryMaps(db: D1Database, owner_id?: string): Promise<LibraryMapRow[]> {
  const tpl = await getTemplate(db, LIBRARY_MAP_TEMPLATE_NAME);
  if (!tpl) return [];
  const params: unknown[] = owner_id ? [tpl.id, owner_id] : [tpl.id];
  const [res, entryCounts] = await Promise.all([
    db
      .prepare( // kbdb-sql-ok：牆內本體（kbdb/src/actions/），既有查詢（listLibraryMaps 原本就有）此次改包進 Promise.all 才重新觸發掃描，非新增違規；worktree 路徑假警報同上方 liveEntryCountsByLibrary 註解
        `WITH m AS (${mapPivotSql(!!owner_id)})
         SELECT * FROM m WHERE COALESCE(m.status, 'active') = 'active' AND m.library IS NOT NULL
         ORDER BY m.ts DESC`,
      )
      .bind(...params)
      .all<MapPivotRow>(),
    liveEntryCountsByLibrary(db, owner_id),
  ]);
  // 每庫只留最新 active（supersede 失敗殘留多個 active 時，讀端自癒取最新——順序安全的另一半）。
  const byLib = new Map<string, LibraryMapRow>();
  for (const r of res.results ?? []) {
    if (!r.library || byLib.has(r.library)) continue;
    byLib.set(r.library, {
      library: r.library,
      narrative: r.narrative || null,
      top_entities: parseJsonArray<TopEntity>(r.top_entities).slice(0, 3).map((t) => t.name),
      triplet_count: Number(r.triplet_count ?? 0) || 0,
      entry_count: entryCounts.get(r.library) ?? 0,
      updated_at: r.ts,
    });
  }
  return [...byLib.values()].sort((a, b) => a.library.localeCompare(b.library));
}

// 單庫詳圖：完整 slots＋map block 的人話 content。
export async function getLibraryMapDetail(
  db: D1Database,
  library: string,
  owner_id?: string,
): Promise<LibraryMapDetail | null> {
  const tpl = await getTemplate(db, LIBRARY_MAP_TEMPLATE_NAME);
  if (!tpl) return null;
  const params: unknown[] = owner_id ? [tpl.id, owner_id, library] : [tpl.id, library];
  const row = await db
    .prepare(
      `WITH m AS (${mapPivotSql(!!owner_id)})
       SELECT * FROM m WHERE m.library = ? AND COALESCE(m.status, 'active') = 'active'
       ORDER BY m.ts DESC LIMIT 1`,
    )
    .bind(...params)
    .first<MapPivotRow>();
  if (!row) return null;
  // record_id＝map block entry id（recompute 寫入時綁定）；entry 若被外力刪除，content 誠實回 null。
  // entry_count 與全館視圖（listLibraryMaps）同一套計法（liveEntryCountsByLibrary），單庫詳圖
  // 只取自己那一庫的數字——Arcrun#87 三次收尾，理由見 LibraryMapDetail.entry_count 欄位註解。
  const [blockEntry, entryCounts] = await Promise.all([
    getEntry(db, row.rid),
    liveEntryCountsByLibrary(db, owner_id),
  ]);
  return {
    record_id: row.rid,
    library,
    narrative: row.narrative || null,
    content: blockEntry?.content ?? null,
    top_entities: parseJsonArray<TopEntity>(row.top_entities),
    relation_profile: parseJsonArray<RelationStat>(row.relation_profile),
    bridges: parseJsonArray<Bridge>(row.bridges),
    triplet_count: Number(row.triplet_count ?? 0) || 0,
    entry_count: entryCounts.get(library) ?? 0,
    commit_hash: row.commit_hash || null,
    status: row.status ?? 'active',
    updated_at: row.ts,
  };
}