fix(graph): backfill 讀 entity 不帶 owner 過濾(存量 owner=None,濾了讀0);owner 只套建立的 gloss entry

合併 arcrun-7-gloss-bridge（A1 gloss 橋）與 owner-threading（owner_id 寫入鏈必經）：
- node-persist / triplet-ingest 衝突解為「兩者都要」：persistNodes 既寫 entity
  record（帶真 owner）又 upsert gloss entry（帶真 owner、帶 source）；ingestEnvelope
  既帶 source.uri 又 thread 必填 owner 到底。
- gloss 路徑補 owner 必填（配合 owner-mandatory D28）：
  * upsertGlossEntry(..., owner_id: string) owner 改必填
  * backfillGlossEntries(client, owner_id: string) owner 改必填
  * POST /backfill-gloss-entries 缺 owner_id → 400（存量 record owner=None，
    owner 由 caller 明確指定，不從 record 帶）
- 合併兩支測試：gloss 測試補 owner 參數以配合 base owner-required mock。

tsc：除 index.ts:57 swaggerUI 既存 baseline 外 0 error。
vitest：34 passed（gloss 7 + owner/graph 27）。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ck8bjuBTLFkiFxqLGHMpqG

src/actions/backfill-gloss-entries.ts

@@ -0,0 +1,43 @@
+// 存量回填：對「已存在的 entity records」補上對應的 embeddable base entry。
+// 讀 base 既有 entity records（GET /records/by-template/entity）→ 為每筆有 gloss 的落一筆 embeddable entry
+// （同 persistNodes 前向路徑的格式與冪等）。讓既有知識立刻可被 base embed backfill 嵌到。
+// 鐵律：走 base API（API-as-Wall）、零 SQL、樂高法（<100 行、一檔一事、第一參數收 KbdbClient）。
+
+import type { KbdbClient } from '../lib/kbdb-client';
+import { TPL_ENTITY, ensurePluginTemplates } from '../lib/templates';
+import { upsertGlossEntry, type GlossEntryOutcome } from './gloss-entry';
+
+export type BackfillGlossResult = {
+  scanned: number;    // 掃到的 entity record 數
+  created: number;    // 新落的 embeddable entry 數
+  updated: number;    // gloss 變 → 更新內容的數
+  unchanged: number;  // 已存在且內容相同（冪等 no-op）
+  skipped: number;    // embed=false / 空 gloss / 空 canonical → 不落
+};
+
+/**
+ * 對既有 entity records 補 embeddable entry。冪等：重跑不造重複（同 node → 同 page_name → no-op）。
+ * embed 標為 'false' 的 record 略過（明確不入向量庫）。source 未知（存量）→ 留空。
+ */
+export async function backfillGlossEntries(
+  client: KbdbClient,
+  owner_id: string,  // 必經：存量 entity record 本身 owner=None，owner 由 caller 明確指定（配合 owner-mandatory D28）
+): Promise<BackfillGlossResult> {
+  await ensurePluginTemplates(client);
+  // 讀「全部」存量 entity record（不帶 owner 過濾）——存量 entity 本身 owner=None，拿 owner 去濾來源會讀到 0。
+  // owner 只套在下面建立的 gloss entry（caller 明確指定），不套來源讀取。
+  const records = await client.listRecordsByTemplate(TPL_ENTITY);
+  const res: BackfillGlossResult = { scanned: records.length, created: 0, updated: 0, unchanged: 0, skipped: 0 };
+
+  for (const r of records) {
+    const v = r.values;
+    if (v.embed === 'false') { res.skipped++; continue; } // 明確標不嵌 → 略過
+    const outcome: GlossEntryOutcome = await upsertGlossEntry(
+      client,
+      { canonical: v.canonical ?? '', node_id: v.node_id || '', gloss: v.gloss ?? '', source: '' },
+      owner_id,
+    );
+    res[outcome]++; // 'created' | 'updated' | 'unchanged' | 'skipped' 都是 res 的 number 欄位
+  }
+  return res;
+}

src/actions/entity-crud.ts

@@ -13,12 +13,12 @@ const norm = (s: string): string => s.toLowerCase().trim();
 // ─── Entity ──────────────────────────────────────────────────────────────────
 
 /** 建立 Entity（canonical name）。底層 = 一筆 entity template record。 */
