---
tags: [契約邊界, 契約規格, 架構設計]
gloss: ingest→graph 的唯一耦合面——一個來源檔一次萃取產出的候選 envelope，規定 ingest 能送什麼、禁送什麼。
---
# envelope 契約

← [[ingest/00-INDEX]]

**來源**：`contracts/ingest-candidate.json`（凍結形式契約，逐字依原文）、`docs/3-specs/ingest-pipeline/design.md`
**最後更新**：2026-06-26

> 這是**凍結的形式契約**。欄位的精確 schema 以 `contracts/ingest-candidate.json` 為唯一真相，**逐字依原文**；本卡只距離化「設計意圖與職責切割」，不取代 schema。

## 摘要

`IngestCandidateEnvelope` 是 ingest 與 graph 之間唯一的耦合面：一個 envelope ＝一個 canonical MD 一次萃取的候選產物。

## 重點

- **頂層三必填**：`source`（來自哪個檔 + 快照鍵）、`extractor`（哪個模型/tier 萃的）、`triplets`（邊，至少一條）。另有選填 `nodes[]`（節點層附帶資訊）。`additionalProperties: false` 全程鎖死。
- **source = 指回原文的指標 + append-only 快照鍵**：`uri`（`github:<owner>/<repo>@<path>`）+ `content_hash`。同一 uri 後續 envelope **取代**前一批（latest-wins），不疊加；同 hash → graph no-op 跳過。
- **取代語意歸 graph，ingest 一無所知**：同 uri 出新 hash 時，graph 把舊 active 實例 PATCH 成 deprecated、append 新批 active（可查/rollback/清）。ingest 只管送新批。
- **向量化分工（leo 2026-06-26 升格成契約）**：ingest 在 `nodes[].embed` / `triplets[].predicate_embed` **打標**「要不要向量化、embed 什麼（名+gloss / 謂詞裸詞）」；base/KBDB embed 模組**讀標執行**實際 embedding。**ingest 自己不算向量**（呼應 [[掛載架構]]「准運算不准碰儲存」、principles「不算向量 normalize」）。
- **ingest 能送**：原始 s/p/o + `source.*` + `extractor.*` + `nodes[].gloss/aliases/entity_type/embed` + `confidence` + 謂詞向量打標。
- **ingest 禁送（graph 領域，絕不可送）**：`id`（record id）/ `clusters` / `bridge_score` / `created_at` / `updated_at` / triplet 上的 `subject_entity_type|object_entity_type`（類型只走 `nodes[]`）。結構符號（`>>`/`←`）與給人讀的散文（`## 摘要`）也不進 envelope。
- 這是**【輸入候選】不是【已存三元組】**（後者見 graph 的 triplet.json）。

## 實體

- **IngestCandidateEnvelope**（envelope／凍結契約）— ingest→graph 唯一耦合面，一個來源檔一次萃取的候選產物。
- **向量化打標**（embed/predicate_embed 標記）— ingest 標哪些 node/謂詞要 embed、embed 什麼，自己不執行 embedding。
- **讀標執行**（base embed 模組）— base/KBDB 讀 ingest 的標去做實際 embedding 的分工角色。
- **content_hash**（快照鍵）— 來源檔內容 hash，graph 據此判 no-op 或寫新快照。
- **禁送欄位**（graph 領域）— id/clusters/bridge_score/時間戳/邊上 type，由 graph 算、ingest 絕不送。

## 關聯
### 內文知識關係（端點＝上方 `## 實體` 正規名）
- 向量化打標 >> 配對分工 >> 讀標執行
- IngestCandidateEnvelope >> 禁止攜帶 >> 禁送欄位
- content_hash >> 充當 >> IngestCandidateEnvelope
### 卡片關係（卡對卡）
- [[envelope-契約]] >> 約束 >> [[掛載架構]]
- [[envelope-契約]] >> 承載產出於 >> [[extract-模型策略]]