-export async function createEntity(client: KbdbClient, canonical: string, owner?: string): Promise<Entity> {
+export async function createEntity(client: KbdbClient, canonical: string, owner: string): Promise<Entity> {
   await ensurePluginTemplates(client);
   const id = await client.createRecord(
     TPL_ENTITY,
-    { canonical, aliases_json: '[]', entity_type: '', owner: owner ?? '' },
-    owner,
+    { canonical, aliases_json: '[]', entity_type: '', owner },  // 真 owner 落 slot（不再 ?? ''）
+    owner,  // 必經：createRecord 內 requireOwner 守衛
   );
   return { id, canonical, aliases: [] };
 }
@@ -45,21 +45,23 @@ export async function listEntities(client: KbdbClient, limit = 100, owner?: stri
  * 新增 alias。base 無 PUT /records/:id → 改「重建一筆新 entity record」覆寫（含舊 canonical + 既有 aliases + 新 alias）。
  * [→arcrun] base 缺 PUT /records/:id：補上後改為原地 patch aliases_json，省一次重建。
  */
-export async function addAlias(client: KbdbClient, entityId: string, alias: string, owner?: string): Promise<void> {
+export async function addAlias(client: KbdbClient, entityId: string, alias: string, owner: string): Promise<void> {
   const rec = await client.getRecord(entityId);
   if (!rec) throw new Error(`Entity ${entityId} not found`);
   const ent = recordToEntity(rec);
   if (ent.aliases.includes(alias)) return;
   const aliases = [...ent.aliases, alias];
   await ensurePluginTemplates(client);
+  // 重建時沿用原 record 既有 owner；原 record 無主（舊資料 owner=None）才退回 caller 指定的 owner。
+  const effectiveOwner = (rec.values.owner || '').trim() || owner;
   await client.createRecord(
     TPL_ENTITY,
     {
       canonical: ent.canonical,
       aliases_json: JSON.stringify(aliases),
       entity_type: rec.values.entity_type ?? '',
-      owner: rec.values.owner ?? owner ?? '',
+      owner: effectiveOwner,
     },
-    owner,
+    effectiveOwner,  // 必經：createRecord 內 requireOwner 守衛
   );
 }

src/actions/entity-normalize.ts

@@ -18,7 +18,7 @@ import type { KbdbClient } from '../lib/kbdb-client';
 export async function normalizeEntity(
   client: KbdbClient,
   rawName: string,
-  owner?: string,
+  owner: string,  // 必經：未命中會建新 entity，必帶 owner
 ): Promise<string> {
   try {
     const exact = await findEntityByName(client, rawName, owner);

src/actions/entity-pending.ts

@@ -16,7 +16,7 @@ export async function createPendingAlias(
   candidateEntityId: string,
   candidateCanonical: string,
   similarity: number,
-  owner?: string,
+  owner: string,  // 必經：pending record 也不可無主
 ): Promise<PendingAlias> {
   await ensurePluginTemplates(client);
   const id = await client.createRecord(
@@ -27,7 +27,7 @@ export async function createPendingAlias(
       candidate_canonical: candidateCanonical,
       similarity: String(similarity),
     },
-    owner,
+    owner,  // 必經：createRecord 內 requireOwner 守衛
   );
   return {
     id,
@@ -56,14 +56,14 @@ export async function getPendingAliases(client: KbdbClient, limit = 100, owner?:
 }
 
 /** 確認 → addAlias 到候選 entity。pending soft 保留（[→arcrun] base 缺 DELETE record）。 */
-export async function confirmPendingAlias(client: KbdbClient, pendingId: string, owner?: string): Promise<void> {
+export async function confirmPendingAlias(client: KbdbClient, pendingId: string, owner: string): Promise<void> {
   const rec = await client.getRecord(pendingId);
   if (!rec || !rec.values.raw_name) throw new Error(`Pending alias ${pendingId} not found`);
   await addAlias(client, rec.values.candidate_entity_id, rec.values.raw_name, owner);
 }
 
 /** 拒絕 → 以 raw_name 建新 entity。pending soft 保留（[→arcrun] base 缺 DELETE record）。 */
-export async function rejectPendingAlias(client: KbdbClient, pendingId: string, owner?: string): Promise<Entity> {
+export async function rejectPendingAlias(client: KbdbClient, pendingId: string, owner: string): Promise<Entity> {
   const rec = await client.getRecord(pendingId);
   if (!rec || !rec.values.raw_name) throw new Error(`Pending alias ${pendingId} not found`);
   return createEntity(client, rec.values.raw_name, owner);

src/actions/gloss-entry.ts

@@ -0,0 +1,66 @@
+// node gloss → base embeddable entry。把 node 的 canonical+gloss 落成一筆 base entry，
+// metadata.embed=true，供 base optional embed 模組讀標 → 嵌進 Vectorize（見 arcrun/kbdb src/embed.ts）。
+// 鐵律：走 base API（API-as-Wall）、零 SQL、不綁 Vectorize（embedding 是 base 職責，graph 只落標）。
+//
+// 為何要這檔：node 打標存進 entity **record**（node-persist），但 base embed 只掃 **entries**.metadata_json
+// .$.embed===true → 標在 record、讀在 entry 對不上，語意查不到圖內容。這裡補「同一 gloss 也落成 entry」。
+//
+// 冪等（base 無 upsert entry 端點）：以 node 去重鍵派生確定性 page_name（base 文件化的 idempotency key），
+// 先 listEntries({entry_type,page_name}) 查存 → 無則 create、內容變則 patch、同則 no-op。
+// [→arcrun] 若 base 日後補「POST /entries upsert（page_name 為鍵）」，這裡可收斂成單一呼叫、免 list-then-write。
+
+import type { KbdbClient } from '../lib/kbdb-client';
+
+// base embed 對「內容語意」無知，只認通用 embed 旗標；entry_type 供向量 metadata 過濾/辨識這批是圖節點 gloss。
+export const NODE_GLOSS_ENTRY_TYPE = 'graph_node_gloss';
+
+export type GlossEntryInput = {
+  canonical: string;
+  node_id?: string;
+  gloss?: string;
+  source?: string; // 沿用 node 的 ingest 來源（envelope source.uri）；存量回填未知則留空
+};
+
+export type GlossEntryOutcome = 'created' | 'updated' | 'unchanged' | 'skipped';
+
+/** node 去重鍵（同 persistNodes：id 優先、無則 canonical）→ 確定性 idempotency key。 */
+function glossKey(canonical: string, node_id?: string): string {
+  return `gloss:${(node_id || canonical).toLowerCase().trim()}`;
+}
+
+/**
+ * 把一個 node 的 gloss 落成 embeddable base entry（冪等）。
+ * - 空 gloss（或空 canonical）→ 跳過：base 對空 content 本就跳過 embed，且裸名的語意召回價值低、
+ *   keyword 搜尋已覆蓋 → 不造無意義 entry（契約允許「空 gloss 可跳過」）。
+ * - content = `canonical：gloss`（名+描述一起 embed，利於語意召回）。
+ * - metadata_json.embed=true（base 讀此旗標）、source、node_id、canonical（回連原 node）。
+ */
+export async function upsertGlossEntry(
+  client: KbdbClient,
+  node: GlossEntryInput,
+  owner_id: string,  // 必經：owner 從 persistNodes / backfill caller 帶真 owner，不得為 None（配合 owner-mandatory D28）
+): Promise<GlossEntryOutcome> {
+  const canonical = (node.canonical || '').trim();
+  const gloss = (node.gloss || '').trim();
+  if (!canonical || !gloss) return 'skipped';
+
+  const page_name = glossKey(canonical, node.node_id);
+  const content = `${canonical}：${gloss}`;
+  const metadata_json = JSON.stringify({
+    embed: true,
+    source: node.source || '',
+    node_id: node.node_id || '',
+    canonical,
+  });
+
+  // 確定性 key 去重：同一 node 重複 ingest 不造重複 entry。
+  const existing = await client.listEntries({ entry_type: NODE_GLOSS_ENTRY_TYPE, page_name, owner_id });
+  if (existing.length > 0) {
+    const e = existing[0];
+    if (e.content === content) return 'unchanged'; // 同內容 → no-op
+    await client.updateEntry(e.id, { content, metadata_json }); // gloss 變 → 更新（base PATCH 觸發重嵌）
+    return 'updated';
+  }
+  await client.createEntry({ content, entry_type: NODE_GLOSS_ENTRY_TYPE, owner_id, page_name, metadata_json });
+  return 'created';
+}

src/actions/node-persist.ts

@@ -4,6 +4,7 @@
 
 import type { KbdbClient } from '../lib/kbdb-client';
 import { TPL_ENTITY, ensurePluginTemplates } from '../lib/templates';
+import { upsertGlossEntry } from './gloss-entry';
 
 export type IngestNode = {
   name: string;
@@ -22,7 +23,8 @@ export type IngestNode = {
 export async function persistNodes(
   client: KbdbClient,
   nodes: IngestNode[],
-  owner_id?: string,
+  owner_id: string,  // 必經：owner 一路從 ingest envelope / route 帶到底，不得掉成空字串
+  source?: string,  // envelope source.uri，帶進 gloss entry 的 metadata.source（供 base backfill 依 source 過濾）
 ): Promise<void> {
   if (!nodes || nodes.length === 0) return;
   await ensurePluginTemplates(client);
@@ -42,9 +44,16 @@ export async function persistNodes(
         gloss: n.gloss ?? '',
         // contract 預設 true；只在明確 false 時存標（base 看 'false' 跳過 embed）。
         embed: n.embed === false ? 'false' : 'true',
-        owner: owner_id ?? '',
+        owner: owner_id,  // 真 owner 落 slot（不再 ?? ''）
       },
-      owner_id,
+      owner_id,  // createRecord 內 requireOwner 守衛：缺→throw
     );
+
+    // 另落一筆 embeddable base entry（metadata.embed=true）——record 的 gloss 標 base embed 讀不到，
+    // 必須也落成 entry base embed 模組才掃得到（打標≠讀標的修補）。只在要 embed（embed !== false）時落；
+    // 空 gloss 由 upsertGlossEntry 自行跳過。冪等：同 node 重複 ingest 不造重複 entry。
+    if (n.embed !== false) {
+      await upsertGlossEntry(client, { canonical: n.name, node_id: n.id, gloss: n.gloss, source }, owner_id);
+    }
   }
 }

src/actions/triplet-crud.ts

@@ -13,7 +13,7 @@ export type CreateTripletData = {
   object: string;
   source_block_id?: string;
   confidence?: number;
-  owner_id?: string;
+  owner_id: string;  // 必經：三元組寫入必帶 owner（createRecord 內 requireOwner 守衛）
   clusters?: string[];
   bridge_score?: number;
   subject_entity_type?: string;

src/actions/triplet-extract.ts

@@ -55,7 +55,7 @@ export async function extractTripletsViaLLM(ai: Ai, chunks: string[]): Promise<L
 export async function writeTripletToDb(
   client: KbdbClient,
   t: { subject: string; predicate: string; object: string; confidence?: number },
-  owner: string | null,
+  owner: string,  // 必經：萃取寫入必帶 owner（不再收 null → 不會 owner_id: undefined）
 ): Promise<boolean> {
   // 查重：以 S-P-O 三欄精確比對（queryTriplets 取 template record 後在插件層 filter）
   const { count } = await queryTriplets(client, {
@@ -71,7 +71,7 @@ export async function writeTripletToDb(
     predicate: t.predicate,
     object: t.object,
     confidence: t.confidence ?? 0.8,
-    owner_id: owner ?? undefined,
+    owner_id: owner,
   });
   return true;
 }

src/actions/triplet-ingest.ts

@@ -53,7 +53,7 @@ export type IngestResult = { skipped: boolean; ingested: number; deprecated: num
 export async function ingestEnvelope(
   client: KbdbClient,
   env: IngestEnvelope,
-  owner_id?: string,
+  owner_id: string,  // 必經：owner 從 route 帶入，一路 thread 進 triplet + node 寫入，不得掉成空
 ): Promise<IngestResult> {
   await ensurePluginTemplates(client);
 
@@ -84,7 +84,8 @@ export async function ingestEnvelope(
 
   // 1b) 落地 node 層打標（embed / gloss / aliases），供 base embed 模組讀標執行 embedding。
   //     graph 自己不算向量（鐵律一致）。id 作去重鍵：同一卡（同 id/檔名）只存一筆 entity，不以邊數重複。
-  await persistNodes(client, env.nodes ?? [], owner_id);
+  //     並為每個 node 另落一筆 embeddable base entry（source.uri 帶進 metadata.source）。
+  await persistNodes(client, env.nodes ?? [], owner_id, env.source.uri);
 
   // 2) 後翻舊批 status=deprecated（指向本批 source_uri；append 在前 → 無空窗）。
   for (const old of priorActive) {

src/lib/kbdb-client.ts

@@ -13,6 +13,9 @@ export type BaseEntry = {
   owner_id: string | null;
   parent_id?: string | null;
   page_name?: string | null;
+  // base entries 的通用 metadata（TEXT，JSON 字串）。base embed 模組讀 metadata_json.$.embed / $.source
+  // 決定要不要嵌、嵌進哪個 source 分組（見 arcrun/kbdb src/embed.ts）。插件只落標、不算向量。
+  metadata_json?: string | null;
   created_at?: number;
   updated_at?: number;
 };
@@ -26,11 +29,32 @@ export type BaseRecord = {
 export type CreateEntryInput = {
   content: string | null;
   entry_type: string;
-  owner_id?: string;
+  // owner_id 必經（D27/D28）：型別上必填、且執行期缺→throw。不再靜默送空 → 不寫出無主資料。
+  owner_id: string;
   parent_id?: string;
+  // page_name = base 文件化的 idempotency key（entry-crud.ts：exact-match lookup）。
   page_name?: string;
+  // metadata_json = base 既有欄位（JSON 字串）。標 { embed:true, source, ... } 供 base embed 模組讀標執行。
+  metadata_json?: string;
 };
 
+/**
+ * owner_id 必經守衛（D27/D28，2026-07-05）。
+ * 病根：漏 owner → 靜默送 owner:'' → base 寫成 owner=None → mira owner 過濾濾掉 → 使用者查不到
+ * （實測回填 16 筆 gloss entry owner=None）。base 即將把 owner 設必填（缺→400）；插件端先擋，fail loud。
+ * 任何寫入前呼叫此守衛：漏 owner 在插件端就爆、不會送到 base，錯誤訊息指名該從最外層 route/envelope 帶入。
+ */
+export function requireOwner(owner_id: string | null | undefined, op: string): string {
+  const v = (owner_id ?? '').trim();
+  if (!v) {
+    throw new Error(
+      `[kbdb-graph] ${op} 缺 owner_id：owner 為必經欄位，不可寫出無主資料。` +
+        `請從最外層（route 參數 / ingest envelope）把真 owner thread 到底。`,
+    );
+  }
+  return v;
+}
+
 /** 基本盤 API client。所有方法 = 一個 HTTP 呼叫，零 SQL。 */
 export class KbdbClient {
   constructor(
@@ -70,7 +94,8 @@ export class KbdbClient {
   // --- entries ---
 
   async createEntry(input: CreateEntryInput): Promise<BaseEntry> {
-    const { entry } = await this.req<{ entry: BaseEntry }>('POST', '/entries', input);
+    const owner_id = requireOwner(input.owner_id, 'createEntry');
+    const { entry } = await this.req<{ entry: BaseEntry }>('POST', '/entries', { ...input, owner_id });
     return entry;
   }
 
@@ -154,11 +179,12 @@ export class KbdbClient {
 
   // --- records（= template 實例，填 slot） ---
 
-  async createRecord(template: string, values: Record<string, string>, owner_id?: string): Promise<string> {
+  async createRecord(template: string, values: Record<string, string>, owner_id: string): Promise<string> {
+    const owner = requireOwner(owner_id, `createRecord(template=${template})`);
     const { record } = await this.req<{ record: { record_id: string } }>('POST', '/records', {
       template,
       values,
-      owner_id,
+      owner_id: owner,
     });
     return record.record_id;
   }

src/routes/entities.ts

@@ -6,6 +6,7 @@ import {
   rejectPendingAlias,
 } from '../actions/entity-pending';
 import { listTripletEntities } from '../actions/triplet-entities';
+import { backfillGlossEntries } from '../actions/backfill-gloss-entries';
 import { makeKbdbClient } from '../lib/kbdb-client';
 
 const entityRoutes = new OpenAPIHono<{ Bindings: Bindings }>();
@@ -54,14 +55,31 @@ entityRoutes.openapi(listPendingRoute, async (c) => {
 
 entityRoutes.post('/pending/:id/confirm', async (c) => {
   const id = c.req.param('id');
-  await confirmPendingAlias(makeKbdbClient(c.env), id);
+  // owner 必經：confirm 會 addAlias（重建 entity record），缺 owner→400 不寫無主資料。
+  const owner = c.req.query('owner_id')?.trim();
+  if (!owner) return c.json({ error: 'owner_id query parameter required（資料不可無主）' }, 400);
+  await confirmPendingAlias(makeKbdbClient(c.env), id, owner);
   return c.json({ success: true, action: 'confirmed', id });
 });
 
 entityRoutes.post('/pending/:id/reject', async (c) => {
   const id = c.req.param('id');
-  const newEntity = await rejectPendingAlias(makeKbdbClient(c.env), id);
+  // owner 必經：reject 會 createEntity，缺 owner→400 不寫無主資料。
+  const owner = c.req.query('owner_id')?.trim();
+  if (!owner) return c.json({ error: 'owner_id query parameter required（資料不可無主）' }, 400);
+  const newEntity = await rejectPendingAlias(makeKbdbClient(c.env), id, owner);
   return c.json({ success: true, action: 'rejected', newEntity });
 });
 
+// POST /backfill-gloss-entries — 存量回填：對既有 entity records 補 embeddable base entry（metadata.embed=true）。
+// route 只驗參數 + 呼叫 action（樂高法：無業務邏輯）。冪等，可重複呼叫。
+entityRoutes.post('/backfill-gloss-entries', async (c) => {
+  const body = (await c.req.json().catch(() => ({}))) as { owner_id?: string };
+  // owner 必經：存量 entity record 本身 owner=None，owner 由 caller 明確指定（不從 record 帶）。缺→400 不寫無主資料。
+  const owner_id = c.req.query('owner_id') || body?.owner_id;
+  if (!owner_id) return c.json({ success: false, error: 'owner_id required' }, 400);
+  const result = await backfillGlossEntries(makeKbdbClient(c.env), owner_id);
+  return c.json({ success: true, ...result });
+});
+
 export { entityRoutes };

src/routes/triplets.ts

@@ -77,7 +77,7 @@ const createRouteDefinition = createRoute({
             subject: z.string().min(1),
             predicate: z.string().min(1),
             object: z.string().min(1),
-            owner_id: z.string().optional(),
+            owner_id: z.string().min(1),  // 必填：缺→400（資料不可無主）
             source_block_id: z.string().optional(),
             confidence: z.number().optional(),
             clusters: z.array(z.string()).optional(),
@@ -103,10 +103,13 @@ const ingestRoute = createRoute({
   method: 'post',
   path: '/ingest',
   request: {
+    // owner_id 走 route 參數（envelope 是 .strict() 凍結契約，不塞 owner 進去）。缺→400。
+    query: z.object({ owner_id: z.string().optional().describe('資料所有者（必填，缺→400）') }),
     body: { content: { 'application/json': { schema: IngestEnvelopeSchema } } },
   },
   responses: {
     200: { description: 'Envelope ingested (or skipped if same content_hash)' },
+    400: { description: 'Missing owner_id (資料不可無主)' },
     422: { description: 'Invalid envelope (forbidden field or shape mismatch)' },
   },
   tags: ['Triplets'],
@@ -115,8 +118,11 @@ const ingestRoute = createRoute({
 tripletRoutes.openapi(
   ingestRoute,
   async (c) => {
+    // owner 必經：缺→400（不寫出無主 triplet/node；避免再現 owner=None 被 mira 過濾）。
+    const owner_id = c.req.query('owner_id')?.trim();
+    if (!owner_id) return c.json({ error: 'owner_id query parameter required（資料不可無主）' }, 400);
     const env = c.req.valid('json');
-    const result = await ingestEnvelope(makeKbdbClient(c.env), env);
+    const result = await ingestEnvelope(makeKbdbClient(c.env), env, owner_id);
     return c.json(result, 200);
   },
   // strict() 驗證失敗（如送禁止欄位 bridge_score）→ 422，不是預設 400。

tests/entity.test.ts

@@ -5,17 +5,29 @@ import { normalizeEntity } from '../src/actions/entity-normalize';
 import { mockClient } from './mock-client';
 
 describe('entity-crud', () => {
-  it('建立後可 exact 查回（大小寫不敏感）', async () => {
+  it('建立後可 exact 查回（大小寫不敏感），owner slot 帶真 owner', async () => {
     const c = mockClient();
-    await createEntity(c, 'InkStone');
-    const found = await findEntityByName(c, 'inkstone');
+    const ent = await createEntity(c, 'InkStone', 'leo');
+    const found = await findEntityByName(c, 'inkstone', 'leo');
     expect(found?.canonical).toBe('InkStone');
+    // owner 落底：record 掛在 leo 名下（非無主），用錯 owner 查不到。
+    const rec = await c.getRecord(ent.id);
+    expect(rec?.values.owner).toBe('leo');
+    expect(await findEntityByName(c, 'inkstone', 'someone-else')).toBeNull();
+  });
+
+  it('漏 owner → 插件端 fail（不寫出無主 entity）', async () => {
+    const c = mockClient();
+    await expect(
+      // @ts-expect-error 蓄意漏 owner：型別上 owner 必填，執行期也應 throw
+      createEntity(c, 'NoOwner'),
+    ).rejects.toThrow(/owner/i);
   });
 
   it('listEntities 列出', async () => {
     const c = mockClient();
-    await createEntity(c, 'A');
-    await createEntity(c, 'B');
+    await createEntity(c, 'A', 'leo');
+    await createEntity(c, 'B', 'leo');
     const all = await listEntities(c);
     expect(all.map((e) => e.canonical).sort()).toEqual(['A', 'B']);
   });
@@ -24,8 +36,8 @@ describe('entity-crud', () => {
 describe('normalizeEntity', () => {
   it('已存在回 canonical，不存在建新回原值', async () => {
     const c = mockClient();
-    await createEntity(c, 'InkStone');
-    expect(await normalizeEntity(c, 'INKSTONE')).toBe('InkStone');
-    expect(await normalizeEntity(c, '新公司')).toBe('新公司');
+    await createEntity(c, 'InkStone', 'leo');
+    expect(await normalizeEntity(c, 'INKSTONE', 'leo')).toBe('InkStone');
+    expect(await normalizeEntity(c, '新公司', 'leo')).toBe('新公司');
   });
 });

tests/gloss-entry.test.ts

@@ -0,0 +1,120 @@
+// node gloss → embeddable base entry：走 mock KbdbClient（API-as-Wall），零 SQL、不打網路。
+// 覆蓋：前向 persistNodes 多落 embeddable entry / embed=false 不落 / 空 gloss 不落 / 冪等不重複 /
+//       gloss 變則更新 / backfill 對既有 entity records 補 entry（含冪等、embed=false 略過）。
+import { describe, it, expect } from 'vitest';
+import { persistNodes } from '../src/actions/node-persist';
+import { backfillGlossEntries } from '../src/actions/backfill-gloss-entries';
+import { NODE_GLOSS_ENTRY_TYPE } from '../src/actions/gloss-entry';
+import { TPL_ENTITY } from '../src/lib/templates';
+import { mockClient } from './mock-client';
+
+const glossEntries = (c: ReturnType<typeof mockClient>) =>
+  c.listEntries({ entry_type: NODE_GLOSS_ENTRY_TYPE });
+
+describe('persistNodes — 前向：每個 node 另落一筆 embeddable base entry', () => {
+  it('有 gloss 的 node → 落 entry：content=名+gloss、metadata.embed=true、帶 source/node_id', async () => {
+    const c = mockClient();
+    await persistNodes(
+      c,
+      [{ name: '系統動力學', id: 'sd.md', gloss: '用因果圖表解複雜系統的方法論' }],
+      'leo21c',
+      'github:uncle6me-web/wiki@sd.md',
+    );
+
+    const entries = await glossEntries(c);
+    expect(entries.length).toBe(1);
+    const e = entries[0];
+    expect(e.content).toBe('系統動力學：用因果圖表解複雜系統的方法論');
+    expect(e.page_name).toBe('gloss:sd.md');
+    expect(e.owner_id).toBe('leo21c');
+    const meta = JSON.parse(e.metadata_json!);
+    expect(meta.embed).toBe(true);              // 關鍵：base embed 模組讀這個
+    expect(meta.source).toBe('github:uncle6me-web/wiki@sd.md');
+    expect(meta.node_id).toBe('sd.md');
+    expect(meta.canonical).toBe('系統動力學');
+
+    // entity record 仍照舊存在（兩者並存：record 給圖、entry 給 embed）。
+    const recs = await c.listRecordsByTemplate(TPL_ENTITY);
+    expect(recs.find((r) => r.values.canonical === '系統動力學')).toBeTruthy();
+  });
+
+  it('embed=false 的 node → 不落 embeddable entry', async () => {
+    const c = mockClient();
+    await persistNodes(c, [{ name: '黃仁勳', id: '黃仁勳', gloss: 'NVIDIA 創辦人', embed: false }], 'leo21c');
+    expect((await glossEntries(c)).length).toBe(0);
+  });
+
+  it('空 gloss 的 node → 不落 embeddable entry（不造無意義空殼）', async () => {
+    const c = mockClient();
+    await persistNodes(c, [{ name: '某卡', id: 'card.md' }], 'leo21c');
+    expect((await glossEntries(c)).length).toBe(0);
+  });
+
+  it('冪等：同一 node 重複 ingest → 只一筆 embeddable entry', async () => {
+    const c = mockClient();
+    const nodes = [{ name: '長壽', id: 'longevity', gloss: '活得更久本身具有價值' }];
+    await persistNodes(c, nodes, 'leo21c', 'u1');
+    await persistNodes(c, nodes, 'leo21c', 'u1'); // 再送一次
+    expect((await glossEntries(c)).length).toBe(1);
+  });
+
+  it('gloss 變更 → 更新既有 entry 內容（仍只一筆）', async () => {
+    const c = mockClient();
+    await persistNodes(c, [{ name: '長壽', id: 'longevity', gloss: '舊描述' }], 'leo21c');
+    await persistNodes(c, [{ name: '長壽', id: 'longevity', gloss: '活得更久本身具有價值' }], 'leo21c');
+    const entries = await glossEntries(c);
+    expect(entries.length).toBe(1);
+    expect(entries[0].content).toBe('長壽：活得更久本身具有價值');
+  });
+});
+
+describe('backfillGlossEntries — 存量：對既有 entity records 補 embeddable entry', () => {
+  // 直接以 entity record 造存量（模擬既有 16 筆），不經前向路徑。
+  async function seedEntity(
+    c: ReturnType<typeof mockClient>,
+    v: { canonical: string; node_id?: string; gloss?: string; embed?: string },
+  ) {
+    await c.createRecord(TPL_ENTITY, {
+      canonical: v.canonical,
+      node_id: v.node_id ?? '',
+      aliases_json: '[]',
+      entity_type: '',
+      gloss: v.gloss ?? '',
+      embed: v.embed ?? 'true',
+      owner: '',  // slot 存量 owner=None（模擬 D28 前的無主 record）；backfill 的 owner 由 caller 明確指定
+    }, 'leo21c');  // 記錄層 owner_id：base D28 後 createRecord 一律要 owner；caller 明指
+  }
+
+  it('有 gloss 的既有 record → 落 entry；embed=false / 空 gloss → 略過', async () => {
+    const c = mockClient();
+    await seedEntity(c, { canonical: '長壽', node_id: 'longevity', gloss: '活得更久本身具有價值' });
+    await seedEntity(c, { canonical: '系統動力學', node_id: 'sd', gloss: '用因果圖表解複雜系統的方法論' });
+    await seedEntity(c, { canonical: '無標', node_id: 'x', gloss: '不該嵌', embed: 'false' });
+    await seedEntity(c, { canonical: '空描述', node_id: 'y' }); // 空 gloss
+
+    const res = await backfillGlossEntries(c, 'leo21c');
+    expect(res.scanned).toBe(4);
+    expect(res.created).toBe(2);
+    expect(res.skipped).toBe(2); // embed=false + 空 gloss
+
+    const entries = await glossEntries(c);
+    expect(entries.length).toBe(2);
+    expect(entries.every((e) => JSON.parse(e.metadata_json!).embed === true)).toBe(true);
+    expect(entries.map((e) => e.content).sort()).toEqual(
+      ['系統動力學：用因果圖表解複雜系統的方法論', '長壽：活得更久本身具有價值'].sort(),
+    );
+  });
+
+  it('冪等：連跑兩次 backfill → 不造重複（第二次全 unchanged）', async () => {
+    const c = mockClient();
+    await seedEntity(c, { canonical: '長壽', node_id: 'longevity', gloss: '活得更久本身具有價值' });
+
+    const first = await backfillGlossEntries(c, 'leo21c');
+    expect(first.created).toBe(1);
+
+    const second = await backfillGlossEntries(c, 'leo21c');
+    expect(second.created).toBe(0);
+    expect(second.unchanged).toBe(1);
+    expect((await glossEntries(c)).length).toBe(1);
+  });
+});

tests/graph-source.test.ts

@@ -12,7 +12,7 @@ describe('getSource — 回節點的原文來源指標', () => {
       source: { uri: 'github:u/w@a.md', content_hash: 'h1', anchor: '#graph-rag' },
       extractor: { model: 'm', tier: 'deep' },
       triplets: [{ subject: 'GraphRAG', predicate: '是', object: 'RAG 變體' }],
-    });
+    }, 'leo');
 
     const refs = await getSource(c, 'GraphRAG');
     expect(refs.length).toBe(1);
@@ -27,12 +27,12 @@ describe('getSource — 回節點的原文來源指標', () => {
       source: { uri: 'github:u/w@a.md', content_hash: 'h1', anchor: '#old' },
       extractor: { model: 'm', tier: 'deep' },
       triplets: [{ subject: 'X', predicate: 'r', object: 'old' }],
-    });
+    }, 'leo');
     await ingestEnvelope(c, {
       source: { uri: 'github:u/w@a.md', content_hash: 'h2', anchor: '#new' },
       extractor: { model: 'm', tier: 'deep' },
       triplets: [{ subject: 'X', predicate: 'r', object: 'new' }],
-    });
+    }, 'leo');
 
     const refs = await getSource(c, 'X');
     expect(refs.length).toBe(1);

tests/graph.test.ts

@@ -7,10 +7,10 @@ import { mockClient } from './mock-client';
 import type { KbdbClient } from '../src/lib/kbdb-client';
 
 async function seed(c: KbdbClient) {
-  // A — B — C，D 孤立連 A
-  await createTriplet(c, { subject: 'A', predicate: 'r', object: 'B' });
-  await createTriplet(c, { subject: 'B', predicate: 'r', object: 'C' });
-  await createTriplet(c, { subject: 'A', predicate: 'r', object: 'D' });
+  // A — B — C，D 孤立連 A（owner 必經：所有寫入帶真 owner）
+  await createTriplet(c, { subject: 'A', predicate: 'r', object: 'B', owner_id: 'leo' });
+  await createTriplet(c, { subject: 'B', predicate: 'r', object: 'C', owner_id: 'leo' });
+  await createTriplet(c, { subject: 'A', predicate: 'r', object: 'D', owner_id: 'leo' });
 }
 
 describe('graph-nodes', () => {

tests/mock-client.ts

@@ -15,8 +15,19 @@ export class MockKbdbClient {
   }
 
   async createEntry(input: any): Promise<BaseEntry> {
+    // 對齊基本盤 D27/D28 即將上線的 owner 必填：缺 owner → 400（模擬 base 擋死無主寫入）。
+    if (!(input?.owner_id ?? '').trim()) throw new Error('[kbdb-base] POST /entries: owner_id required (400)');
     const id = this.id('entry');
-    const entry: BaseEntry = { id, content: input.content ?? null, entry_type: input.entry_type, owner_id: input.owner_id ?? null };
+    // 對齊 base entry-crud：保留 page_name（idempotency key）、metadata_json（embed 打標）、parent_id。
+    const entry: BaseEntry = {
+      id,
+      content: input.content ?? null,
+      entry_type: input.entry_type,
+      owner_id: input.owner_id ?? null,
+      parent_id: input.parent_id ?? null,
+      page_name: input.page_name ?? null,
+      metadata_json: input.metadata_json ?? null,
+    };
     this.entries.set(id, entry);
     return entry;
   }
@@ -26,8 +37,13 @@ export class MockKbdbClient {
   }
 
   async listEntries(filters: any = {}): Promise<BaseEntry[]> {
+    // 對齊 base entry-crud listEntries 的 exact-match filters（含 page_name idempotency key、parent_id）。
     return [...this.entries.values()].filter(
-      (e) => (!filters.entry_type || e.entry_type === filters.entry_type) && (!filters.owner_id || e.owner_id === filters.owner_id),
+      (e) =>
+        (!filters.entry_type || e.entry_type === filters.entry_type) &&
+        (!filters.owner_id || e.owner_id === filters.owner_id) &&
+        (!filters.parent_id || e.parent_id === filters.parent_id) &&
+        (!filters.page_name || e.page_name === filters.page_name),
     );
   }
 
@@ -61,6 +77,8 @@ export class MockKbdbClient {
   }
 
   async createRecord(template: string, values: Record<string, string>, owner_id?: string): Promise<string> {
+    // 對齊基本盤 D27/D28 即將上線的 owner 必填：缺 owner → 400（模擬 base 擋死無主寫入）。
+    if (!(owner_id ?? '').trim()) throw new Error('[kbdb-base] POST /records: owner_id required (400)');
     const id = this.id('rec');
     this.records.set(id, { template, values: { ...values }, owner_id });
     return id;

tests/triplet-crud.test.ts

@@ -6,7 +6,7 @@ import { mockClient } from './mock-client';
 describe('createTriplet → records API', () => {
   it('建立後可由 id 取回', async () => {
     const c = mockClient();
-    const r = await createTriplet(c, { subject: 'InkStone', predicate: '是', object: '創業 OS' });
+    const r = await createTriplet(c, { subject: 'InkStone', predicate: '是', object: '創業 OS', owner_id: 'leo' });
     expect(r.id).toBeDefined();
     expect(r.subject).toBe('InkStone');
 
@@ -14,13 +14,23 @@ describe('createTriplet → records API', () => {
     expect(got?.predicate).toBe('是');
     expect(got?.object).toBe('創業 OS');
   });
+
+  it('漏 owner → 插件端 fail（不靜默送空，不寫出無主 triplet）', async () => {
+    const c = mockClient();
+    await expect(
+      // @ts-expect-error 蓄意漏 owner：型別上 owner 必填，執行期也應 throw
+      createTriplet(c, { subject: 'X', predicate: 'p', object: 'Y' }),
+    ).rejects.toThrow(/owner/i);
+    const { count } = await queryTriplets(c, { includeDeprecated: true });
+    expect(count).toBe(0);
+  });
 });
 
 describe('queryTriplets → 插件層 filter', () => {
   it('by subject 過濾', async () => {
     const c = mockClient();
-    await createTriplet(c, { subject: 'KBDB', predicate: '使用', object: 'D1' });
-    await createTriplet(c, { subject: 'Other', predicate: '使用', object: 'X' });
+    await createTriplet(c, { subject: 'KBDB', predicate: '使用', object: 'D1', owner_id: 'leo' });
+    await createTriplet(c, { subject: 'Other', predicate: '使用', object: 'X', owner_id: 'leo' });
 
     const { triplets, count } = await queryTriplets(c, { subject: 'KBDB' });
     expect(count).toBe(1);
@@ -29,7 +39,7 @@ describe('queryTriplets → 插件層 filter', () => {
 
   it('limit/offset 分頁', async () => {
     const c = mockClient();
-    for (let i = 0; i < 5; i++) await createTriplet(c, { subject: `s${i}`, predicate: 'p', object: 'o' });
+    for (let i = 0; i < 5; i++) await createTriplet(c, { subject: `s${i}`, predicate: 'p', object: 'o', owner_id: 'leo' });
     const { triplets } = await queryTriplets(c, { limit: 2, offset: 1 });
     expect(triplets.length).toBe(2);
   });

tests/triplet-ingest.test.ts

@@ -1,10 +1,13 @@
 // ingest 寫入端 — 走 mock KbdbClient（API-as-Wall），零 SQL、不打網路。
 // 覆蓋 T3.4 五案：正常 envelope / 同 hash no-op / 新 hash deprecate / 污染 envelope 422 / rollback。
+// + owner 必經（D27/D28）：漏 owner→插件端 fail；真 owner 一路 thread 進 triplet + node 寫入。
 import { describe, it, expect } from 'vitest';
 import { ingestEnvelope, IngestEnvelopeSchema, type IngestEnvelope } from '../src/actions/triplet-ingest';
 import { queryTriplets } from '../src/actions/triplet-crud';
 import { mockClient } from './mock-client';
 
+const OWNER = 'leo';
+
 function envelope(hash: string, triplets: IngestEnvelope['triplets']): IngestEnvelope {
   return {
     source: { uri: 'github:uncle6me-web/wiki@a.md', content_hash: hash },
@@ -19,7 +22,7 @@ describe('ingestEnvelope — 正常 envelope', () => {
     const res = await ingestEnvelope(c, envelope('h1', [
       { subject: 'A', predicate: 'rel', object: 'B' },
       { subject: 'B', predicate: 'rel', object: 'C' },
-    ]));
+    ]), OWNER);
     expect(res).toEqual({ skipped: false, ingested: 2, deprecated: 0 });
 
     const { triplets } = await queryTriplets(c, {});
@@ -30,11 +33,46 @@ describe('ingestEnvelope — 正常 envelope', () => {
   });
 });
 
+describe('ingestEnvelope — owner 必經（D27/D28）', () => {
+  it('漏 owner → 插件端 fail（不靜默送空，不寫出無主 triplet）', async () => {
+    const c = mockClient();
+    await expect(
+      // @ts-expect-error 蓄意漏 owner：型別上 owner 必填，執行期也應 throw
+      ingestEnvelope(c, envelope('h1', [{ subject: 'A', predicate: 'r', object: 'B' }])),
+    ).rejects.toThrow(/owner/i);
+    // fail loud：一筆都不該寫進去（第一筆寫入即擋）。
+    const { triplets } = await queryTriplets(c, {});
+    expect(triplets.length).toBe(0);
+  });
+
+  it('真 owner 一路 thread 到 triplet + node 寫入（owner slot 非空、record owner_id=真 owner）', async () => {
+    const c = mockClient();
+    const env: IngestEnvelope = {
+      source: { uri: 'github:uncle6me-web/wiki@own.md', content_hash: 'ho' },
+      extractor: { model: 'm', tier: 'deep' },
+      nodes: [{ name: 'Graph RAG', id: 'graph-rag.md', gloss: '關係遍歷檢索' }],
+      triplets: [{ subject: 'Graph RAG', predicate: 'r', object: 'X' }],
+    };
+    await ingestEnvelope(c, env, OWNER);
+
+    // triplet record 帶真 owner。
+    const triplets = await c.listRecordsByTemplate('triplet', OWNER);
+    expect(triplets.length).toBe(1);
+    // node → entity record 帶真 owner（owner slot + record owner_id 皆為 leo，非 None/空）。
+    const entities = await c.listRecordsByTemplate('entity', OWNER);
+    const gr = entities.find((e) => e.values.canonical === 'Graph RAG');
+    expect(gr).toBeDefined();
+    expect(gr!.values.owner).toBe(OWNER);
+    // 用錯 owner 查 → 濾掉（證明 record 確實掛在 leo 名下，非無主）。
+    expect((await c.listRecordsByTemplate('entity', 'someone-else')).length).toBe(0);
+  });
+});
+
 describe('ingestEnvelope — 同 hash no-op', () => {
   it('同 uri+hash 再送 → skipped，不新增', async () => {
     const c = mockClient();
-    await ingestEnvelope(c, envelope('h1', [{ subject: 'A', predicate: 'r', object: 'B' }]));
-    const res = await ingestEnvelope(c, envelope('h1', [{ subject: 'A', predicate: 'r', object: 'B' }]));
+    await ingestEnvelope(c, envelope('h1', [{ subject: 'A', predicate: 'r', object: 'B' }]), OWNER);
+    const res = await ingestEnvelope(c, envelope('h1', [{ subject: 'A', predicate: 'r', object: 'B' }]), OWNER);
     expect(res.skipped).toBe(true);
 
     const { triplets } = await queryTriplets(c, {});
@@ -45,8 +83,8 @@ describe('ingestEnvelope — 同 hash no-op', () => {
 describe('ingestEnvelope — 新 hash deprecate-then-append', () => {
   it('同 uri 新 hash → 舊批轉 deprecated、新批 active；查詢 active-only', async () => {
     const c = mockClient();
-    await ingestEnvelope(c, envelope('h1', [{ subject: 'A', predicate: 'r', object: 'old' }]));
-    const res = await ingestEnvelope(c, envelope('h2', [{ subject: 'A', predicate: 'r', object: 'new' }]));
+    await ingestEnvelope(c, envelope('h1', [{ subject: 'A', predicate: 'r', object: 'old' }]), OWNER);
+    const res = await ingestEnvelope(c, envelope('h2', [{ subject: 'A', predicate: 'r', object: 'new' }]), OWNER);
     expect(res).toEqual({ skipped: false, ingested: 1, deprecated: 1 });
 
     // active-only 查詢只見新批。
@@ -103,7 +141,7 @@ describe('ingestEnvelope — 向量化打標欄位（contract 升格，ingest#1
     expect(IngestEnvelopeSchema.safeParse(env).success).toBe(true);
 
     // 落地：triplet 寫入、node 打標存進 entity slot。
-    const res = await ingestEnvelope(c, env);
+    const res = await ingestEnvelope(c, env, OWNER);
     expect(res).toEqual({ skipped: false, ingested: 1, deprecated: 0 });
 
     const { triplets } = await queryTriplets(c, {});
@@ -131,7 +169,7 @@ describe('ingestEnvelope — 向量化打標欄位（contract 升格，ingest#1
       ],
       triplets: [{ subject: 'Graph RAG', predicate: 'r', object: 'X' }],
     };
-    await ingestEnvelope(c, env);
+    await ingestEnvelope(c, env, OWNER);
     const entities = await c.listRecordsByTemplate('entity');
     expect(entities.filter((e) => e.values.node_id === 'graph-rag.md').length).toBe(1);
   });
@@ -160,8 +198,8 @@ describe('ingestEnvelope — 向量化打標欄位（contract 升格，ingest#1
 describe('ingestEnvelope — rollback（翻回 status）', () => {
   it('把 deprecated 翻回 active 後，active 查詢重新見到它', async () => {
     const c = mockClient();
-    await ingestEnvelope(c, envelope('h1', [{ subject: 'A', predicate: 'r', object: 'old' }]));
-    await ingestEnvelope(c, envelope('h2', [{ subject: 'A', predicate: 'r', object: 'new' }]));
+    await ingestEnvelope(c, envelope('h1', [{ subject: 'A', predicate: 'r', object: 'old' }]), OWNER);
+    await ingestEnvelope(c, envelope('h2', [{ subject: 'A', predicate: 'r', object: 'new' }]), OWNER);
 
     // 取出被 deprecate 的舊批 id，手動 rollback（翻回 active、清 superseded_by）。
     const all = await queryTriplets(c, { includeDeprecated: true });