Skip to content

World's first open-source enterprise world model.

Fifty-three migrations become nineteen (#130)

WaylandYangac5b9ee71b97
diff --git a/Cargo.lock b/Cargo.lock
index 3d60d7d1..927b8640 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -4813,6 +4813,9 @@ version = "0.1.0"
[[package]]
name = "utopia-reason"
version = "0.1.0"
+dependencies = [
+ "uuid",
+]
[[package]]
name = "utopia-search"
diff --git a/crates/utopia-core/src/models.rs b/crates/utopia-core/src/models.rs
index 8702aa07..f7cab99e 100644
--- a/crates/utopia-core/src/models.rs
+++ b/crates/utopia-core/src/models.rs
@@ -157,7 +157,7 @@ pub struct ChunkFactView {
pub fact_id: Uuid,
pub subject_id: Uuid,
pub subject: String,
- /// 本体没认下这条关系时回落到原文说法;两者都拿不出时为 None(0052 之前的老数据)
+ /// 本体没认下这条关系时回落到原文说法;两者都拿不出时为 None(更早的历史数据长这样)
pub predicate: Option<String>,
pub inferred: bool,
pub object_id: Option<Uuid>,
@@ -470,7 +470,7 @@ pub struct GraphEdge {
pub id: Uuid,
pub source: Uuid,
pub target: Uuid,
- /// 本体里没有对应关系时回落到原文说法(迁移 0052)。
+ /// 本体里没有对应关系时回落到原文说法(见 `facts.predicate_id`)。
/// 两个来源都拿不出时为 None——那是 add_evidence 记录原文说法之前的老数据
pub predicate: Option<String>,
pub label: Option<String>,
@@ -487,7 +487,7 @@ pub struct EntityFact {
pub id: Uuid,
/// out = 该实体为主语;in = 为宾语
pub direction: String,
- /// 本体没认下这条关系时回落到原文说法;两者都拿不出时为 None(0052 之前的老数据)
+ /// 本体没认下这条关系时回落到原文说法;两者都拿不出时为 None(更早的历史数据长这样)
pub predicate_key: Option<String>,
pub predicate_label: Option<String>,
/// true = 这条事实的名字来自原文,不是本体认下的关系。界面要显示得看得出区别
@@ -501,11 +501,11 @@ pub struct EntityFact {
pub valid_from: Option<DateTime<Utc>>,
pub valid_to: Option<DateTime<Utc>>,
/// 精度描述的是这条事实**有的那些日期**的粒度。两端都没有日期时为 None——
- /// 从前这里是 NOT NULL DEFAULT day,于是没日期的事实也自称精确到日(迁移 0045)
+ /// 从前这里是 NOT NULL DEFAULT day,于是没日期的事实也自称精确到日(见 `facts.valid_from_precision`)
/// 起始端的粒度:year | month | day。没有 valid_from 时为 None
pub valid_from_precision: Option<String>,
/// 结束端的粒度,外加一个 `unknown`——**原文说它结束了,但没说哪天**。
- /// `valid_to` 与它都为 None 才是「仍在持续」(迁移 0046)
+ /// `valid_to` 与它都为 None 才是「仍在持续」(见 `facts.valid_to_precision`)
pub valid_to_precision: Option<String>,
pub confidence: f32,
pub evidence_count: i64,
@@ -544,11 +544,11 @@ pub struct EntityHistoryEvent {
pub valid_from: Option<DateTime<Utc>>,
pub valid_to: Option<DateTime<Utc>>,
/// 精度描述的是这条事实**有的那些日期**的粒度。两端都没有日期时为 None——
- /// 从前这里是 NOT NULL DEFAULT day,于是没日期的事实也自称精确到日(迁移 0045)
+ /// 从前这里是 NOT NULL DEFAULT day,于是没日期的事实也自称精确到日(见 `facts.valid_from_precision`)
/// 起始端的粒度:year | month | day。没有 valid_from 时为 None
pub valid_from_precision: Option<String>,
/// 结束端的粒度,外加一个 `unknown`——**原文说它结束了,但没说哪天**。
- /// `valid_to` 与它都为 None 才是「仍在持续」(迁移 0046)
+ /// `valid_to` 与它都为 None 才是「仍在持续」(见 `facts.valid_to_precision`)
pub valid_to_precision: Option<String>,
pub confidence: Option<f32>,
/// 人工操作者;NULL = 引擎自动(抽取写入 / 时态对账闭合 / 高置信改类)
@@ -585,11 +585,11 @@ pub struct GraphChange {
pub valid_from: Option<DateTime<Utc>>,
pub valid_to: Option<DateTime<Utc>>,
/// 精度描述的是这条事实**有的那些日期**的粒度。两端都没有日期时为 None——
- /// 从前这里是 NOT NULL DEFAULT day,于是没日期的事实也自称精确到日(迁移 0045)
+ /// 从前这里是 NOT NULL DEFAULT day,于是没日期的事实也自称精确到日(见 `facts.valid_from_precision`)
/// 起始端的粒度:year | month | day。没有 valid_from 时为 None
pub valid_from_precision: Option<String>,
/// 结束端的粒度,外加一个 `unknown`——**原文说它结束了,但没说哪天**。
- /// `valid_to` 与它都为 None 才是「仍在持续」(迁移 0046)
+ /// `valid_to` 与它都为 None 才是「仍在持续」(见 `facts.valid_to_precision`)
pub valid_to_precision: Option<String>,
pub confidence: f32,
pub document_id: Option<Uuid>,
diff --git a/crates/utopia-reason/Cargo.toml b/crates/utopia-reason/Cargo.toml
index c5d73419..0e477a68 100644
--- a/crates/utopia-reason/Cargo.toml
+++ b/crates/utopia-reason/Cargo.toml
@@ -5,3 +5,4 @@ edition.workspace = true
license.workspace = true
[dependencies]
+uuid.workspace = true
diff --git a/crates/utopia-reason/src/lib.rs b/crates/utopia-reason/src/lib.rs
index 386548c4..1fb8dc7c 100644
--- a/crates/utopia-reason/src/lib.rs
+++ b/crates/utopia-reason/src/lib.rs
@@ -1,3 +1,544 @@
-//! utopia-reason: placeholder. Temporal Datalog interpreter for derived facts
-//! with explanations, plus the ontology axiom compiler.
-//! See the Roadmap in README.md.
+//! 一致性检查:拿本体声明的公理去量已经落库的事实(见 `docs/decisions/0002` R0)。
+//!
+//! **不写 `facts` 表,也不碰数据库。** 这一层只做判断:输入是边与公理,输出是
+//! 「哪几条事实互相矛盾」。取数与落库在 `utopia-store` / `utopia-server`。
+//!
+//! 这样分不是洁癖。ADR 说 R0 的价值在于「引擎的难点——规则表示、求值、终止——
+//! 全部建成并验证,而风险面为零」,而那些难点是纯逻辑:不起数据库就能跑几百个
+//! 用例,包括那些真实语料里未必凑得出来的形状(十一个节点的环、自环套在环里、
+//! 同一对节点被两条不同谓词连着)。
+//!
+//! **没有公理就没有依据。** 四类检查每一类都由本体里的一位布尔决定要不要查,
+//! 没声明就不查——不报矛盾比猜一个公理出来安全。所以一个没装本体包的库跑出来
+//! 是零,那是实情不是故障。
+
+use std::collections::{HashMap, HashSet};
+use uuid::Uuid;
+
+/// 一条参与检查的事实:谁、什么关系、指向谁。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Edge {
+ pub fact: Uuid,
+ pub predicate: Uuid,
+ pub subject: Uuid,
+ pub object: Uuid,
+}
+
+/// 一个谓词声明了哪些公理。四位都为假的谓词根本不进检查。
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub struct Axioms {
+ pub transitive: bool,
+ pub symmetric: bool,
+ pub asymmetric: bool,
+ pub irreflexive: bool,
+ pub functional: bool,
+ pub inverse_functional: bool,
+}
+
+impl Axioms {
+ /// 一位都没声明的谓词不必检查——**这是性能上的事,也是语义上的事**:
+ /// 没有公理就没有判据,扫它只会白扫。
+ fn says_nothing(&self) -> bool {
+ *self == Axioms::default()
+ }
+}
+
+/// 查出来的一处矛盾。`reason` 直接进 `fact_conflicts.reason`。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Violation {
+ pub kind: Kind,
+ /// 涉及的事实。**自反违反只有一条**——它跟自己矛盾,不需要第二条。
+ /// 环取首尾两条(中间那些在 `path` 里)。
+ pub left: Uuid,
+ pub right: Uuid,
+ /// 环的完整路径,按事实排列;其余三类为空。
+ /// 留着是因为「A→B→C→A」比「A 与 C 矛盾」有用得多——人要顺着看一遍才知道
+ /// 该撤哪一条
+ pub path: Vec<Uuid>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Kind {
+ /// `A p A`,而 p 声明了 irreflexive
+ SelfLoop,
+ /// `A p B` 且 `B p A`,而 p 声明了 asymmetric
+ Asymmetry,
+ /// `A p B p … p A`,而 p 声明了 transitive——闭包里推出 `A p A`
+ Cycle,
+ /// 同一主语与谓词同时指向两个宾语,而 p 声明了 functional
+ /// (inverse_functional 则是同一宾语被两个主语指)
+ Functional,
+}
+
+impl Kind {
+ pub fn as_str(self) -> &'static str {
+ match self {
+ Kind::SelfLoop => "self_loop",
+ Kind::Asymmetry => "asymmetry",
+ Kind::Cycle => "cycle",
+ Kind::Functional => "functional",
+ }
+ }
+}
+
+/// 环检测的深度上限。
+///
+/// **必须有,不是防御性编程。** 0002 在真实语料上量过:`part_of` 的传递闭包
+/// 从 185 条膨胀到 828 条且**不收敛**——深度分布 `1:185 2:181 3:141 4:45
+/// 5:52 6:40 7:52 8:40 9:52 10:40`,第 5 层起振荡而不是衰减,那是有环的形状。
+/// 没有上限,一个环就能让求值不终止。
+pub const MAX_DEPTH: usize = 12;
+
+/// 拿公理量一遍这批边。
+///
+/// 每个谓词各查各的:公理是挂在谓词上的,跨谓词的边之间没有可比性
+/// (`A part_of B` 与 `B produces A` 同时成立不是矛盾)。
+pub fn check(edges: &[Edge], axioms: &HashMap<Uuid, Axioms>) -> Vec<Violation> {
+ let mut out = Vec::new();
+ let mut by_pred: HashMap<Uuid, Vec<Edge>> = HashMap::new();
+ for e in edges {
+ let Some(ax) = axioms.get(&e.predicate) else {
+ continue;
+ };
+ if ax.says_nothing() {
+ continue;
+ }
+ by_pred.entry(e.predicate).or_default().push(*e);
+ }
+ for (pred, group) in by_pred {
+ let ax = axioms[&pred];
+ if ax.irreflexive {
+ out.extend(self_loops(&group));
+ }
+ if ax.asymmetric {
+ out.extend(asymmetries(&group));
+ }
+ if ax.transitive {
+ out.extend(cycles(&group));
+ }
+ if ax.functional {
+ out.extend(too_many(&group, |e| e.subject, |e| e.object));
+ }
+ if ax.inverse_functional {
+ out.extend(too_many(&group, |e| e.object, |e| e.subject));
+ }
+ }
+ out
+}
+
+fn self_loops(edges: &[Edge]) -> Vec<Violation> {
+ edges
+ .iter()
+ .filter(|e| e.subject == e.object)
+ .map(|e| Violation {
+ kind: Kind::SelfLoop,
+ // 两列填同一条:它跟自己矛盾,没有第二条事实可指
+ left: e.fact,
+ right: e.fact,
+ path: Vec::new(),
+ })
+ .collect()
+}
+
+fn asymmetries(edges: &[Edge]) -> Vec<Violation> {
+ let mut seen: HashMap<(Uuid, Uuid), Uuid> = HashMap::new();
+ let mut out = Vec::new();
+ for e in edges {
+ if e.subject == e.object {
+ // 自环由 irreflexive 那一档负责;反对称在这里报一遍是重复
+ continue;
+ }
+ if let Some(&other) = seen.get(&(e.object, e.subject)) {
+ out.push(Violation {
+ kind: Kind::Asymmetry,
+ left: other,
+ right: e.fact,
+ path: Vec::new(),
+ });
+ }
+ seen.insert((e.subject, e.object), e.fact);
+ }
+ out
+}
+
+/// 找环。**每个环只报一次**,从环上最小的节点起算。
+///
+/// 用深度优先而不是半朴素闭包求值:两者都能发现环,但闭包只告诉你「A 推出了
+/// A」,而人要的是**路径**——顺着 `A→B→C→A` 看一遍才知道该撤哪一条。闭包丢掉
+/// 的正是这个。
+///
+/// R1 物化推导要的是闭包本身,那时再建;R0 要的是「哪几条边凑成了环」。
+fn cycles(edges: &[Edge]) -> Vec<Violation> {
+ let mut adj: HashMap<Uuid, Vec<&Edge>> = HashMap::new();
+ for e in edges {
+ adj.entry(e.subject).or_default().push(e);
+ }
+ let mut reported: HashSet<Vec<Uuid>> = HashSet::new();
+ let mut out = Vec::new();
+ let nodes: Vec<Uuid> = adj.keys().copied().collect();
+ for start in nodes {
+ let mut path: Vec<&Edge> = Vec::new();
+ let mut on_path: HashSet<Uuid> = HashSet::new();
+ walk(
+ start,
+ start,
+ &adj,
+ &mut path,
+ &mut on_path,
+ &mut reported,
+ &mut out,
+ );
+ }
+ out
+}
+
+#[allow(clippy::too_many_arguments)]
+fn walk<'a>(
+ start: Uuid,
+ at: Uuid,
+ adj: &HashMap<Uuid, Vec<&'a Edge>>,
+ path: &mut Vec<&'a Edge>,
+ on_path: &mut HashSet<Uuid>,
+ reported: &mut HashSet<Vec<Uuid>>,
+ out: &mut Vec<Violation>,
+) {
+ if path.len() >= MAX_DEPTH {
+ return;
+ }
+ let Some(next) = adj.get(&at) else { return };
+ for e in next {
+ if e.object == start && !path.is_empty() {
+ // 回到起点:成环。**按事实 id 排序去重**——同一个环从不同节点
+ // 出发会被走到 n 次,报 n 遍就是让人把同一件事看 n 次
+ let mut facts: Vec<Uuid> = path.iter().map(|x| x.fact).collect();
+ facts.push(e.fact);
+ let mut key = facts.clone();
+ key.sort();
+ if reported.insert(key) {
+ out.push(Violation {
+ kind: Kind::Cycle,
+ left: facts[0],
+ right: *facts.last().unwrap(),
+ path: facts,
+ });
+ }
+ continue;
+ }
+ if e.object == start || on_path.contains(&e.object) {
+ continue;
+ }
+ on_path.insert(e.object);
+ path.push(e);
+ walk(start, e.object, adj, path, on_path, reported, out);
+ path.pop();
+ on_path.remove(&e.object);
+ }
+}
+
+/// 函数性违反:同一个「一端」指向了两个不同的「另一端」。
+///
+/// `functional` 与 `inverse_functional` 是同一个判断的两个方向,所以共用这一个
+/// 函数,由调用方决定哪一端是键。
+fn too_many(edges: &[Edge], key: fn(&Edge) -> Uuid, val: fn(&Edge) -> Uuid) -> Vec<Violation> {
+ let mut by_key: HashMap<Uuid, Vec<&Edge>> = HashMap::new();
+ for e in edges {
+ by_key.entry(key(e)).or_default().push(e);
+ }
+ let mut out = Vec::new();
+ for (_, group) in by_key {
+ // 只报第一对。同一个主语指了五个宾语时报十对(两两组合)只是把同一件事
+ // 说十遍——人要处理的是「这里有冲突」,看一对就够去查了
+ let mut distinct: Vec<&Edge> = Vec::new();
+ for e in group {
+ if !distinct.iter().any(|d| val(d) == val(e)) {
+ distinct.push(e);
+ }
+ }
+ if distinct.len() > 1 {
+ out.push(Violation {
+ kind: Kind::Functional,
+ left: distinct[0].fact,
+ right: distinct[1].fact,
+ path: Vec::new(),
+ });
+ }
+ }
+ out
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ /// 造边的简写。节点用小整数编出稳定的 uuid,读断言时看得出谁是谁。
+ fn n(i: u8) -> Uuid {
+ Uuid::from_bytes([i; 16])
+ }
+ fn f(i: u8) -> Uuid {
+ // 与节点 id 分段:节点用低位,事实用高位。`u8` 装得下 0..=255,
+ // 而测试里造过 30 条边的链——用 `200 + i` 会溢出
+ Uuid::from_bytes([i; 16].map(|b| b ^ 0xF0))
+ }
+ fn e(fact: u8, s: u8, o: u8) -> Edge {
+ Edge {
+ fact: f(fact),
+ predicate: n(99),
+ subject: n(s),
+ object: n(o),
+ }
+ }
+ fn with(ax: Axioms) -> HashMap<Uuid, Axioms> {
+ HashMap::from([(n(99), ax)])
+ }
+ fn kinds(v: &[Violation]) -> Vec<Kind> {
+ let mut k: Vec<Kind> = v.iter().map(|x| x.kind).collect();
+ k.sort_by_key(|x| x.as_str());
+ k
+ }
+
+ /// **没声明公理的谓词一条都不查。** 这是整套检查的地基:没有依据就不报矛盾。
+ ///
+ /// 反过来说也成立——一个没装本体包的库跑出来是零,那是实情不是故障。
+ #[test]
+ fn a_predicate_that_declares_nothing_is_never_checked() {
+ let edges = [e(1, 1, 1), e(2, 1, 2), e(3, 2, 1)];
+ assert!(check(&edges, &with(Axioms::default())).is_empty());
+ // 连 axioms 里都没有这个谓词时同样不查(本体里没有这一行)
+ assert!(check(&edges, &HashMap::new()).is_empty());
+ }
+
+ #[test]
+ fn a_self_loop_needs_irreflexive_to_be_a_problem() {
+ let edges = [e(1, 1, 1)];
+ assert!(check(
+ &edges,
+ &with(Axioms {
+ transitive: true,
+ ..Default::default()
+ })
+ )
+ .is_empty());
+ let v = check(
+ &edges,
+ &with(Axioms {
+ irreflexive: true,
+ ..Default::default()
+ }),
+ );
+ assert_eq!(kinds(&v), vec![Kind::SelfLoop]);
+ // 只有一条事实:两列填同一个 id
+ assert_eq!(v[0].left, v[0].right);
+ }
+
+ /// 反对称那一档**不重复报自环**。`A p A` 同时满足「有反向边」的字面意思,
+ /// 不挡掉的话一条自环会在两档里各报一次,人看到两条要处理的东西而其实是一件。
+ #[test]
+ fn a_self_loop_is_reported_once_not_twice() {
+ let edges = [e(1, 1, 1)];
+ let v = check(
+ &edges,
+ &with(Axioms {
+ irreflexive: true,
+ asymmetric: true,
+ ..Default::default()
+ }),
+ );
+ assert_eq!(kinds(&v), vec![Kind::SelfLoop]);
+ }
+
+ #[test]
+ fn a_pair_pointing_both_ways_needs_asymmetric() {
+ let edges = [e(1, 1, 2), e(2, 2, 1)];
+ assert!(check(
+ &edges,
+ &with(Axioms {
+ transitive: true,
+ ..Default::default()
+ })
+ )
+ .iter()
+ .all(|v| v.kind != Kind::Asymmetry));
+ let v = check(
+ &edges,
+ &with(Axioms {
+ asymmetric: true,
+ ..Default::default()
+ }),
+ );
+ assert_eq!(kinds(&v), vec![Kind::Asymmetry]);
+ assert_eq!((v[0].left, v[0].right), (f(1), f(2)));
+ }
+
+ /// 长环要报出**路径**,而不只是「首尾矛盾」——人要顺着看一遍才知道撤哪一条。
+ #[test]
+ fn a_long_cycle_reports_the_whole_path() {
+ let edges = [e(1, 1, 2), e(2, 2, 3), e(3, 3, 4), e(4, 4, 1)];
+ let v = check(
+ &edges,
+ &with(Axioms {
+ transitive: true,
+ ..Default::default()
+ }),
+ );
+ assert_eq!(v.len(), 1, "一个环只报一次");
+ assert_eq!(v[0].path.len(), 4, "四条边都该在路径里");
+ }
+
+ /// **同一个环从不同节点出发会被走到 n 次。** 去重是这个函数存在的一半理由:
+ /// 报四遍就是让人把同一件事看四遍。
+ #[test]
+ fn one_cycle_is_one_finding_however_many_ways_in() {
+ let edges = [e(1, 1, 2), e(2, 2, 3), e(3, 3, 1)];
+ let v = check(
+ &edges,
+ &with(Axioms {
+ transitive: true,
+ ..Default::default()
+ }),
+ );
+ assert_eq!(v.len(), 1);
+ }
+
+ /// 两个互不相干的环各报一次。
+ #[test]
+ fn separate_cycles_stay_separate() {
+ let edges = [e(1, 1, 2), e(2, 2, 1), e(3, 5, 6), e(4, 6, 5)];
+ let v = check(
+ &edges,
+ &with(Axioms {
+ transitive: true,
+ ..Default::default()
+ }),
+ );
+ assert_eq!(v.len(), 2);
+ }
+
+ /// **深度上限挡得住不收敛。** 0002 在真实语料上量到 `part_of` 闭包深度到 10
+ /// 仍在振荡;没有上限,一条长链加一个环就能让求值不终止。
+ ///
+ /// 这里造一条比上限更长的链再闭合——它不该让检查挂住,报不报得出那个环是
+ /// 次要的,**不挂住是首要的**。
+ #[test]
+ fn a_chain_longer_than_the_limit_still_terminates() {
+ let mut edges: Vec<Edge> = (0..30).map(|i| e(i, i, i + 1)).collect();
+ edges.push(e(60, 30, 0));
+ let v = check(
+ &edges,
+ &with(Axioms {
+ transitive: true,
+ ..Default::default()
+ }),
+ );
+ // 断言的是"跑完了",长度不作要求
+ assert!(v.len() <= 1);
+ }
+
+ #[test]
+ fn functional_and_its_inverse_are_two_directions_of_one_check() {
+ // 同一个主语指了两个宾语
+ let out = [e(1, 1, 2), e(2, 1, 3)];
+ assert_eq!(
+ kinds(&check(
+ &out,
+ &with(Axioms {
+ functional: true,
+ ..Default::default()
+ })
+ )),
+ vec![Kind::Functional]
+ );
+ assert!(check(
+ &out,
+ &with(Axioms {
+ inverse_functional: true,
+ ..Default::default()
+ })
+ )
+ .is_empty());
+
+ // 同一个宾语被两个主语指
+ let inn = [e(1, 2, 1), e(2, 3, 1)];
+ assert_eq!(
+ kinds(&check(
+ &inn,
+ &with(Axioms {
+ inverse_functional: true,
+ ..Default::default()
+ })
+ )),
+ vec![Kind::Functional]
+ );
+ assert!(check(
+ &inn,
+ &with(Axioms {
+ functional: true,
+ ..Default::default()
+ })
+ )
+ .is_empty());
+ }
+
+ /// 同一个主语指五个宾语只报一对。报十对(两两组合)是把同一件事说十遍——
+ /// 人要处理的是「这里有冲突」,看一对就够去查了。
+ #[test]
+ fn one_finding_per_conflicting_key_not_one_per_pair() {
+ let edges = [e(1, 1, 2), e(2, 1, 3), e(3, 1, 4), e(4, 1, 5), e(5, 1, 6)];
+ let v = check(
+ &edges,
+ &with(Axioms {
+ functional: true,
+ ..Default::default()
+ }),
+ );
+ assert_eq!(v.len(), 1);
+ }
+
+ /// 同一个主语两次指向**同一个**宾语不是冲突——重复断言而已。
+ #[test]
+ fn saying_the_same_thing_twice_is_not_a_contradiction() {
+ let edges = [e(1, 1, 2), e(2, 1, 2)];
+ assert!(check(
+ &edges,
+ &with(Axioms {
+ functional: true,
+ ..Default::default()
+ })
+ )
+ .is_empty());
+ }
+
+ /// **公理挂在谓词上,跨谓词的边之间没有可比性。**
+ /// `A p B` 与 `B q A` 同时成立不是矛盾,哪怕 p 声明了反对称。
+ #[test]
+ fn axioms_do_not_leak_across_predicates() {
+ let a = Edge {
+ fact: f(1),
+ predicate: n(90),
+ subject: n(1),
+ object: n(2),
+ };
+ let b = Edge {
+ fact: f(2),
+ predicate: n(91),
+ subject: n(2),
+ object: n(1),
+ };
+ let ax = HashMap::from([
+ (
+ n(90),
+ Axioms {
+ asymmetric: true,
+ ..Default::default()
+ },
+ ),
+ (
+ n(91),
+ Axioms {
+ asymmetric: true,
+ ..Default::default()
+ },
+ ),
+ ]);
+ assert!(check(&[a, b], &ax).is_empty());
+ }
+}
diff --git a/crates/utopia-server/src/api/admin_routes.rs b/crates/utopia-server/src/api/admin_routes.rs
index ce5622d3..0c123401 100644
--- a/crates/utopia-server/src/api/admin_routes.rs
+++ b/crates/utopia-server/src/api/admin_routes.rs
@@ -145,7 +145,7 @@ pub async fn create_user(
Ok(Json(json!({ "user": created })))
}
-/// 停用一个账号(软删除,见迁移 0056)。
+/// 停用一个账号(软删除,见 `users.deactivated_at`)。
///
/// **不是 DELETE。** 审计事件、合并日志、改类账本、口径确认的 `actor_id` 都指着
/// 这个人,那些是审计材料——人走了仍然要能回答「当时是谁做的」。停用只断访问:
diff --git a/crates/utopia-server/src/api/chat.rs b/crates/utopia-server/src/api/chat.rs
index 2116e141..95b8dd9f 100644
--- a/crates/utopia-server/src/api/chat.rs
+++ b/crates/utopia-server/src/api/chat.rs
@@ -904,7 +904,7 @@ async fn run_query(state: &AppState, ds_id: Uuid, sql: &str) -> anyhow::Result<S
fn fact_line(f: &EntityFact) -> String {
let other = f.other_name.as_deref().unwrap_or("?");
// 本体没认下、原文说法也没留下时用 "?"——与 other 同一个约定。
- // 不编一个"相关"出来:那正是 0052 删掉 related_to 要消灭的东西
+ // 不编一个"相关"出来:那正是删掉 related_to 要消灭的东西
let pred = f.predicate_label.as_deref().unwrap_or("?");
let core = if f.direction == "out" {
format!("{pred} → {other}")
@@ -1137,8 +1137,8 @@ mod tests {
object_value: None,
valid_from: None,
valid_to: None,
- // 两端都没日期就没有精度——夹具也得守这条不变量(迁移 0045)
- // 两端都没日期,所以两端都没有精度(迁移 0045 / 0046)
+ // 两端都没日期就没有精度——夹具也得守这条不变量(见 `facts.valid_from_precision`)
+ // 两端都没日期,所以两端都没有精度(见 facts 的两个精度列)
valid_from_precision: None,
valid_to_precision: None,
confidence: 0.9,
diff --git a/crates/utopia-server/src/api/mod.rs b/crates/utopia-server/src/api/mod.rs
index 2087f885..82b041ee 100644
--- a/crates/utopia-server/src/api/mod.rs
+++ b/crates/utopia-server/src/api/mod.rs
@@ -89,7 +89,7 @@ pub fn router(state: AppState, cfg: &AppConfig) -> Router {
get(admin_routes::get_deployment).put(admin_routes::put_deployment),
)
.route("/admin/users", post(admin_routes::create_user))
- // 停用 / 恢复账号(0056)。DELETE 的语义是「这个人不再有访问权」,
+ // 停用 / 恢复账号(见 `users.deactivated_at`)。DELETE 的语义是「这个人不再有访问权」,
// 而不是「这一行没了」——归因照旧查得到
.route(
"/admin/users/{id}",
@@ -182,7 +182,7 @@ pub fn router(state: AppState, cfg: &AppConfig) -> Router {
post(ontology_routes::restore_miss),
)
.route("/kbs/{id}/ontology/suggest", post(ontology_routes::suggest))
- // 上次算出来、还没人表态的那些(0049)。刷新页面靠它,不必重跑模型
+ // 上次算出来、还没人表态的那些(迁移 0018)。刷新页面靠它,不必重跑模型
.route(
"/kbs/{id}/ontology/proposals",
get(ontology_routes::stored_proposals).post(ontology_routes::decide_proposal),
diff --git a/crates/utopia-server/src/api/ontology_routes.rs b/crates/utopia-server/src/api/ontology_routes.rs
index 463ab1c3..a5daaacd 100644
--- a/crates/utopia-server/src/api/ontology_routes.rs
+++ b/crates/utopia-server/src/api/ontology_routes.rs
@@ -367,7 +367,7 @@ pub async fn suggest(
// 人工那条路 min_docs = 0:面板上「出现在 1 篇」这个数字是显示给人看的,
// 他自己判断得了。替他滤掉,只是让他少一条信息
let proposals = build_proposals(&state, kb_id, &locale, 0).await?;
- // 算完就写下来(0049)。从前这批结果只回给前端、存进一个 useState,
+ // 算完就写下来(迁移 0018)。从前这批结果只回给前端、存进一个 useState,
// 刷新一次就没了——而重算要再调一次模型,且未必给出同一批归并
persist_proposals(&state, kb_id, &proposals).await;
Ok(Json(proposals))
diff --git a/crates/utopia-server/src/extraction.rs b/crates/utopia-server/src/extraction.rs
index 4fb7acd0..b7908978 100644
--- a/crates/utopia-server/src/extraction.rs
+++ b/crates/utopia-server/src/extraction.rs
@@ -172,14 +172,14 @@ async fn run(state: &AppState, document_id: Uuid) -> anyhow::Result<()> {
let rtypes = utopia_store::graph::relation_types(&state.pool, doc.kb_id).await?;
// 关系与属性分道:属性走字面值通道,不进关系清单。
//
- // **本体里没有对应关系时就没有谓词**(迁移 0052)。原词落进
+ // **本体里没有对应关系时就没有谓词**(见 `facts.predicate_id`)。原词落进
// fact_evidence.proposed_predicate,显示时由 fact_surface_predicate() 取回。
//
// 从前这里是一个叫 related_to 的兜底关系,且刻意不列给模型——它摆进提示词就成了
// 逃生舱,模型读到说不清的关系时不去写原文说法,直接挑这个万能选项。
// 现在它连行都没有了,逃生舱和"记得别列它"这两件事一起消失。
//
- // **这两件事必须一起做,缺一件比都不做更糟。** 0052 只删了库里的行,没删
+ // **这两件事必须一起做,缺一件比都不做更糟。** 只删库里的行不够,还要删
// `DEFAULT_RELATION_TYPES` 里的种子——而这里的排除过滤已经跟着删了。于是
// `ensure_default_ontology` 七分钟后把行种回来,`related_to` 第一次被**列进
// 提示词给模型看**。0001 量过:359 次使用里 321 次是模型从清单上挑的。
@@ -465,7 +465,7 @@ async fn run(state: &AppState, document_id: Uuid) -> anyhow::Result<()> {
}
let from = f.valid_from.as_deref().and_then(utopia_extract::parse_time);
let to = f.valid_to.as_deref().and_then(utopia_extract::parse_time);
- // **两端各记各的粒度**(迁移 0046)。从前一个精度列描述两个端点,
+ // **两端各记各的粒度**(见 `facts.valid_to_precision`)。从前一个精度列描述两个端点,
// 于是「2020 年开始、2023-05-06 结束」这种只能共用一个值。
//
// 模型给的 valid_to = "unknown" 表示**原文说它结束了、但没说哪天**。
@@ -765,7 +765,7 @@ async fn run(state: &AppState, document_id: Uuid) -> anyhow::Result<()> {
Some(&format!("{} → {}", f.subject, object_name)),
)
.await;
- // 本体里没有对应的关系 → **就是没有谓词**(迁移 0052)。
+ // 本体里没有对应的关系 → **就是没有谓词**(见 `facts.predicate_id`)。
// 原意留在证据的 proposed_predicate 里,显示时取回。
// 从前这里落到 related_to 上,还要额外担心"兜底关系被删了"——
// 那条失败模式连同它的 continue 一起消失了
diff --git a/crates/utopia-server/src/ontology_index.rs b/crates/utopia-server/src/ontology_index.rs
index b2ca146a..703c7c55 100644
--- a/crates/utopia-server/src/ontology_index.rs
+++ b/crates/utopia-server/src/ontology_index.rs
@@ -175,7 +175,7 @@ pub async fn nearest_for_each(
pub enum Target {
/// 整段索引(label + 描述)。长画像走这一路
Class,
- /// **只有 label 的索引**(0050)。短说法(`district. place`)走这一路。
+ /// **只有 label 的索引**(见 `entity_types.label_embedding`)。短说法(`district. place`)走这一路。
/// 短说法比整段索引会被同义反复的类接管——`Map` 那一行的描述就是
/// "A map.",赢在长度不在语义
ClassLabel,
diff --git a/crates/utopia-server/src/owl_import.rs b/crates/utopia-server/src/owl_import.rs
index e04dc3bb..070792d0 100644
--- a/crates/utopia-server/src/owl_import.rs
+++ b/crates/utopia-server/src/owl_import.rs
@@ -461,7 +461,7 @@ pub async fn apply(
// 换一个"发现得早一点",不划算
utopia_store::ontology::set_parents_bulk(&state.pool, &parent_edges).await?;
- // 类互斥同理攒一批(0054)。指向没被建出来的类的那些自然落选——
+ // 类互斥同理攒一批(见 `relation_types` 的公理列)。指向没被建出来的类的那些自然落选——
// 一条互斥声明的两端都得在这个库里,才谈得上拿它判矛盾
let mut disjoint_edges: Vec<(Uuid, Uuid)> = Vec::new();
for c in &proj.classes {
diff --git a/crates/utopia-server/src/type_resolution.rs b/crates/utopia-server/src/type_resolution.rs
index 18ebedd2..a53ab3bb 100644
--- a/crates/utopia-server/src/type_resolution.rs
+++ b/crates/utopia-server/src/type_resolution.rs
@@ -129,7 +129,7 @@ pub async fn preview(state: &AppState, kb_id: Uuid) -> AppResult<Vec<TypeSuggest
// 两次结果取并集——多一次嵌入,换掉一整类漏检。
let profiles: Vec<String> = subjects.iter().map(profile_of).collect();
let names: Vec<Option<String>> = subjects.iter().map(name_query_of).collect();
- // **两路各查各的索引**(0050)。从前两路共用整段索引,于是短说法那一路
+ // **两路各查各的索引**(见 `entity_types.label_embedding`)。从前两路共用整段索引,于是短说法那一路
// 被同义反复的类接管:`district. place` 回来的是 Map / Park / Country /
// Museum,四个赢家的嵌入原文全是 `X\nAn X.` 一行话,而带一百字定义的
// AdministrativeArea 排不进前八。短对短、长对长,这才是可比的
@@ -398,7 +398,7 @@ pub struct ReviewItem {
/// 跑一轮类型消解并落库。
///
/// **落库时不带 actor,尽管是人点的运行。** `retype_entities` 的 actor 参数
-/// 现在有两重身份:账本里记"谁改的",而 0051 之后它还决定 `type_source`——
+/// 现在有两重身份:账本里记"谁改的",而它现在还决定 `type_source`——
/// 有 actor 就是 `human`,而 `human` 意味着**引擎从此不再碰这个实体**。
///
/// 这两个问题不是一回事:
diff --git a/crates/utopia-store/src/access.rs b/crates/utopia-store/src/access.rs
index 5e3af9f1..0a478789 100644
--- a/crates/utopia-store/src/access.rs
+++ b/crates/utopia-store/src/access.rs
@@ -102,7 +102,7 @@ pub async fn kb_members(pool: &PgPool, kb_id: Uuid) -> AppResult<Vec<KbMemberVie
let rows: Vec<KbMemberView> = sqlx::query_as(
"SELECT m.user_id, u.email, u.display_name, m.role
FROM kb_members m JOIN users u ON u.id = m.user_id
- -- 停用的人不出现在成员列表里(0056);成员关系那一行留着
+ -- 停用的人不出现在成员列表里(见 `users.deactivated_at`);成员关系那一行留着
WHERE m.kb_id = $1 AND u.deactivated_at IS NULL ORDER BY u.display_name",
)
.bind(kb_id)
diff --git a/crates/utopia-store/src/accounts.rs b/crates/utopia-store/src/accounts.rs
index d1629023..8ab2fd36 100644
--- a/crates/utopia-store/src/accounts.rs
+++ b/crates/utopia-store/src/accounts.rs
@@ -201,7 +201,7 @@ pub async fn admin_create_user(
///
/// 这一句 `deactivated_at IS NULL` 同时管两件事:停用的人登不进来,以及
/// 「一个 email 在停用账号里可能重复」时不会随机返回其中一条(唯一索引
-/// 现在是部分的,只约束在职账号,见迁移 0056)。
+/// 现在是部分的,只约束在职账号,见 `users.deactivated_at`)。
pub async fn find_user_by_email(pool: &PgPool, email: &str) -> AppResult<Option<User>> {
let user = sqlx::query_as("SELECT * FROM users WHERE email = $1 AND deactivated_at IS NULL")
.bind(email)
@@ -244,7 +244,7 @@ pub async fn update_password(pool: &PgPool, id: Uuid, password_hash: &str) -> Ap
Ok(())
}
-/// 停用一个账号(软删除,见迁移 0056)。
+/// 停用一个账号(软删除,见 `users.deactivated_at`)。
///
/// **不删行。** 审计事件、合并日志、改类账本、口径确认的 `actor_id` 都指着这个人,
/// 而那些是审计材料——人走了仍然要能回答「当时是谁做的」。停用只断访问。
diff --git a/crates/utopia-store/src/graph.rs b/crates/utopia-store/src/graph.rs
index 4c432b5b..b2bb421e 100644
--- a/crates/utopia-store/src/graph.rs
+++ b/crates/utopia-store/src/graph.rs
@@ -95,7 +95,7 @@ pub async fn insert_fact(
kb_id: Uuid,
subject_id: Uuid,
// None = 本体里没有对应的关系。原意不丢——它在证据的 proposed_predicate 里,
- // 显示时由 fact_surface_predicate() 取回(迁移 0052)
+ // 显示时由 fact_surface_predicate() 取回(见 `facts.predicate_id`)
predicate_id: Option<Uuid>,
object_id: Uuid,
validity: Validity<'_>,
@@ -126,7 +126,7 @@ pub async fn insert_fact(
/// | **结束了,不知哪天** | `None` | `Some("unknown")` |
/// | 某时结束 | `Some(t)` | `Some("year"/"month"/"day")` |
///
-/// 第二行是 0046 加的。在它之前 `to = None` 同时承载「还在持续」和「不知何时
+/// 第二行是后加的。在它之前 `to = None` 同时承载「还在持续」和「不知何时
/// 结束」,于是 "former CEO of Weta Digital" 这种**结束明确、日期缺失**的句子
/// 只能写成前者,图会断言一件原文说已经结束的事。
#[derive(Debug, Clone, Copy, Default)]
@@ -164,7 +164,7 @@ impl<'a> Validity<'a> {
/// 这条断言是否已经不再成立——**两种结束都算**。
///
/// 判据写在这里而不是散在各处的 `valid_to.is_some()`:那种写法会把
- /// 「结束了但不知哪天」漏成「仍在持续」,而那正是 0046 要修的东西。
+ /// 「结束了但不知哪天」漏成「仍在持续」,而那正是两端各记精度要修的东西。
pub fn has_ended(&self) -> bool {
self.to.is_some() || self.to_precision == Some(ENDED_UNKNOWN)
}
@@ -176,7 +176,7 @@ async fn insert_fact_inner(
kb_id: Uuid,
subject_id: Uuid,
// None = 本体里没有对应的关系。原意不丢——它在证据的 proposed_predicate 里,
- // 显示时由 fact_surface_predicate() 取回(迁移 0052)
+ // 显示时由 fact_surface_predicate() 取回(见 `facts.predicate_id`)
predicate_id: Option<Uuid>,
object: FactObject<'_>,
validity: Validity<'_>,
@@ -292,7 +292,7 @@ pub async fn insert_value_fact(
kb_id: Uuid,
subject_id: Uuid,
// None = 本体里没有对应的关系。原意不丢——它在证据的 proposed_predicate 里,
- // 显示时由 fact_surface_predicate() 取回(迁移 0052)
+ // 显示时由 fact_surface_predicate() 取回(见 `facts.predicate_id`)
predicate_id: Option<Uuid>,
object_value: &serde_json::Value,
validity: Validity<'_>,
diff --git a/crates/utopia-store/src/mappings.rs b/crates/utopia-store/src/mappings.rs
index 52378a93..8b1bf0b4 100644
--- a/crates/utopia-store/src/mappings.rs
+++ b/crates/utopia-store/src/mappings.rs
@@ -1,7 +1,7 @@
//! 语义层的「业务概念 → 数据资产」映射(见 `docs/decisions/0011`)。
//!
//! 它从前是一条 `mapped_to` 事实,宾语是塞在 `object_value` 里的一份 JSON。
-//! 搬出来的理由写在迁移 0055 里,一句话:**它不是关于世界的断言,是配置**。
+//! 搬出来的理由写在迁移 0019 里,一句话:**它不是关于世界的断言,是配置**。
//!
//! 与账本的区别在这里就能看见:这张表**允许原地改**。`confirm` 改的是
//! 「这条配置生效了没有」,不是「我们对世界的认知变了」——所以它不需要
@@ -19,7 +19,7 @@ use uuid::Uuid;
///
/// 已经有人表过态的不覆盖:重跑探索会再次算出被拒绝过的那条,不加这一句
/// 它就被刷回待看,等于每跑一次都把人的否决抹掉一次(`ontology_proposals`
-/// 那边踩过同一个坑,见 0049)。
+/// 那边踩过同一个坑,见 `ontology_proposals`)。
#[allow(clippy::too_many_arguments)]
pub async fn propose(
pool: &PgPool,
diff --git a/crates/utopia-store/src/members.rs b/crates/utopia-store/src/members.rs
index 09404160..ff909c68 100644
--- a/crates/utopia-store/src/members.rs
+++ b/crates/utopia-store/src/members.rs
@@ -7,7 +7,7 @@ pub async fn list(pool: &PgPool, workspace_id: Uuid) -> AppResult<Vec<MemberView
let rows = sqlx::query_as(
"SELECT m.user_id, u.email, u.display_name, m.role, u.is_admin
FROM memberships m JOIN users u ON u.id = m.user_id
- -- 停用的人不再出现在成员列表里(0056)。成员关系那一行留着——
+ -- 停用的人不再出现在成员列表里(见 `users.deactivated_at`)。成员关系那一行留着——
-- 恢复账号时不必重新加回每一个工作区
WHERE m.workspace_id = $1 AND u.deactivated_at IS NULL
ORDER BY m.created_at",
diff --git a/crates/utopia-store/src/ontology.rs b/crates/utopia-store/src/ontology.rs
index 87050444..bb4875ad 100644
--- a/crates/utopia-store/src/ontology.rs
+++ b/crates/utopia-store/src/ontology.rs
@@ -827,7 +827,7 @@ pub struct TypeToEmbed {
pub kind: TypeKind,
pub text: String,
/// 写进哪一组列。类有两份向量:整段(label + 描述)与只有 label 的那份,
- /// 分别服务长画像与短说法两种查询(见迁移 0050)
+ /// 分别服务长画像与短说法两种查询(见 `entity_types.label_embedding`)
pub field: EmbedField,
}
@@ -897,7 +897,7 @@ pub async fn types_needing_embedding(
text: embed_text(&label, &desc),
field: EmbedField::Full,
}));
- // 只嵌 label 的那一份(0050)。短查询走这个索引——查询分了两种形状,
+ // 只嵌 label 的那一份(见 `entity_types.label_embedding`)。短查询走这个索引——查询分了两种形状,
// 文档也得分两种,否则短查询被同义反复的类接管
let labels: Vec<(Uuid, String)> = sqlx::query_as(
"SELECT id, label FROM entity_types
@@ -965,7 +965,7 @@ pub async fn set_type_embeddings(
TypeKind::Entity => "entity_types",
TypeKind::Relation => "relation_types",
};
- // 两份向量各写各的列(0050)。列名前缀不同,其余一模一样
+ // 两份向量各写各的列(见 `entity_types.label_embedding`)。列名前缀不同,其余一模一样
let (vec_col, text_col, model_col) = match item.field {
EmbedField::Full => ("embedding", "embedded_text", "embedded_model"),
EmbedField::Label => (
@@ -1009,7 +1009,7 @@ pub async fn nearest_entity_types(
kb_id: Uuid,
embedding: &[f32],
limit: i64,
- // true = 比只有 label 的那份向量(0050)。短说法走这一路:**短对短**,
+ // true = 比只有 label 的那份向量(见 `entity_types.label_embedding`)。短说法走这一路:**短对短**,
// 否则 `district. place` 会被 `Map\nA map.` 这类同义反复的一行话赢过去
by_label: bool,
) -> AppResult<Vec<TypeCandidate>> {
@@ -1379,7 +1379,7 @@ pub async fn set_parents_bulk(pool: &PgPool, pairs: &[(Uuid, Uuid)]) -> AppResul
Ok(())
}
-/// 类互斥落库(迁移 0054)。语义同 [`set_parents_bulk`]。
+/// 类互斥落库(见 `relation_types` 的公理列)。语义同 [`set_parents_bulk`]。
///
/// **两个方向都写。** 解析侧已经把 `owl:disjointWith` 的对称性展开成两条,
/// 这里照写即可——查"A 与 B 互斥吗"因此不必关心从哪一头问。
@@ -1412,7 +1412,7 @@ pub async fn set_disjoint_bulk(
}
// ---------------------------------------------------------------------------
-// 本体提案(见迁移 0049)
+// 本体提案(迁移 0018)
// ---------------------------------------------------------------------------
/// 一条落库的提案。`payload` 是接口原样返回的那一条。
diff --git a/crates/utopia-store/src/resolution.rs b/crates/utopia-store/src/resolution.rs
index 4f6b11f2..e8eb8bfd 100644
--- a/crates/utopia-store/src/resolution.rs
+++ b/crates/utopia-store/src/resolution.rs
@@ -342,7 +342,7 @@ const CONTAIN_SCAN_LIMIT: i64 = 16;
///
/// **已知不覆盖**:两个名字既不互相包含、又没有共同别名做桥的情形
///(`启明 X7 加速卡` 与 `启明 X7 推理加速卡`)。那要三元组相似度,而
-/// `CREATE EXTENSION pg_trgm` 需要超级权限——本仓库是受限角色连库(迁移 0031),
+/// `CREATE EXTENSION pg_trgm` 需要超级权限——本仓库是受限角色连库(迁移 0014),
/// 装扩展会在部署上失败。留给需要时再说。
///
/// **性能**:反向那半(新名字包含旧名字)用不上任何索引,别名那半同样,
diff --git a/crates/utopia-store/tests/a_mapping_is_not_a_fact.rs b/crates/utopia-store/tests/a_mapping_is_not_a_fact.rs
index c8e18dbb..e91f718d 100644
--- a/crates/utopia-store/tests/a_mapping_is_not_a_fact.rs
+++ b/crates/utopia-store/tests/a_mapping_is_not_a_fact.rs
@@ -6,7 +6,7 @@
//! 这个 JSONB 内部,数据库看不见,只能靠确认流程显式闭合——也就是靠流程
//! 而不是约束。现在它是主键。
//! 2. **表过态的不被下一轮探索刷回待看。** `ontology_proposals` 那边踩过同一个
-//! 坑(0049):重跑必然再次算出被拒绝过的那条,不挡住就等于每跑一次都把
+//! 坑(迁移 0018):重跑必然再次算出被拒绝过的那条,不挡住就等于每跑一次都把
//! 人的否决抹掉一次。
use sqlx::PgPool;
diff --git a/crates/utopia-store/tests/a_retired_account.rs b/crates/utopia-store/tests/a_retired_account.rs
index 7bc2c911..3e1dcc82 100644
--- a/crates/utopia-store/tests/a_retired_account.rs
+++ b/crates/utopia-store/tests/a_retired_account.rs
@@ -1,4 +1,4 @@
-//! 停用账号的四条硬性质——打在真库上(见迁移 0056)。
+//! 停用账号的四条硬性质——打在真库上(见 `users.deactivated_at`)。
//!
//! 软删除的风险全在「漏过滤一处」:只要有一条读 `users` 的路径忘了带
//! `deactivated_at IS NULL`,停用就成了摆设,而且**不会有任何报错**。
diff --git a/crates/utopia-store/tests/adopt_swap.rs b/crates/utopia-store/tests/adopt_swap.rs
index 8f9777e1..99e7a9af 100644
--- a/crates/utopia-store/tests/adopt_swap.rs
+++ b/crates/utopia-store/tests/adopt_swap.rs
@@ -75,7 +75,7 @@ async fn adopting_a_passive_wording_flips_subject_and_object() -> anyhow::Result
.execute(&pool)
.await?;
// 原文说的是 "ChatGPT produced_by OpenAI",本体里没有这个关系,
- // 于是这条事实**没有谓词**——0052 之后兜底谓词不存在了
+ // 于是这条事实**没有谓词**——兜底谓词已经不存在了
sqlx::query(
"INSERT INTO facts (id, kb_id, subject_id, predicate_id, object_id)
VALUES ($1, $2, $3, NULL, $4)",
diff --git a/crates/utopia-store/tests/ended_when_unknown.rs b/crates/utopia-store/tests/ended_when_unknown.rs
index c0ce8981..66410422 100644
--- a/crates/utopia-store/tests/ended_when_unknown.rs
+++ b/crates/utopia-store/tests/ended_when_unknown.rs
@@ -1,6 +1,6 @@
//! 「结束了,但不知道哪天」这个状态,打在真库上。
//!
-//! 迁移 0046 之前,`valid_to IS NULL` 同时表示「还在持续」和「结束了但不知何时」。
+//! 两端各记精度之前,`valid_to IS NULL` 同时表示「还在持续」和「结束了但不知何时」。
//! 那两件事**真值相反**——一个说关系现在成立,一个说不成立——而账本只有一种写法,
//! 于是 "former CEO of Weta Digital" 只能写成前者,图会断言一件原文说已经结束的事。
//!
diff --git a/crates/utopia-store/tests/human_type_decisions.rs b/crates/utopia-store/tests/human_type_decisions.rs
index 4673eca4..bb15e61c 100644
--- a/crates/utopia-store/tests/human_type_decisions.rs
+++ b/crates/utopia-store/tests/human_type_decisions.rs
@@ -314,7 +314,7 @@ async fn who_approved_a_retype_decides_whether_it_is_protected() -> anyhow::Resu
/// **引擎改过的实体,下一轮还要捞得回来。**
///
/// 这一条守的是一个真出过的事故:类型消解落库时把「点运行的那个人」当成了
-/// `retype_entities` 的 actor,而 0051 之后有 actor 就写 `type_source = 'human'`。
+/// `retype_entities` 的 actor,而有 actor 就写 `type_source = 'human'`。
/// 于是**跑过一次消解的实体从此永远不再被消解**——一个没有任何人工 PATCH 记录
/// 的库,跑完一轮之后预览返回空列表,而且没有任何报错。
///
diff --git a/crates/utopia-store/tests/no_predicate_still_shows.rs b/crates/utopia-store/tests/no_predicate_still_shows.rs
index 29d7d2e8..f5637c0d 100644
--- a/crates/utopia-store/tests/no_predicate_still_shows.rs
+++ b/crates/utopia-store/tests/no_predicate_still_shows.rs
@@ -1,6 +1,6 @@
-//! 没有谓词的事实**不能从读路径上消失**(迁移 0052)。
+//! 没有谓词的事实**不能从读路径上消失**(见 `facts.predicate_id`)。
//!
-//! 为什么非要连库:0052 把 `facts.predicate_id` 改成可空之后,二十条读查询里的
+//! 为什么非要连库:`facts.predicate_id` 改成可空之后,二十条读查询里的
//! `JOIN relation_types` 全都变成了静默的过滤器——内连接丢掉 NULL 行不报错、
//! 不告警,`cargo check` 和 clippy 一个字都看不见。这与 0009 的
//! `NULL <> uuid` 是同一个陷阱的两副面孔:三值逻辑下"没有值"被当成"不匹配"。
@@ -22,7 +22,7 @@ struct Fixture {
doc: Uuid,
/// 没有谓词、但证据里留了原文说法的事实
surfaced: Uuid,
- /// 没有谓词、连原文说法也没有的事实(0052 之前的历史遗留长这样)
+ /// 没有谓词、连原文说法也没有的事实(更早的历史遗留长这样)
mute: Uuid,
}
@@ -101,7 +101,7 @@ async fn seed(pool: &PgPool) -> anyhow::Result<Fixture> {
.await?;
}
- // 两条事实都没有谓词——本体里没有对应的关系,这正是 0052 要表达的状态
+ // 两条事实都没有谓词——本体里没有对应的关系,这正是可空谓词要表达的状态
for (id, from) in [
(surfaced, "2020-01-01T00:00:00Z"),
(mute, "2021-01-01T00:00:00Z"),
@@ -241,7 +241,7 @@ async fn a_fact_without_a_predicate_is_still_visible_everywhere() -> anyhow::Res
// 这一条的历史值得留着:第一版是空断言(只 `SELECT … WHERE builtin`,
// 而夹具是裸 SQL 建的库、从没播种过,于是断言在一片空地上成立);
// 第二版补了对照组——先调 `ensure_default_ontology` 把种子种下去,
- // 再确认 `related_to` 不在其中。因为 0052 删完七分钟,代码就把行种回来了(0053)。
+ // 再确认 `related_to` 不在其中。因为删完七分钟,代码就把行种回来过一次。
//
// 现在**连播种函数都没有了**:0009 删内置实体类、0010 与 `#125` 删种子关系、
// 0011 把 `mapped_to` 搬去 `concept_mappings`,`ensure_default_ontology`
diff --git a/crates/utopia-store/tests/proposal_counts.rs b/crates/utopia-store/tests/proposal_counts.rs
index ceeb249e..8bc88d1e 100644
--- a/crates/utopia-store/tests/proposal_counts.rs
+++ b/crates/utopia-store/tests/proposal_counts.rs
@@ -60,7 +60,7 @@ async fn seed(pool: &PgPool) -> anyhow::Result<Uuid> {
.bind(kb)
.execute(pool)
.await?;
- // 积压的那条不挂任何关系——查询按 predicate_id IS NULL 筛(0052)
+ // 积压的那条不挂任何关系——查询按 predicate_id IS NULL 筛(见 `facts.predicate_id`)
sqlx::query("INSERT INTO relation_types (id, kb_id, key, label) VALUES ($1, $2, $3, $3)")
.bind(real)
.bind(kb)
diff --git a/docs/decisions/0001-ontology-import-and-governance.md b/docs/decisions/0001-ontology-import-and-governance.md
index 6a80f909..b7cacecb 100644
--- a/docs/decisions/0001-ontology-import-and-governance.md
+++ b/docs/decisions/0001-ontology-import-and-governance.md
@@ -186,7 +186,7 @@ v2: http://acme.com/hr#Employee rdfs:label "Staff Member" → key = staff_membe
> 落地的是三层里的前两层与整条预览流程:解析(`utopia-ingest/src/ontology_rdf.rs`)、
> 计划与执行(`utopia-server/src/owl_import.rs`,预览与落库**共用同一个 `plan()`**)、
> 界面(本体页左栏底部 Import 入口 → 选文件 → 计划 → 确认)。
-> `ontology_imports` 表与 `entity_types.iri` / `relation_types.iri` 见迁移 0031。
+> `ontology_imports` 表与 `entity_types.iri` / `relation_types.iri` 见迁移 0015。
>
> **对着真实词汇表验证,不是自己写的样例**。FOAF(RDF/XML,635 三元组):
> 15 类 + 89 属性,`functional` / `inverse_functional` / domain / range 全部读出;
@@ -221,7 +221,7 @@ v2: http://acme.com/hr#Employee rdfs:label "Staff Member" → key = staff_membe
属性在产品里早已完整:`relation_types` 一表两用(`kind='attribute'`),
`domain_type_id` 指明挂在哪个类下,`datatype` / `unit` 描述取值,值走
-`facts.object_value`,时态、证据、审阅全套复用(迁移 0004)。
+`facts.object_value`,时态、证据、审阅全套复用(见 `relation_types.kind`)。
缺的只是**导入器不建它们**。FOAF 的 54 个 `owl:DatatypeProperty` 解析出来了、
预览里报了数,但 `apply()` 跳过。初稿把原因记成"要 domain,而 domain 要等类
@@ -307,7 +307,7 @@ OWL 里一个属性有多个 domain 是常态。`datatype` 仍留在 `relation_t
#### 四、多继承 DAG
-`entity_types.parent_id` 是单列(迁移 0005),只能表达树。而多继承在真实词汇表里
+`entity_types.parent_id` 曾是单列,只能表达树。而多继承在真实词汇表里
是常态——FOAF 的 `Person` 同时是 `foaf:Agent` 与 `geo:SpatialThing`,两个方向,
不是同一根链上的祖孙。P2b 目前**只投影第一个父类**。
@@ -496,7 +496,7 @@ related_to 事实 359 条
**顺序不能反**:先有 P0 的编辑能力,才有"人工决策"可保护、可学习。
-1. **决策不可被遗忘(正确性,不是功能)** —— **已建成**(迁移 0051 · #114)。
+1. **决策不可被遗忘(正确性,不是功能)** —— **已建成**(`entities.type_source` · #114)。
`entities.type_source`(extracted / human / inferred),四条路径各有守卫:
类型消解取材、本体新类认领、抽取升格、改类落库(`actor` 有值即 `human`)。
diff --git a/docs/decisions/0005-alert-center.md b/docs/decisions/0005-alert-center.md
index d48a5242..08fe44fb 100644
--- a/docs/decisions/0005-alert-center.md
+++ b/docs/decisions/0005-alert-center.md
@@ -153,7 +153,7 @@ kb_id 有值 知识库级:解析失败、抽取失败、源同步失败
> 以及一个 `WHERE resolved_at IS NULL` 的部分唯一索引。随上面前两条决定一起作废。
> **不在这里重抄一份 schema** —— 一份和迁移不一致的草案比没有草案更坏。
-真实定义见 [`migrations/0039_alerts.sql`](../../migrations/0039_alerts.sql)。形状是:
+真实定义见 [`migrations/0017_alerts.sql`](../../migrations/0017_alerts.sql)。形状是:
- `alerts` 一次故障一行,写完不再改。`subject_id` 是**单列**不是数组 ——
一行只讲一个对象,`detail` 里存一份当时的名字,所以对象被删了这条告警仍然显示得出来。
diff --git a/docs/decisions/0007-who-decides-what-becomes-a-relation.md b/docs/decisions/0007-who-decides-what-becomes-a-relation.md
index 2c349ebe..5f398365 100644
--- a/docs/decisions/0007-who-decides-what-becomes-a-relation.md
+++ b/docs/decisions/0007-who-decides-what-becomes-a-relation.md
@@ -49,7 +49,7 @@
**六、没有日期的事实自称精确到日。** `valid_precision` 是 `NOT NULL DEFAULT 'day'`,
于是每一条两端都没有日期的事实都带着 `'day'` 落库(实测两个库分别 728 和 843 条活行)。
-→ 迁移 0045:可空 + `CHECK ((valid_from IS NULL AND valid_to IS NULL) = (valid_precision IS NULL))`。
+→ 改成可空 + 「有日期才有精度」的 CHECK(见 `facts.valid_from_precision`)。
## 决定
diff --git a/docs/decisions/0010-no-relation-is-no-relation.md b/docs/decisions/0010-no-relation-is-no-relation.md
index a26de038..8a8bba3b 100644
--- a/docs/decisions/0010-no-relation-is-no-relation.md
+++ b/docs/decisions/0010-no-relation-is-no-relation.md
@@ -1,6 +1,6 @@
# 「说不出是什么关系」不该是一个关系
-**状态**:已实施 · `facts.predicate_id` 改为可空 · 迁移 0052
+**状态**:已实施 · `facts.predicate_id` 改为可空
这是 [0009](0009-no-type-is-a-type.md) 在关系侧的孪生。那一篇讲的是
`concept`——一个"还没判出来"被写成了一个类;这一篇讲 `related_to`——
@@ -124,7 +124,7 @@
## 修订:删了数据,没删代码,七分钟后它长回来了
-**状态**:迁移 0053 · 与 0052 同一篇的直接后续
+**状态**:已实施 · 与上一节同一篇的直接后续
0052 只删了 `relation_types` 里的**行**。种子关系是**代码**——`graph.rs` 的
`DEFAULT_RELATION_TYPES` 里那一条还在,而 `ensure_default_ontology` 在建库、
diff --git a/migrations/0001_core.sql b/migrations/0001_core.sql
index e48fb07b..12bcc6df 100644
--- a/migrations/0001_core.sql
+++ b/migrations/0001_core.sql
@@ -11,12 +11,29 @@ CREATE TABLE organizations (
CREATE TABLE users (
id UUID PRIMARY KEY,
org_id UUID NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
- email TEXT NOT NULL UNIQUE,
+ -- **唯一性只约束在职账号**,见下面那个部分索引。停用之后地址就放开了——
+ -- 否则「停用」等于「这个邮箱永久报废」,同一个人回来都建不了新账号
+ email TEXT NOT NULL,
password_hash TEXT NOT NULL,
display_name TEXT NOT NULL,
- created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ -- 单租户部署里的系统管理员。第一个注册的人自动是(见 accounts.rs)
+ is_admin BOOLEAN NOT NULL DEFAULT FALSE,
+ -- **软删除,不是 DELETE。** 审计事件、合并日志、改类账本、口径确认的
+ -- `actor_id` 都指着这个人,而那些是审计材料——人走了仍然要能回答
+ -- 「当时是谁做的」。停用只断访问:`find_user_by_email` 与
+ -- `find_user_by_id` 各带一句 `deactivated_at IS NULL`,前者挡登录、
+ -- 后者挡已签发的 token(会话校验走它,所以停用立即生效)
+ deactivated_at TIMESTAMPTZ,
+ -- 谁停的。裸外键——停用者自己也可能被停用,而那条记录还得在
+ deactivated_by UUID REFERENCES users(id)
);
+-- email 唯一,**但只管在职的**。停用过的账号里可以有重复地址,
+-- 所以按 email 找人的查询必须带 `deactivated_at IS NULL`——它本来就要带
+-- (不然停用的人还能登录),这里让那一句同时也是正确性的保证。
+CREATE UNIQUE INDEX users_email_active_idx ON users (email) WHERE deactivated_at IS NULL;
+
CREATE TABLE workspaces (
id UUID PRIMARY KEY,
org_id UUID NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
@@ -42,7 +59,27 @@ CREATE TABLE knowledge_bases (
-- 部署的公共默认空间(workspace 里第一个建的库):永远 open、不可删(API 强制)
is_default BOOLEAN NOT NULL DEFAULT FALSE,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
- updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ -- open 库无矩阵记录时按部署角色行事,restricted 库仅 kb_members 里的成员
+ -- 可见(外人 NotFound)
+ visibility TEXT NOT NULL DEFAULT 'open'
+ CHECK (visibility IN ('open', 'restricted')),
+ -- 要不要替人扩本体。**显式开关而不是从行为里推断**:从前靠「本体有没有被
+ -- 碰过」来判断,推错了会很荒唐——在提案上点一次 Add 就永久关掉建议功能,
+ -- 因为那记了一条带操作人的本体动作。而且它一旦为假就永不再真,本体被冻结在
+ -- 第一批文档碰巧包含的词汇上,可来源是每天持续进文档的
+ auto_extend_ontology BOOLEAN NOT NULL DEFAULT TRUE,
+ -- **不是「系统语言」**(见 docs/decisions/0004)。界面语言在客户端,后端没有
+ -- locale。这一列管的是**语料的语言**:类的 description 逐字进抽取提示词,
+ -- 读者是正在读你文档的模型——描述与被判断的文本同语言,判断更稳。所以中国
+ -- 团队读英文技术文档时,界面要中文而这一列该是 'en',一个开关按不下去这两件事。
+ --
+ -- 取值收在 CHECK 里而不是应用层:这一列会被用来挑一张编译期常量表,写进一个
+ -- 没有对应表的值只会静默回落到英文,不报错——那种错最难查
+ ontology_lang TEXT NOT NULL DEFAULT 'en',
+ -- 默认库永远 open(规则在 API 强制,这里是 DB 级双保险)
+ CONSTRAINT kb_default_open CHECK (NOT is_default OR visibility = 'open'),
+ CONSTRAINT knowledge_bases_ontology_lang_chk CHECK (ontology_lang IN ('en', 'zh'))
);
CREATE INDEX knowledge_bases_workspace_idx ON knowledge_bases (workspace_id);
diff --git a/migrations/0002_ingest.sql b/migrations/0002_ingest.sql
index 972af16c..27ae83dd 100644
--- a/migrations/0002_ingest.sql
+++ b/migrations/0002_ingest.sql
@@ -1,11 +1,32 @@
-- 0002: 摄入管道(来源/文档/分块)+ 工作区 LLM 设置
+-- 来源即文件夹:source 是 Library 中的容器,挂着它摄入的文档,可定时同步。
+-- kind: upload(手动上传的虚拟归属,通常 source_id 为 NULL)| watch_folder | url | rss | api。
+-- 设计见 docs/DESIGN.md §4 摄入渠道
CREATE TABLE sources (
id UUID PRIMARY KEY,
kb_id UUID NOT NULL REFERENCES knowledge_bases(id) ON DELETE CASCADE,
kind TEXT NOT NULL DEFAULT 'upload',
name TEXT NOT NULL,
- created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ -- 各种源自己的配置(url 列表、rss 地址、选择器…)。形状按 kind 变,
+ -- 所以是 JSONB 而不是一堆稀疏列
+ config JSONB NOT NULL DEFAULT '{}',
+ -- NULL = 仅手动同步
+ sync_interval_minutes INTEGER,
+ last_sync_at TIMESTAMPTZ,
+ last_sync_status TEXT NOT NULL DEFAULT 'never'
+ CHECK (last_sync_status IN ('never', 'queued', 'running', 'ok', 'failed')),
+ last_sync_error TEXT,
+ last_sync_added INTEGER NOT NULL DEFAULT 0,
+ icon TEXT,
+ -- cron 表达式(标准 5 段),与 sync_interval_minutes 互斥。
+ -- UI 用可视化选择器构建,Advanced 模式才暴露原生表达式
+ sync_cron TEXT,
+ -- **明文存,不是哈希。** 自部署威胁模型下「只看一次」是自找麻烦:
+ -- 改存明文随时可查(Editor 权限专用端点)。DB 失守时文档本体早已泄露,
+ -- 密钥哈希化没有额外收益;Rotate 保留应对泄露
+ ingest_token TEXT
);
CREATE INDEX sources_kb_idx ON sources (kb_id);
@@ -27,9 +48,29 @@ CREATE TABLE documents (
text_len INT NOT NULL DEFAULT 0,
chunk_count INT NOT NULL DEFAULT 0,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
- updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ -- 图谱抽取状态。**与摄入管道状态分离**:两段式可用,解析完就能检索,
+ -- 抽取慢慢跑
+ graph_status TEXT NOT NULL DEFAULT 'none'
+ CHECK (graph_status IN ('none', 'queued', 'extracting', 'done', 'failed')),
+ -- 文档标签(过滤与批量组织;不做实体文件夹)
+ tags TEXT[] NOT NULL DEFAULT '{}',
+ -- 来源内的逻辑身份(watch_folder 相对路径 / url / rss guid / api external_id)。
+ -- 摄入据此做三路判定:新增 / 变更 / 未变——内容变了原地替换文档而不是堆积
+ -- 新文档,旧版本记入 document_versions
+ external_key TEXT,
+ -- 目录里消失的文件打这个戳。**默认保留不删**
+ missing_since TIMESTAMPTZ,
+ -- 抽取失败的原因。独立成列而不是复用 error:那一列归解析管道所有
+ -- (set_status 会清空它),互不干扰
+ graph_error TEXT,
+ -- 抽取任务的所有权凭证。重抽时自增即「解雇」正在跑的那个任务:它每处理完
+ -- 一个分块回读一次,发现 epoch 变了就安静退出,把文档让给新任务。
+ -- 单靠 graph_status 判断不可靠——接手者会把状态写回 extracting,旧任务无从分辨
+ extract_epoch INT NOT NULL DEFAULT 0
);
CREATE INDEX documents_kb_idx ON documents (kb_id, created_at DESC);
+CREATE INDEX documents_tags_idx ON documents USING gin (tags);
CREATE UNIQUE INDEX documents_kb_sha_idx ON documents (kb_id, sha256);
CREATE TABLE chunks (
@@ -68,3 +109,17 @@ CREATE TABLE llm_settings (
embed_dim INT,
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
+
+CREATE UNIQUE INDEX documents_source_key_idx
+ ON documents (source_id, external_key) WHERE external_key IS NOT NULL;
+
+-- 版本回放的原料(文件 blob 内容寻址,不删)
+CREATE TABLE document_versions (
+ id UUID PRIMARY KEY,
+ document_id UUID NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+ version INTEGER NOT NULL,
+ sha256 TEXT NOT NULL,
+ size_bytes BIGINT NOT NULL DEFAULT 0,
+ ingested_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ UNIQUE (document_id, version)
+);
diff --git a/migrations/0003_graph.sql b/migrations/0003_graph.sql
new file mode 100644
index 00000000..514979f2
--- /dev/null
+++ b/migrations/0003_graph.sql
@@ -0,0 +1,347 @@
+-- 0004: 图谱层 —— 轻量本体 + 实体 + 双时态事实账本 + 证据链
+-- 设计见 docs/DESIGN.md §3:事实 append-only;抽取错误设 invalidated_at,事实变化闭合 valid_to。
+
+-- 类。**两个向量不是冗余**:类型消解发两种查询(见 `type_resolution.rs`),
+-- 一种是模型给的短说法(`district. place`),一种是整段画像。此前两种比的是
+-- 同一批 `label + description` 向量——查询分了两种形状,文档只有一种,于是短
+-- 查询被同义反复的类接管(`Park\nA park.` 这样一行的类,赢在长度而不是语义:
+-- 被检索出来的类原文长度中位数 44,而全体中位数 89)。
+--
+-- 「短的那一侧距离系统性地更小」这条规律本仓库栽过四次(跨实体不可比、两路之间
+-- 不可比、同一路两个查询之间不可比、空描述的悬空类占便宜),前四次修的都是查询
+-- 一侧,这一次是文档一侧:**两种查询就该有两份文档**,短对短、长对长。
+--
+-- 维度不定:跟 chunks.embedding 一样随工作区所选模型走,所以不建 HNSW,顺扫。
+-- 本体行数以千计,顺扫完全够。
+CREATE TABLE entity_types (
+ id UUID PRIMARY KEY,
+ kb_id UUID NOT NULL REFERENCES knowledge_bases(id) ON DELETE CASCADE,
+ key TEXT NOT NULL,
+ label TEXT NOT NULL,
+ color TEXT NOT NULL DEFAULT '#64748b',
+ builtin BOOLEAN NOT NULL DEFAULT FALSE,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ -- 图谱节点按类型的形状渲染(此前 organization/product = 方形是前端写死的)
+ shape TEXT NOT NULL DEFAULT 'circle' CHECK (shape IN ('circle', 'square')),
+ -- 不是给人看的装饰,是喂给抽取 prompt 的语义指引("Event: 有明确时间点的
+ -- 事件,如发布、收购、会议"),直接影响抽取质量
+ description TEXT NOT NULL DEFAULT '',
+ -- IRI 是全局身份,key 是给模型读的短标签(见 0001 P2「IRI 与 key 的分工」)。
+ -- 重导入按 IRI 匹配已有行——按 key 匹配会因为上游改了 rdfs:label 导致 key
+ -- 变化而把同一个类当成新类建出来,实体全留在孤儿上
+ iri TEXT,
+ -- 长文档:label + description
+ embedding vector,
+ -- **存「当时嵌的是什么」而不是一个时间戳。** 时间戳只能回答「嵌过没有」,
+ -- 回答不了「嵌的还是不是现在这段文字」——描述改了、模型换了,向量就是陈的,
+ -- 而时间戳看不出来。存原文与模型名,填充任务一比对就知道该重嵌谁,也就不必
+ -- 去每一个改描述的写入点挂钩子(漏一个就悄悄烂掉)
+ embedded_text text,
+ embedded_model text,
+ -- 短文档:只嵌 label
+ label_embedding vector,
+ label_embedded_text text,
+ label_embedded_model text,
+ UNIQUE (kb_id, key)
+);
+CREATE UNIQUE INDEX entity_types_iri_idx ON entity_types (kb_id, iri) WHERE iri IS NOT NULL;
+
+CREATE TABLE relation_types (
+ id UUID PRIMARY KEY,
+ kb_id UUID NOT NULL REFERENCES knowledge_bases(id) ON DELETE CASCADE,
+ key TEXT NOT NULL,
+ label TEXT NOT NULL,
+ -- 时间语义:state 状态型(区间) / event 事件型(时点) / eternal 永恒型(无时间)
+ temporal TEXT NOT NULL DEFAULT 'state' CHECK (temporal IN ('state', 'event', 'eternal')),
+ -- 基数唯一(同一时刻单值),时态冲突检测(自动闭合 valid_to)的依据:
+ -- functional = 主语侧唯一;inverse_functional = 宾语侧唯一(一个项目一个 leader)
+ functional BOOLEAN NOT NULL DEFAULT FALSE,
+ inverse_functional BOOLEAN NOT NULL DEFAULT FALSE,
+ builtin BOOLEAN NOT NULL DEFAULT FALSE,
+ -- 属性系统:属性 = 值域为字面量的关系(RDF datatype property),一表两用。
+ -- 属性值走 facts.object_value 通道,时态/证据/Review 全套复用
+ kind TEXT NOT NULL DEFAULT 'relation' CHECK (kind IN ('relation', 'attribute')),
+ datatype TEXT CHECK (datatype IN ('text', 'number', 'date', 'bool')),
+ unit TEXT,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ description TEXT NOT NULL DEFAULT '',
+ iri TEXT,
+ embedding vector,
+ embedded_text text,
+ embedded_model text,
+ -- 其余属性公理,跟 `functional` / `inverse_functional` 同族——那两个先落库
+ -- 而已。**默认 false 而不是 NULL**:OWL 是开放世界,但一致性检查只能按写
+ -- 下来的判,「没声明」与「声明为否」后果相同(都不构成报矛盾的依据),
+ -- 不必用三态去区分一个不影响行为的差别。
+ --
+ -- **列名带 is_ 前缀不是风格洁癖**:`symmetric` 与 `asymmetric` 都是 Postgres
+ -- 保留字(`BETWEEN SYMMETRIC`),裸用会在建表那一行就报语法错。加引号能绕
+ -- 过去,但那要求之后每一处写这两列的 SQL 都记得加——漏一处就是运行时才炸
+ is_transitive BOOLEAN NOT NULL DEFAULT FALSE,
+ is_symmetric BOOLEAN NOT NULL DEFAULT FALSE,
+ is_asymmetric BOOLEAN NOT NULL DEFAULT FALSE,
+ is_irreflexive BOOLEAN NOT NULL DEFAULT FALSE,
+ UNIQUE (kb_id, key)
+);
+CREATE UNIQUE INDEX relation_types_iri_idx ON relation_types (kb_id, iri) WHERE iri IS NOT NULL;
+
+-- domain / range 是**关联表而不是列**:OWL 里一个属性有多个 rdfs:domain 是常态
+-- (works_at 的主语可能是 person 也可能是 organization),单列表达不了,导入时
+-- 只能挑一个丢一个(FOAF 里就有这样的属性)。也不留一个「主 domain」列——那是
+-- 同一件事有两处记录,而两处记录迟早分叉(预览与落库各判一次 key 冲突、结果
+-- 预览说了假话,这个坑已经踩过)。一处权威,读的人不必猜该信哪个。
+--
+-- range 只服务对象属性:数据属性的 range 是字面量类型,落在 relation_types.datatype 上。
+CREATE TABLE relation_type_domains (
+ relation_type_id UUID NOT NULL REFERENCES relation_types(id) ON DELETE CASCADE,
+ entity_type_id UUID NOT NULL REFERENCES entity_types(id) ON DELETE CASCADE,
+ PRIMARY KEY (relation_type_id, entity_type_id)
+);
+
+CREATE TABLE relation_type_ranges (
+ relation_type_id UUID NOT NULL REFERENCES relation_types(id) ON DELETE CASCADE,
+ entity_type_id UUID NOT NULL REFERENCES entity_types(id) ON DELETE CASCADE,
+ PRIMARY KEY (relation_type_id, entity_type_id)
+);
+
+-- 反向查:本体页要按类列出它的属性,抽取要按类筛可用属性。
+-- 主键覆盖了正向,反向得自己建
+CREATE INDEX relation_type_domains_entity_idx ON relation_type_domains (entity_type_id);
+CREATE INDEX relation_type_ranges_entity_idx ON relation_type_ranges (entity_type_id);
+
+-- subClassOf。**一个类可以有多个父类**,这在真实词汇表里是常态:FOAF 的 Person
+-- 同时是 foaf:Agent 与 geo:SpatialThing——两个方向,不是同一根链上的祖孙。只认
+-- 一个父类的话,domain 落在另一支上的属性判定不过(latitude 的 domain 是
+-- SpatialThing,而 person 只挂在 agent 下,那条事实抽出来了却被挡掉)。
+--
+-- **is_primary 不是冗余**:左栏按树展示,一个类只能画在一处,而「画在哪一支下」
+-- 是 subClassOf 集合本身答不出的问题——它是多出来的一条信息,不是同一件事记两遍。
+CREATE TABLE entity_type_parents (
+ child_id UUID NOT NULL REFERENCES entity_types(id) ON DELETE CASCADE,
+ parent_id UUID NOT NULL REFERENCES entity_types(id) ON DELETE CASCADE,
+ -- 左栏画树时走这一支。不参与语义,只管展示
+ is_primary BOOLEAN NOT NULL DEFAULT FALSE,
+ PRIMARY KEY (child_id, parent_id),
+ -- 自环在这里就挡掉;更长的环由应用在写入前查(SQL 拦不住 A→B→A)
+ CONSTRAINT entity_type_parents_no_self CHECK (child_id <> parent_id)
+);
+
+-- 每个类至多一个主父
+CREATE UNIQUE INDEX entity_type_parents_primary_idx
+ ON entity_type_parents (child_id) WHERE is_primary;
+
+-- 反向查:左栏要按父类找子类,域判定要沿父链上溯
+CREATE INDEX entity_type_parents_parent_idx ON entity_type_parents (parent_id);
+
+-- 类互斥。**存成一张表而不是数组列**:要查的问题是「A 与 B 互斥吗」,那是一次
+-- 点查;数组列查起来要么全表扫要么建 GIN,而这里的语义就是一条边。
+CREATE TABLE entity_type_disjoint (
+ kb_id UUID NOT NULL REFERENCES knowledge_bases(id) ON DELETE CASCADE,
+ a_id UUID NOT NULL REFERENCES entity_types(id) ON DELETE CASCADE,
+ b_id UUID NOT NULL REFERENCES entity_types(id) ON DELETE CASCADE,
+ -- 两个方向各存一行(导入侧已经把公理的对称性展开了)。主键因此天然去重,
+ -- 而查询不必关心调用方从哪一头问
+ PRIMARY KEY (kb_id, a_id, b_id),
+ -- 自己跟自己互斥是无意义的声明,挡在门口比留着让检查去猜好
+ CHECK (a_id <> b_id)
+);
+
+-- 「跟这个类互斥的有哪些」是唯一的查法(一致性检查拿实体的类去问)
+CREATE INDEX entity_type_disjoint_a_idx ON entity_type_disjoint (kb_id, a_id);
+
+CREATE TABLE entities (
+ id UUID PRIMARY KEY,
+ kb_id UUID NOT NULL REFERENCES knowledge_bases(id) ON DELETE CASCADE,
+ -- **可以为空**,见 docs/decisions/0009:「还没判出来」不是一个类。
+ -- 从前它是一行叫 concept 的哨兵,而哨兵有名字,有名字就会撞——SKOS 的
+ -- skos:Concept 派生出的 key 正是 concept,导入逻辑「占位者没有 IRI 就认领它」
+ -- 会让它接管哨兵,所有未分类的实体一夜之间变成正经的 skos:Concept。
+ -- 不是撞名被跳过,是语义被静默改写。NULL 没有名字,撞不着;也忘不掉——
+ -- 漏过滤一个哨兵不会有任何提示,漏处理一个 NULL 会当场报出来
+ type_id UUID REFERENCES entity_types(id) ON DELETE RESTRICT,
+ canonical_name TEXT NOT NULL,
+ aliases TEXT[] NOT NULL DEFAULT '{}',
+ attrs JSONB NOT NULL DEFAULT '{}',
+ -- 被合并后指向存活实体(合并可回滚,P2 后续)
+ merged_into UUID REFERENCES entities(id),
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ -- 实体画像:证据分块向量的增量质心(上下文相似度判定用;
+ -- 复用摄入阶段已算好的 chunk embedding)
+ profile_embedding vector,
+ profile_n INTEGER NOT NULL DEFAULT 0,
+ -- 同名并存时的展示消歧后缀(如 张三 · Platform Engineering)
+ disambiguator TEXT,
+ -- 模型提议的类型:**本体装不下时它说的那个词**。不记的话,想加 model 类时
+ -- 找不出那些实体——它们混在未分类里,只能整库重抽
+ proposed_type TEXT,
+ -- 模型对这个实体自己的说法:它认为这最具体是个什么。
+ --
+ -- **跟 proposed_type 不能合用一列**:那一列的含义是「模型要的东西本体里没有」,
+ -- 本体增长回路靠它的稀有性设门槛,每个实体都填的话回路会给每一个实体提议建新类。
+ --
+ -- 为什么需要它:清单里总有个「差不多」的。本体有 product,模型觉得够用就选了,
+ -- 心里那个「向量数据库软件」就此丢失。而类型消解最需要的正是这个名字:
+ -- 短名字对短标签,比拿一段中文散文去匹配 schema.org 的 "A software application." 近得多
+ specific_type text,
+ -- **这个类型是怎么来的。** 保护要事前——`entity_retypes` 记得住「谁改的」,
+ -- 但那是事后的账;实体身上得有一位说明有没有人拍过板,否则每一条读路径都
+ -- 只能看见 `type_id`。漏在类型消解那条路上:人工定成 `organization` 的实体,
+ -- 只要 `organization` 有子类,下一轮消解照样把它拿去重判。
+ --
+ -- 0009 之后还多了一种情形:「没有类型」现在可能是**人的决定**——他看过这个
+ -- 实体,认为本体里没有合适的类。而 `type_id IS NULL` 分不出「还没判」和
+ -- 「人判了,就是没有」,于是下一次抽取会给它安一个类型。
+ --
+ -- extracted 抽取判出来的(`resolve_type_drift` 的升格)
+ -- inferred 引擎裁决的(类型消解、本体长出新类后的认领)
+ -- human 人拍板的(实体面板直改、审核队列里点批准)
+ --
+ -- `inferred` 与 `extracted` 分开而不是合成一个「非人」:它们的可信度不同,
+ -- 将来若要「引擎可以改引擎的,但不能改抽取的」,判据现成
+ type_source TEXT NOT NULL DEFAULT 'extracted'
+ CHECK (type_source IN ('extracted', 'human', 'inferred'))
+);
+-- **不唯一**:名字不是身份(0001 P0 的两个张伟),同名实体允许并存,
+-- 这里只做候选召回。
+--
+-- 0009 之后 type_id 还可能是 NULL,而 Postgres 里 NULL <> NULL——两个都没类型的
+-- 同名实体更不会被拦住。这是要的行为:未分类时我们对它们是不是同一个东西
+-- 知道得更少,更没有理由合并
+CREATE INDEX entities_kb_type_name_idx
+ ON entities (kb_id, type_id, lower(canonical_name)) WHERE merged_into IS NULL;
+CREATE INDEX entities_kb_idx ON entities (kb_id);
+-- 跨类型同名召回(类型漂移处理):上面那个索引带 type_id 前缀,跨类型查询用不上
+CREATE INDEX entities_kb_name_idx
+ ON entities (kb_id, lower(canonical_name)) WHERE merged_into IS NULL;
+
+-- 事实账本:SPO + 双时间轴(append-only,永不 DELETE)
+CREATE TABLE facts (
+ id UUID PRIMARY KEY,
+ kb_id UUID NOT NULL REFERENCES knowledge_bases(id) ON DELETE CASCADE,
+ subject_id UUID NOT NULL REFERENCES entities(id) ON DELETE CASCADE,
+ -- **可以为空**:「说不出是什么关系」不该是一种关系(与 0009 对 concept 做的
+ -- 事同构)。从前它是一行叫 related_to 的 builtin 关系,在本体页上跟真关系
+ -- 并排列着——而它编码的是「抽取器抽到了一条边,但本体里没有对应的关系」,
+ -- 那是控制流,不是词汇。
+ --
+ -- 删掉它一个字的信息都不丢:原意一直存在证据的 `proposed_predicate` 里,
+ -- 被那行假词汇盖着而已。删掉之后信息反而更多——从前统统显示「有关联」,
+ -- 之后各自显示原文说的 acquired / runs_on / sued(见 fact_surface_predicate)
+ predicate_id UUID REFERENCES relation_types(id) ON DELETE CASCADE,
+ object_id UUID REFERENCES entities(id) ON DELETE CASCADE,
+ object_value JSONB,
+ valid_from TIMESTAMPTZ,
+ valid_to TIMESTAMPTZ,
+ -- **两端各记各的精度,且没日期就没精度。**
+ --
+ -- 从前是一个 `valid_precision NOT NULL DEFAULT 'day'`,于是根本没有日期的
+ -- 事实也带着 'day' 落库——账本在无知的地方填了一个确定的值,任何按这个字段
+ -- 渲染「精确到日」的界面都会照着念。默认值本身就是那条 bug:它让「没量过」
+ -- 和「量到日」长得一模一样。
+ --
+ -- 一个列描述两个端点也不行:只有 valid_to 的事实(「直到 2023 年」这类),
+ -- 那个列名写着 from、描述的却是 to。
+ valid_from_precision TEXT,
+ recorded_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ invalidated_at TIMESTAMPTZ,
+ confidence REAL NOT NULL DEFAULT 1.0,
+ derived_by_rule UUID,
+ supersedes UUID REFERENCES facts(id),
+ -- 结束端。多一个 'unknown',因为账本原本说不出「结束了,但不知道哪天」:
+ -- `valid_to IS NULL` 一直承载两个意思,于是 "former CEO of Weta Digital"
+ -- 这句——**结束是原文明说的,日期是原文没给的**——只能写成 null,然后被
+ -- 系统读成「至今仍是」,图会理直气壮地断言一件原文说已经结束的事。
+ --
+ -- 仍在持续 valid_to IS NULL valid_to_precision IS NULL
+ -- 结束了,不知哪天 valid_to IS NULL valid_to_precision = 'unknown'
+ -- 2023 年结束 valid_to = … valid_to_precision = 'year'
+ --
+ -- **不采用「把文档日期填进 valid_to 当上界」那种做法**(教科书里的
+ -- indeterminate instant):那会在列里放一个看起来确定的时间戳,每个读者都得
+ -- 先查精度才敢用它,而这个产品卖的正是不骗人
+ valid_to_precision text,
+ CHECK (object_id IS NOT NULL OR object_value IS NOT NULL),
+ -- 起始端没有 unknown——「开始了但不知道何时」与「不知道有没有开始」在这个
+ -- 账本里不可区分,硬加一个状态只会让读者猜
+ CONSTRAINT facts_from_precision_matches_date
+ CHECK ((valid_from IS NULL) = (valid_from_precision IS NULL)),
+ -- 那句 `IS NOT NULL` 不是冗余的。少了它,`valid_to` 有日期而精度为 NULL 的
+ -- 行会**被放行**:`NULL IN ('year',…)` 求值是 NULL,`TRUE AND NULL` 是 NULL,
+ -- `NULL OR FALSE` 还是 NULL,而 CHECK 约束遇到 NULL 判通过。三值逻辑在这里
+ -- 是静默的
+ CONSTRAINT facts_to_precision_matches_date
+ CHECK (
+ (valid_to IS NOT NULL AND valid_to_precision IS NOT NULL
+ AND valid_to_precision IN ('year', 'month', 'day'))
+ OR (valid_to IS NULL AND (valid_to_precision IS NULL OR valid_to_precision = 'unknown'))
+ )
+);
+-- 热路径部分索引:作废行不进索引(账本边界与清理,DESIGN.md §3.1)
+CREATE INDEX facts_live_subject_idx ON facts (kb_id, subject_id) WHERE invalidated_at IS NULL;
+CREATE INDEX facts_live_object_idx ON facts (kb_id, object_id) WHERE invalidated_at IS NULL;
+CREATE INDEX facts_live_time_idx ON facts (kb_id, valid_from, valid_to) WHERE invalidated_at IS NULL;
+-- 时态冲突检测的不变量点查:主语侧与宾语侧各一(开放期 + 未作废)
+CREATE INDEX facts_open_pair_idx ON facts (kb_id, subject_id, predicate_id)
+ WHERE valid_to IS NULL AND invalidated_at IS NULL;
+CREATE INDEX facts_open_obj_pair_idx ON facts (kb_id, object_id, predicate_id)
+ WHERE valid_to IS NULL AND invalidated_at IS NULL;
+-- 认知轴。上面那几个索引全在世界轴上、且都只认活行,服务的是"某时刻什么为真";
+-- 这两个服务的是另一个问题——**什么时候写进来的、什么时候被推翻的**
+--("上个季度我们的认知有哪些变化",见 chat 的 changes 工具)。
+-- 作废那条是部分索引且条件取反:活行的 invalidated_at 全是 NULL,
+-- 把它们收进来只会让索引跟表一样大,而被推翻的事实天然是少数
+CREATE INDEX facts_recorded_idx ON facts (kb_id, recorded_at DESC);
+CREATE INDEX facts_invalidated_idx ON facts (kb_id, invalidated_at DESC)
+ WHERE invalidated_at IS NOT NULL;
+
+-- 证据链:事实 ↔ 原文分块(溯源一等公民)
+CREATE TABLE fact_evidence (
+ fact_id UUID NOT NULL REFERENCES facts(id) ON DELETE CASCADE,
+ chunk_id UUID NOT NULL REFERENCES chunks(id) ON DELETE CASCADE,
+ quote TEXT,
+ -- 证据出处版本:出自哪份文档的第几版(版本对账与"证据过期"展示的判定依据)
+ document_id UUID REFERENCES documents(id) ON DELETE CASCADE,
+ doc_version INT,
+ -- 模型原话。**落在证据上而不是事实上**:事实按 (kb, 主, 谓, 宾) 去重,
+ -- 甲块说 "runs on"、乙块说 "optimized for" 会并成同一行,放事实上就是
+ -- 先写者胜、其余静默丢弃。证据是每分块一行,粒度对,而且它已经带着 quote
+ -- (该块的原文佐证),原话是同一种东西:每次观察的原始形态
+ proposed_predicate TEXT,
+ PRIMARY KEY (fact_id, chunk_id)
+);
+
+
+-- 时态冲突(S3):自动闭合拿不准的进审,人裁 close / keep / reject_new
+CREATE TABLE fact_conflicts (
+ id UUID PRIMARY KEY,
+ kb_id UUID NOT NULL REFERENCES knowledge_bases(id) ON DELETE CASCADE,
+ old_fact_id UUID NOT NULL REFERENCES facts(id) ON DELETE CASCADE,
+ new_fact_id UUID NOT NULL REFERENCES facts(id) ON DELETE CASCADE,
+ -- no_time | simultaneous | low_confidence
+ reason TEXT NOT NULL,
+ status TEXT NOT NULL DEFAULT 'open' CHECK (status IN ('open', 'resolved')),
+ -- closed | kept_both | rejected_new
+ resolution TEXT,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ resolved_at TIMESTAMPTZ,
+ UNIQUE (old_fact_id, new_fact_id)
+);
+CREATE INDEX fact_conflicts_open_idx ON fact_conflicts (kb_id) WHERE status = 'open';
+
+-- 没有谓词的事实**显示什么**。
+--
+-- 做成函数而不是在每条读查询里塞一段子查询:读事实的路径有六条以上(图的边、
+-- 实体面板、变更历史、低置信审核、文档产出、消解画像),六份同样的 SQL 迟早
+-- 分叉,而分叉在这里的后果是同一条边在不同页面上叫不同的名字。
+--
+-- **确定性**:出现次数相同时按字典序,所以同一条事实每次显示同一个词。
+CREATE FUNCTION fact_surface_predicate(fact uuid) RETURNS text
+LANGUAGE sql STABLE AS $$
+ SELECT e.proposed_predicate
+ FROM fact_evidence e
+ WHERE e.fact_id = fact AND e.proposed_predicate IS NOT NULL
+ GROUP BY e.proposed_predicate
+ ORDER BY count(*) DESC, e.proposed_predicate
+ LIMIT 1
+$$;
diff --git a/migrations/0003_single_tenant.sql b/migrations/0003_single_tenant.sql
deleted file mode 100644
index 94ee4973..00000000
--- a/migrations/0003_single_tenant.sql
+++ /dev/null
@@ -1,9 +0,0 @@
--- 0003: 单租户部署模型
--- 一次部署 = 一个组织;首个注册用户为系统管理员,后续用户加入同一组织。
--- organizations 表与 org_id 列保留为内部管道(永远单行),为将来可能的托管版留门。
-
-ALTER TABLE users ADD COLUMN is_admin BOOLEAN NOT NULL DEFAULT FALSE;
-
--- 存量数据:最早注册的用户视为系统管理员
-UPDATE users SET is_admin = TRUE
-WHERE id = (SELECT id FROM users ORDER BY created_at LIMIT 1);
diff --git a/migrations/0004_graph.sql b/migrations/0004_graph.sql
deleted file mode 100644
index a2387e6d..00000000
--- a/migrations/0004_graph.sql
+++ /dev/null
@@ -1,123 +0,0 @@
--- 0004: 图谱层 —— 轻量本体 + 实体 + 双时态事实账本 + 证据链
--- 设计见 docs/DESIGN.md §3:事实 append-only;抽取错误设 invalidated_at,事实变化闭合 valid_to。
-
-CREATE TABLE entity_types (
- id UUID PRIMARY KEY,
- kb_id UUID NOT NULL REFERENCES knowledge_bases(id) ON DELETE CASCADE,
- key TEXT NOT NULL,
- label TEXT NOT NULL,
- color TEXT NOT NULL DEFAULT '#64748b',
- builtin BOOLEAN NOT NULL DEFAULT FALSE,
- created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
- UNIQUE (kb_id, key)
-);
-
-CREATE TABLE relation_types (
- id UUID PRIMARY KEY,
- kb_id UUID NOT NULL REFERENCES knowledge_bases(id) ON DELETE CASCADE,
- key TEXT NOT NULL,
- label TEXT NOT NULL,
- -- 时间语义:state 状态型(区间) / event 事件型(时点) / eternal 永恒型(无时间)
- temporal TEXT NOT NULL DEFAULT 'state' CHECK (temporal IN ('state', 'event', 'eternal')),
- -- 基数唯一(同一时刻单值),时态冲突检测(自动闭合 valid_to)的依据:
- -- functional = 主语侧唯一;inverse_functional = 宾语侧唯一(一个项目一个 leader)
- functional BOOLEAN NOT NULL DEFAULT FALSE,
- inverse_functional BOOLEAN NOT NULL DEFAULT FALSE,
- builtin BOOLEAN NOT NULL DEFAULT FALSE,
- -- 属性系统:属性 = 值域为字面量的关系(RDF datatype property),一表两用。
- -- 属性值走 facts.object_value 通道,时态/证据/Review 全套复用
- kind TEXT NOT NULL DEFAULT 'relation' CHECK (kind IN ('relation', 'attribute')),
- -- 属性挂在哪个类下(attribute 必填;类删则属性随删)
- domain_type_id UUID REFERENCES entity_types(id) ON DELETE CASCADE,
- datatype TEXT CHECK (datatype IN ('text', 'number', 'date', 'bool')),
- unit TEXT,
- created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
- UNIQUE (kb_id, key)
-);
-
-CREATE TABLE entities (
- id UUID PRIMARY KEY,
- kb_id UUID NOT NULL REFERENCES knowledge_bases(id) ON DELETE CASCADE,
- type_id UUID NOT NULL REFERENCES entity_types(id) ON DELETE RESTRICT,
- canonical_name TEXT NOT NULL,
- aliases TEXT[] NOT NULL DEFAULT '{}',
- attrs JSONB NOT NULL DEFAULT '{}',
- -- 被合并后指向存活实体(合并可回滚,P2 后续)
- merged_into UUID REFERENCES entities(id),
- created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
- updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
-);
-CREATE UNIQUE INDEX entities_kb_type_name_idx
- ON entities (kb_id, type_id, lower(canonical_name)) WHERE merged_into IS NULL;
-CREATE INDEX entities_kb_idx ON entities (kb_id);
--- 跨类型同名召回(类型漂移处理):上面的唯一索引带 type_id 前缀,跨类型查询用不上
-CREATE INDEX entities_kb_name_idx
- ON entities (kb_id, lower(canonical_name)) WHERE merged_into IS NULL;
-
--- 事实账本:SPO + 双时间轴(append-only,永不 DELETE)
-CREATE TABLE facts (
- id UUID PRIMARY KEY,
- kb_id UUID NOT NULL REFERENCES knowledge_bases(id) ON DELETE CASCADE,
- subject_id UUID NOT NULL REFERENCES entities(id) ON DELETE CASCADE,
- predicate_id UUID NOT NULL REFERENCES relation_types(id) ON DELETE CASCADE,
- object_id UUID REFERENCES entities(id) ON DELETE CASCADE,
- object_value JSONB,
- valid_from TIMESTAMPTZ,
- valid_to TIMESTAMPTZ,
- valid_precision TEXT NOT NULL DEFAULT 'day',
- recorded_at TIMESTAMPTZ NOT NULL DEFAULT now(),
- invalidated_at TIMESTAMPTZ,
- confidence REAL NOT NULL DEFAULT 1.0,
- derived_by_rule UUID,
- supersedes UUID REFERENCES facts(id),
- CHECK (object_id IS NOT NULL OR object_value IS NOT NULL)
-);
--- 热路径部分索引:作废行不进索引(账本边界与清理,DESIGN.md §3.1)
-CREATE INDEX facts_live_subject_idx ON facts (kb_id, subject_id) WHERE invalidated_at IS NULL;
-CREATE INDEX facts_live_object_idx ON facts (kb_id, object_id) WHERE invalidated_at IS NULL;
-CREATE INDEX facts_live_time_idx ON facts (kb_id, valid_from, valid_to) WHERE invalidated_at IS NULL;
--- 时态冲突检测的不变量点查:主语侧与宾语侧各一(开放期 + 未作废)
-CREATE INDEX facts_open_pair_idx ON facts (kb_id, subject_id, predicate_id)
- WHERE valid_to IS NULL AND invalidated_at IS NULL;
-CREATE INDEX facts_open_obj_pair_idx ON facts (kb_id, object_id, predicate_id)
- WHERE valid_to IS NULL AND invalidated_at IS NULL;
--- 认知轴。上面那几个索引全在世界轴上、且都只认活行,服务的是"某时刻什么为真";
--- 这两个服务的是另一个问题——**什么时候写进来的、什么时候被推翻的**
---("上个季度我们的认知有哪些变化",见 chat 的 changes 工具)。
--- 作废那条是部分索引且条件取反:活行的 invalidated_at 全是 NULL,
--- 把它们收进来只会让索引跟表一样大,而被推翻的事实天然是少数
-CREATE INDEX facts_recorded_idx ON facts (kb_id, recorded_at DESC);
-CREATE INDEX facts_invalidated_idx ON facts (kb_id, invalidated_at DESC)
- WHERE invalidated_at IS NOT NULL;
-
--- 证据链:事实 ↔ 原文分块(溯源一等公民)
-CREATE TABLE fact_evidence (
- fact_id UUID NOT NULL REFERENCES facts(id) ON DELETE CASCADE,
- chunk_id UUID NOT NULL REFERENCES chunks(id) ON DELETE CASCADE,
- quote TEXT,
- -- 证据出处版本:出自哪份文档的第几版(版本对账与"证据过期"展示的判定依据)
- document_id UUID REFERENCES documents(id) ON DELETE CASCADE,
- doc_version INT,
- PRIMARY KEY (fact_id, chunk_id)
-);
-
--- 文档的图谱抽取状态(与摄入管道状态分离:两段式可用)
-ALTER TABLE documents ADD COLUMN graph_status TEXT NOT NULL DEFAULT 'none'
- CHECK (graph_status IN ('none', 'queued', 'extracting', 'done', 'failed'));
-
--- 时态冲突(S3):自动闭合拿不准的进审,人裁 close / keep / reject_new
-CREATE TABLE fact_conflicts (
- id UUID PRIMARY KEY,
- kb_id UUID NOT NULL REFERENCES knowledge_bases(id) ON DELETE CASCADE,
- old_fact_id UUID NOT NULL REFERENCES facts(id) ON DELETE CASCADE,
- new_fact_id UUID NOT NULL REFERENCES facts(id) ON DELETE CASCADE,
- -- no_time | simultaneous | low_confidence
- reason TEXT NOT NULL,
- status TEXT NOT NULL DEFAULT 'open' CHECK (status IN ('open', 'resolved')),
- -- closed | kept_both | rejected_new
- resolution TEXT,
- created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
- resolved_at TIMESTAMPTZ,
- UNIQUE (old_fact_id, new_fact_id)
-);
-CREATE INDEX fact_conflicts_open_idx ON fact_conflicts (kb_id) WHERE status = 'open';
diff --git a/migrations/0004_ontology.sql b/migrations/0004_ontology.sql
new file mode 100644
index 00000000..cfaf31f4
--- /dev/null
+++ b/migrations/0004_ontology.sql
@@ -0,0 +1,20 @@
+-- 抽取未匹配统计:LLM 建议流的信号源
+
+-- 抽取过程中命中白名单之外的类型/关系:不是垃圾,是本体扩展的信号
+CREATE TABLE ontology_misses (
+ kb_id UUID NOT NULL REFERENCES knowledge_bases(id) ON DELETE CASCADE,
+ -- attribute_type 与 relation_type 分开:词表外的谓词带着字面值时(
+ -- `founding_date: "2015"`),缺的是一个属性而不是一个关系,记错了会让
+ -- 本体提案去建一条关系
+ kind TEXT NOT NULL
+ CHECK (kind IN ('entity_type', 'relation_type', 'attribute_type')),
+ key TEXT NOT NULL,
+ example TEXT,
+ count INT NOT NULL DEFAULT 1,
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ -- 人说过不要。**标记而不是删除**:dismiss 从前是 DELETE,下一次抽取遇到
+ -- 同一个词原样插回来——用户的「不要」活不过一轮抽取。自动扩本体开着时,
+ -- 那等于系统覆盖人的明确决定
+ dismissed_at TIMESTAMPTZ,
+ PRIMARY KEY (kb_id, kind, key)
+);
diff --git a/migrations/0005_ontology.sql b/migrations/0005_ontology.sql
deleted file mode 100644
index c1907a04..00000000
--- a/migrations/0005_ontology.sql
+++ /dev/null
@@ -1,15 +0,0 @@
--- 0005: 本体编辑器基础 —— 类型层级(subClassOf 数据面)+ 抽取未匹配统计(LLM 建议流的信号源)
-
--- 实体类型层级:parent_id = subClassOf(公理推理 P4 点亮;编辑器先落数据)
-ALTER TABLE entity_types ADD COLUMN parent_id UUID REFERENCES entity_types(id) ON DELETE SET NULL;
-
--- 抽取过程中命中白名单之外的类型/关系:不是垃圾,是本体扩展的信号
-CREATE TABLE ontology_misses (
- kb_id UUID NOT NULL REFERENCES knowledge_bases(id) ON DELETE CASCADE,
- kind TEXT NOT NULL CHECK (kind IN ('entity_type', 'relation_type')),
- key TEXT NOT NULL,
- example TEXT,
- count INT NOT NULL DEFAULT 1,
- updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
- PRIMARY KEY (kb_id, kind, key)
-);
diff --git a/migrations/0006_resolution.sql b/migrations/0005_resolution.sql
similarity index 82%
rename from migrations/0006_resolution.sql
rename to migrations/0005_resolution.sql
index 590d62a5..a6a57453 100644
--- a/migrations/0006_resolution.sql
+++ b/migrations/0005_resolution.sql
@@ -2,16 +2,7 @@
-- 设计见 docs/DESIGN.md §4:名字只是候选召回线索,身份由上下文(画像向量 + 关系兼容性)决定;
-- 宁分勿合,灰区先落审核队列,LLM 攒批裁决在后台跑,人工终审兜底。
--- 名字不再是身份:拆掉同名唯一索引,同名实体允许并存;保留普通索引做候选召回
-DROP INDEX entities_kb_type_name_idx;
-CREATE INDEX entities_kb_type_name_idx
- ON entities (kb_id, type_id, lower(canonical_name)) WHERE merged_into IS NULL;
--- 实体画像:证据分块向量的增量质心(上下文相似度判定用;复用摄入阶段已算好的 chunk embedding)
-ALTER TABLE entities ADD COLUMN profile_embedding vector;
-ALTER TABLE entities ADD COLUMN profile_n INTEGER NOT NULL DEFAULT 0;
--- 同名并存时的展示消歧后缀(如 张三 · Platform Engineering)
-ALTER TABLE entities ADD COLUMN disambiguator TEXT;
-- 消解审核队列:疑似同一实体的灰区对。
-- stage: adjudicating = 等 LLM 攒批裁决;human = LLM 不确定/未配模型,等人工终审。
diff --git a/migrations/0011_sync_runs.sql b/migrations/0006_sync_runs.sql
similarity index 100%
rename from migrations/0011_sync_runs.sql
rename to migrations/0006_sync_runs.sql
diff --git a/migrations/0007_kb_access.sql b/migrations/0007_kb_access.sql
new file mode 100644
index 00000000..6bd7edb7
--- /dev/null
+++ b/migrations/0007_kb_access.sql
@@ -0,0 +1,55 @@
+-- KB 级访问控制 + 部署配置。
+-- 部署角色挂隐形 workspace(memberships 不动);每个 KB 自带角色矩阵,
+-- 在库自己的 Settings 里配置。注册开关是库内配置而不是 env(/admin 可切)。
+
+CREATE TABLE kb_members (
+ kb_id UUID NOT NULL REFERENCES knowledge_bases(id) ON DELETE CASCADE,
+ user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+ role TEXT NOT NULL CHECK (role IN ('viewer', 'editor', 'admin')),
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ -- 谁把这个成员加进来的(无人可归时留 NULL,展示退化为只有时间)
+ added_by uuid REFERENCES users(id) ON DELETE SET NULL,
+ PRIMARY KEY (kb_id, user_id)
+);
+
+CREATE TABLE deployment_settings (
+ singleton BOOLEAN PRIMARY KEY DEFAULT TRUE CHECK (singleton),
+ open_registration BOOLEAN NOT NULL DEFAULT TRUE,
+ -- 任务 worker 并发数(系统设置可改;调度循环热读,改动即时生效)。
+ -- **这是外层兜底而不是节流**:真正的节流交给按模型的信号量(见
+ -- model_concurrency),这里只防任务无限堆积。要明显大于各模型限额之和,
+ -- 否则被限流的任务会占满槽位把别的饿死
+ worker_concurrency INT NOT NULL DEFAULT 32
+ CHECK (worker_concurrency BETWEEN 1 AND 32),
+ -- 本体铺进抽取提示词的字符预算,超了就改成按分块检索候选。
+ -- 放部署设置而不是环境变量:这一档要能不重启就改——定它需要每个本体规模
+ -- 下全量内联与按块检索各一组对照,靠重启服务改一档的话,那条曲线不会有人
+ -- 跑第二遍。24000 字符(约 6000 token)是拍的,正等那条曲线来定
+ ontology_prompt_budget INTEGER NOT NULL DEFAULT 24000,
+ -- 没在 model_concurrency 里配过的模型走这个缺省
+ default_model_concurrency INT NOT NULL DEFAULT 10,
+ -- JWT 签名密钥。**首次启动自动生成**,于是「照 README 跑起来」和「安全」
+ -- 不再是两件要分别做的事——默认值 dev-secret-change-me 上生产这类事故,
+ -- 靠提醒是防不住的。UTOPIA_JWT_SECRET 仍然优先于本列:轮换密钥、或者要
+ -- 多个实例显式对齐时填环境变量即可,那条路没有被关掉
+ jwt_secret TEXT,
+ -- 新库的 ontology_lang 缺省,含义见 knowledge_bases.ontology_lang
+ default_ontology_lang TEXT NOT NULL DEFAULT 'en',
+ CONSTRAINT deployment_default_ontology_lang_chk
+ CHECK (default_ontology_lang IN ('en', 'zh'))
+);
+INSERT INTO deployment_settings DEFAULT VALUES;
+
+-- 并发限制**按模型算,不按部署算**。真正的约束是模型供应商的速率限制,那是
+-- 按模型(连同 base_url)来的:本地 Ollama 可能只扛 2 个并发,托管 API 能吃
+-- 50——一个全局数字管两者本来就不对。
+--
+-- 限流放在 LLM 调用处而不是任务调度处:不调模型的任务(文件夹同步)不该受它
+-- 约束,调不同模型的任务(抽取用 chat、摄入用 embedding)之间也不该互相挤。
+CREATE TABLE model_concurrency (
+ base_url TEXT NOT NULL,
+ model TEXT NOT NULL,
+ max_concurrent INT NOT NULL CHECK (max_concurrent BETWEEN 1 AND 256),
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ PRIMARY KEY (base_url, model)
+);
diff --git a/migrations/0007_sources.sql b/migrations/0007_sources.sql
deleted file mode 100644
index 3edd32f0..00000000
--- a/migrations/0007_sources.sql
+++ /dev/null
@@ -1,16 +0,0 @@
--- 0007: 来源即文件夹 —— source 是 Library 中的容器,挂着它摄入的文档,可定时同步。
--- kind: upload(手动上传的虚拟归属,通常 source_id 为 NULL)| watch_folder | url | rss | api
--- 设计见 docs/DESIGN.md §4 摄入渠道。
-
-ALTER TABLE sources ADD COLUMN config JSONB NOT NULL DEFAULT '{}';
--- NULL = 仅手动同步
-ALTER TABLE sources ADD COLUMN sync_interval_minutes INTEGER;
-ALTER TABLE sources ADD COLUMN last_sync_at TIMESTAMPTZ;
-ALTER TABLE sources ADD COLUMN last_sync_status TEXT NOT NULL DEFAULT 'never'
- CHECK (last_sync_status IN ('never', 'queued', 'running', 'ok', 'failed'));
-ALTER TABLE sources ADD COLUMN last_sync_error TEXT;
-ALTER TABLE sources ADD COLUMN last_sync_added INTEGER NOT NULL DEFAULT 0;
-
--- 文档标签(过滤与批量组织;不做实体文件夹)
-ALTER TABLE documents ADD COLUMN tags TEXT[] NOT NULL DEFAULT '{}';
-CREATE INDEX documents_tags_idx ON documents USING gin (tags);
diff --git a/migrations/0008_audit_events.sql b/migrations/0008_audit_events.sql
new file mode 100644
index 00000000..edbf8db7
--- /dev/null
+++ b/migrations/0008_audit_events.sql
@@ -0,0 +1,62 @@
+-- 审计日志:谁在何时对什么做了什么(纯审计,不承载回滚等衍生功能)。
+--
+-- **kb_id 与 actor_id 是裸 UUID,没有外键。** 台账不该依赖它所记录的对象存活:
+-- kb_id 若级联删除,删掉一个知识库就删掉了它的全部审计记录——包括刚刚写下的
+-- 那条 kb.deleted,删除是最需要留痕的动作,却成了唯一不留痕的。actor_id 若
+-- SET NULL,一个用户被停用后他做过的每一次确认、驳回、合并都变成匿名。
+-- 合规审计要的恰恰是这两个场景。
+--
+-- 这也是哈希链的前提:链要求记录只增不删,级联删除会在链中间挖掉一段,
+-- 让它断得「合法」而无从分辨。
+CREATE TABLE audit_events (
+ id UUID PRIMARY KEY,
+ kb_id UUID,
+ actor_id UUID,
+ action TEXT NOT NULL,
+ target_kind TEXT NOT NULL,
+ target_id UUID,
+ -- 变更要点,按 action 语义自定
+ detail JSONB NOT NULL DEFAULT '{}',
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ -- 从哪里做的。ISO 27001 A.8.15 要求日志覆盖 Where / How,即请求的来源;
+ -- 没有它,一个账号被盗用后的所有活动看起来与本人操作毫无差别。
+ -- 两列都可空:后台任务(攒批裁决、定时同步)没有客户端,本就该是空
+ client_ip TEXT,
+ user_agent TEXT,
+ -- 操作者的身份快照。actor_id 没有外键,用户停用时行会留下,但 LEFT JOIN
+ -- users 取不到名字,界面只剩一串 UUID。把当时的邮箱与显示名一并写进记录,
+ -- 台账才真正自包含
+ actor_label TEXT
+);
+CREATE INDEX audit_events_kb_time_idx ON audit_events (kb_id, created_at DESC);
+
+-- 按 IP 排查(同一来源的登录失败、异常时段的活动)需要这条索引
+CREATE INDEX audit_events_client_ip_idx ON audit_events (client_ip, created_at DESC)
+ WHERE client_ip IS NOT NULL;
+
+-- 台账只增不改。应用本就只 INSERT,这道触发器挡的是绕过应用的那条路:
+-- 运维直连数据库、一次手滑的 UPDATE、或者有人回头想抹掉自己的痕迹。
+--
+-- 它挡不住 superuser——那个身份可以 DROP TRIGGER 或 ALTER TABLE ... DISABLE
+-- TRIGGER 之后从容修改。所以这一层的作用是把门槛从「顺手就能改」抬到「必须先
+-- 动 DDL」,而 DDL 本身会留在数据库日志里。要让蓄意篡改也无所遁形,得靠后续
+-- 的哈希链:改动会让链在被改的那一条上断开。
+--
+-- 刻意不留应用层的绕过开关。审计不可变性一旦有开关,就等于没有。将来若要做
+-- 保留期清理,那是特权运维动作,应显式 DROP TRIGGER、清理、再重建,全过程
+-- 留在 DDL 记录里。
+CREATE FUNCTION audit_events_immutable() RETURNS trigger AS $$
+BEGIN
+ RAISE EXCEPTION 'audit_events is append-only (attempted %)', TG_OP
+ USING HINT = 'Audit records cannot be modified or deleted.';
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER audit_events_no_update_delete
+ BEFORE UPDATE OR DELETE ON audit_events
+ FOR EACH ROW EXECUTE FUNCTION audit_events_immutable();
+
+-- TRUNCATE 不触发行级触发器,单独挡一道,否则一句 TRUNCATE 就绕过了上面全部。
+CREATE TRIGGER audit_events_no_truncate
+ BEFORE TRUNCATE ON audit_events
+ FOR EACH STATEMENT EXECUTE FUNCTION audit_events_immutable();
diff --git a/migrations/0008_doc_identity.sql b/migrations/0008_doc_identity.sql
deleted file mode 100644
index 802e9389..00000000
--- a/migrations/0008_doc_identity.sql
+++ /dev/null
@@ -1,19 +0,0 @@
--- 0008: 文档逻辑身份 —— 摄入的三路判定(新增 / 变更 / 未变)。
--- external_key = 来源内的逻辑身份(watch_folder 相对路径 / url / rss guid / api external_id);
--- 内容变更时原地替换文档(不再堆积新文档),旧版本记入 document_versions(版本回放的原料,
--- 文件 blob 内容寻址不删)。目录里消失的文件标记 missing_since(默认保留不删)。
-
-ALTER TABLE documents ADD COLUMN external_key TEXT;
-ALTER TABLE documents ADD COLUMN missing_since TIMESTAMPTZ;
-CREATE UNIQUE INDEX documents_source_key_idx
- ON documents (source_id, external_key) WHERE external_key IS NOT NULL;
-
-CREATE TABLE document_versions (
- id UUID PRIMARY KEY,
- document_id UUID NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
- version INTEGER NOT NULL,
- sha256 TEXT NOT NULL,
- size_bytes BIGINT NOT NULL DEFAULT 0,
- ingested_at TIMESTAMPTZ NOT NULL DEFAULT now(),
- UNIQUE (document_id, version)
-);
diff --git a/migrations/0019_conversations.sql b/migrations/0009_conversations.sql
similarity index 100%
rename from migrations/0019_conversations.sql
rename to migrations/0009_conversations.sql
diff --git a/migrations/0009_source_icon.sql b/migrations/0009_source_icon.sql
deleted file mode 100644
index 35890bcb..00000000
--- a/migrations/0009_source_icon.sql
+++ /dev/null
@@ -1,2 +0,0 @@
--- 0009: 来源自定义图标(lucide 图标名,NULL 时前端按 kind 取默认图标)
-ALTER TABLE sources ADD COLUMN icon TEXT;
diff --git a/migrations/0020_data_sources.sql b/migrations/0010_data_sources.sql
similarity index 100%
rename from migrations/0020_data_sources.sql
rename to migrations/0010_data_sources.sql
diff --git a/migrations/0010_sync_cron.sql b/migrations/0010_sync_cron.sql
deleted file mode 100644
index 4d8df5b1..00000000
--- a/migrations/0010_sync_cron.sql
+++ /dev/null
@@ -1,3 +0,0 @@
--- 0010: 来源定时同步支持 cron 表达式(标准 5 段,与 sync_interval_minutes 互斥;
--- UI 提供可视化选择器构建,Advanced 模式才暴露原生表达式)
-ALTER TABLE sources ADD COLUMN sync_cron TEXT;
diff --git a/migrations/0022_extraction_transparency.sql b/migrations/0011_extraction_transparency.sql
similarity index 60%
rename from migrations/0022_extraction_transparency.sql
rename to migrations/0011_extraction_transparency.sql
index d2869429..2ffd1e40 100644
--- a/migrations/0022_extraction_transparency.sql
+++ b/migrations/0011_extraction_transparency.sql
@@ -1,13 +1,7 @@
--- 抽取的两处静默丢失。
---
--- 一、被挡掉的事实不留痕。抽取器有七处 `continue`:主语类型不明、属性 domain
+-- 被挡掉的事实不留痕。抽取器有七处 `continue`:主语类型不明、属性 domain
-- 不匹配、值不合 datatype、置信度不够……事实抽出来了、被挡掉、什么都不说,
-- 用户只看到图里少了东西。与"账本 append-only、每条事实都有证据、不确定性
-- 浮到人面前"三条原则直接冲突。
---
--- 二、降级成 related_to 时原词丢了。`ontology_misses` 只记了"available_from
--- 出现过 9 次"这样的总数,事实行上一字未留——今天无法回答"哪条 related_to
--- 原本说的是什么"。
-- 按 document 归集:既能算单篇的"多少条没落地",也能在 KB 层聚合。
-- 同时天然修好生命周期——ontology_misses 只在整库重建时清(graph.rs),
@@ -28,8 +22,3 @@ CREATE TABLE extraction_drops (
CREATE INDEX extraction_drops_doc_idx ON extraction_drops (document_id);
--- 表层谓词落在证据上而不是事实上:事实按 (kb, 主, 谓, 宾) 去重,甲块说
--- "runs on"、乙块说 "optimized for" 会并成同一行,放事实上就是先写者胜、
--- 其余静默丢弃——正是本次要修的毛病。证据是每分块一行,粒度对,而且它
--- 已经带着 quote(该块的原文佐证),表层谓词是同一种东西:每次观察的原始形态。
-ALTER TABLE fact_evidence ADD COLUMN surface_predicate TEXT;
diff --git a/migrations/0023_fact_adoptions.sql b/migrations/0012_fact_adoptions.sql
similarity index 100%
rename from migrations/0023_fact_adoptions.sql
rename to migrations/0012_fact_adoptions.sql
diff --git a/migrations/0012_kb_access.sql b/migrations/0012_kb_access.sql
deleted file mode 100644
index 0c8e2052..00000000
--- a/migrations/0012_kb_access.sql
+++ /dev/null
@@ -1,33 +0,0 @@
--- 0012: KB 级访问控制 + 部署配置。
--- 设计(2026-08-26 拍板):部署角色挂隐形 workspace(memberships 不动);
--- 每个 KB 自带角色矩阵(kb_members,viewer|editor|admin),在库自己的 Settings 里配置;
--- open 库无矩阵记录时按部署角色行事,restricted 库仅矩阵成员可见(外人 NotFound)。
--- 注册开关从 env 升级为库内配置(/admin 可切)。
-
-ALTER TABLE knowledge_bases ADD COLUMN visibility TEXT NOT NULL DEFAULT 'open'
- CHECK (visibility IN ('open', 'restricted'));
--- 默认库永远 open(is_default 列见 0001;规则在 API 强制,这里 DB 级双保险)
-ALTER TABLE knowledge_bases ADD CONSTRAINT kb_default_open
- CHECK (NOT is_default OR visibility = 'open');
-
-CREATE TABLE kb_members (
- kb_id UUID NOT NULL REFERENCES knowledge_bases(id) ON DELETE CASCADE,
- user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
- role TEXT NOT NULL CHECK (role IN ('viewer', 'editor', 'admin')),
- created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
- PRIMARY KEY (kb_id, user_id)
-);
-
-CREATE TABLE deployment_settings (
- singleton BOOLEAN PRIMARY KEY DEFAULT TRUE CHECK (singleton),
- open_registration BOOLEAN NOT NULL DEFAULT TRUE,
- -- 任务 worker 并发数(系统设置可改;调度循环热读,改动即时生效)
- worker_concurrency INT NOT NULL DEFAULT 4
- CHECK (worker_concurrency BETWEEN 1 AND 32),
- -- 本体铺进抽取提示词的字符预算,超了就改成按分块检索候选。
- -- 放部署设置而不是环境变量:这一档要能不重启就改——定它需要每个本体规模
- -- 下全量内联与按块检索各一组对照,靠重启服务改一档的话,那条曲线不会有人
- -- 跑第二遍。24000 字符(约 6000 token)是拍的,正等那条曲线来定
- ontology_prompt_budget INTEGER NOT NULL DEFAULT 24000
-);
-INSERT INTO deployment_settings DEFAULT VALUES;
diff --git a/migrations/0030_entity_retypes.sql b/migrations/0013_entity_retypes.sql
similarity index 50%
rename from migrations/0030_entity_retypes.sql
rename to migrations/0013_entity_retypes.sql
index b344741f..52fe2650 100644
--- a/migrations/0030_entity_retypes.sql
+++ b/migrations/0013_entity_retypes.sql
@@ -1,8 +1,7 @@
-- 采纳一个实体类型时,哪些实体被改了类。
--
--- 与 fact_adoptions 对称,理由也一样:只建类型不动实体的话,本体长大了、图没变好——
--- 那些提议过 model 的实体会继续挂在 concept 下。而改完必须能撤销,否则没人敢让
--- 系统自动建类。
+-- 与 fact_adoptions 对称,理由也一样:只建类型不动实体的话,本体长大了、图没变好。
+-- 而改完必须能撤销,否则没人敢让系统自动建类。
--
-- 实体不是 append-only 的(它是可变行,P0 的 PATCH 就直接改),所以撤销靠记下
-- 改之前的类型,而不是靠 supersedes 链。
@@ -10,11 +9,19 @@ CREATE TABLE entity_retypes (
batch_id UUID NOT NULL,
kb_id UUID NOT NULL REFERENCES knowledge_bases(id) ON DELETE CASCADE,
entity_id UUID NOT NULL REFERENCES entities(id) ON DELETE CASCADE,
- from_type_id UUID NOT NULL REFERENCES entity_types(id) ON DELETE CASCADE,
+ -- **可空**:0009 之后最常见的一次改类正是「从没有类到有类」,而这张表是
+ -- 撤销的唯一依据。非空的话第一次赋类就写不进账,那批改动不可撤
+ from_type_id UUID REFERENCES entity_types(id) ON DELETE CASCADE,
to_type_id UUID NOT NULL REFERENCES entity_types(id) ON DELETE CASCADE,
-- 与 fact_adoptions 一致:撤销标记而非删除,采纳发生过、撤销也发生过
reverted_at TIMESTAMPTZ,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ -- 谁改的。可空 = 引擎自动裁决,跟 `entity_merges.merged_by` 一个约定。
+ --
+ -- **它只回答「谁发起了这次改动」**,不回答「这个类是不是人判的」——
+ -- 那两件事被混为一谈过一次:类型消解把点「运行」的人传了下来,于是每个
+ -- 被引擎裁决的实体都成了 `type_source = human`,从此再不被消解(见 #117)
+ actor_id UUID REFERENCES users(id),
PRIMARY KEY (batch_id, entity_id)
);
diff --git a/migrations/0013_entity_shape.sql b/migrations/0013_entity_shape.sql
deleted file mode 100644
index 644a72f1..00000000
--- a/migrations/0013_entity_shape.sql
+++ /dev/null
@@ -1,6 +0,0 @@
--- 0013: 实体类型形状升格为本体属性(此前 organization/product = 方形是前端写死的)。
--- 图谱节点按类型的 shape 渲染:circle(四层圆)| square(四层方)。
-ALTER TABLE entity_types ADD COLUMN shape TEXT NOT NULL DEFAULT 'circle'
- CHECK (shape IN ('circle', 'square'));
--- 保持现有观感:内置的组织/产品沿用方形
-UPDATE entity_types SET shape = 'square' WHERE key IN ('organization', 'product');
diff --git a/migrations/0031_least_privilege_role.sql b/migrations/0014_least_privilege_role.sql
similarity index 100%
rename from migrations/0031_least_privilege_role.sql
rename to migrations/0014_least_privilege_role.sql
diff --git a/migrations/0014_type_descriptions.sql b/migrations/0014_type_descriptions.sql
deleted file mode 100644
index 00aef261..00000000
--- a/migrations/0014_type_descriptions.sql
+++ /dev/null
@@ -1,4 +0,0 @@
--- 类型描述:不是给人看的装饰,是喂给抽取 prompt 的语义指引
--- ("Event: 有明确时间点的事件,如发布、收购、会议"),直接影响抽取质量。
-ALTER TABLE entity_types ADD COLUMN description TEXT NOT NULL DEFAULT '';
-ALTER TABLE relation_types ADD COLUMN description TEXT NOT NULL DEFAULT '';
diff --git a/migrations/0032_ontology_imports.sql b/migrations/0015_ontology_imports.sql
similarity index 71%
rename from migrations/0032_ontology_imports.sql
rename to migrations/0015_ontology_imports.sql
index cdaa6856..f2a5ebb4 100644
--- a/migrations/0032_ontology_imports.sql
+++ b/migrations/0015_ontology_imports.sql
@@ -24,10 +24,3 @@ CREATE TABLE ontology_imports (
CREATE INDEX ontology_imports_kb_idx ON ontology_imports (kb_id, imported_at DESC);
--- IRI 是全局身份,key 是给模型读的短标签(见 0001 P2 的"IRI 与 key 的分工")。
--- 重导入按 IRI 匹配已有行——按 key 匹配会因为上游改了 rdfs:label 导致 key 变化
--- 而把同一个类当成新类建出来,实体全留在孤儿上。
-ALTER TABLE entity_types ADD COLUMN iri TEXT;
-ALTER TABLE relation_types ADD COLUMN iri TEXT;
-CREATE UNIQUE INDEX entity_types_iri_idx ON entity_types (kb_id, iri) WHERE iri IS NOT NULL;
-CREATE UNIQUE INDEX relation_types_iri_idx ON relation_types (kb_id, iri) WHERE iri IS NOT NULL;
diff --git a/migrations/0015_source_ingest_tokens.sql b/migrations/0015_source_ingest_tokens.sql
deleted file mode 100644
index 4cc704e3..00000000
--- a/migrations/0015_source_ingest_tokens.sql
+++ /dev/null
@@ -1,3 +0,0 @@
--- api 来源的专属推送密钥:只存 sha256 十六进制哈希,明文仅在创建/轮换时返回一次。
--- KB 级 /ingest 改为落入 Uploads(普通上传语义);带身份的推送走 api 来源 + 本密钥。
-ALTER TABLE sources ADD COLUMN ingest_token_hash TEXT;
diff --git a/migrations/0016_source_token_plaintext.sql b/migrations/0016_source_token_plaintext.sql
deleted file mode 100644
index c5d77676..00000000
--- a/migrations/0016_source_token_plaintext.sql
+++ /dev/null
@@ -1,4 +0,0 @@
--- 自部署威胁模型下"只看一次"是自找麻烦:改存明文,随时可查(Editor 权限专用端点)。
--- DB 失守时文档本体早已泄露,密钥哈希化没有额外收益;Rotate 保留应对泄露。
-ALTER TABLE sources DROP COLUMN ingest_token_hash;
-ALTER TABLE sources ADD COLUMN ingest_token TEXT;
diff --git a/migrations/0040_type_refinement_pairs.sql b/migrations/0016_type_refinement_pairs.sql
similarity index 100%
rename from migrations/0040_type_refinement_pairs.sql
rename to migrations/0016_type_refinement_pairs.sql
diff --git a/migrations/0041_alerts.sql b/migrations/0017_alerts.sql
similarity index 100%
rename from migrations/0041_alerts.sql
rename to migrations/0017_alerts.sql
diff --git a/migrations/0017_kb_member_added_by.sql b/migrations/0017_kb_member_added_by.sql
deleted file mode 100644
index a3fff611..00000000
--- a/migrations/0017_kb_member_added_by.sql
+++ /dev/null
@@ -1,4 +0,0 @@
--- 加入信息:记录把成员加进库的人(历史行留 NULL,展示退化为只有时间)。
--- IF NOT EXISTS:允许开发期手动预应用与启动迁移共存。
-ALTER TABLE kb_members
- ADD COLUMN IF NOT EXISTS added_by uuid REFERENCES users(id) ON DELETE SET NULL;
diff --git a/migrations/0018_audit_events.sql b/migrations/0018_audit_events.sql
deleted file mode 100644
index fcf92186..00000000
--- a/migrations/0018_audit_events.sql
+++ /dev/null
@@ -1,14 +0,0 @@
--- 审计日志:谁在何时对什么做了什么(纯审计,不承载回滚等衍生功能)。
--- detail 存变更要点(jsonb,按 action 语义自定),actor 删号后置 NULL 保留事件。
-CREATE TABLE IF NOT EXISTS audit_events (
- id UUID PRIMARY KEY,
- kb_id UUID REFERENCES knowledge_bases(id) ON DELETE CASCADE,
- actor_id UUID REFERENCES users(id) ON DELETE SET NULL,
- action TEXT NOT NULL,
- target_kind TEXT NOT NULL,
- target_id UUID,
- detail JSONB NOT NULL DEFAULT '{}',
- created_at TIMESTAMPTZ NOT NULL DEFAULT now()
-);
-CREATE INDEX IF NOT EXISTS audit_events_kb_time_idx
- ON audit_events (kb_id, created_at DESC);
diff --git a/migrations/0049_ontology_proposals.sql b/migrations/0018_ontology_proposals.sql
similarity index 100%
rename from migrations/0049_ontology_proposals.sql
rename to migrations/0018_ontology_proposals.sql
diff --git a/migrations/0055_a_mapping_is_not_a_fact.sql b/migrations/0019_a_mapping_is_not_a_fact.sql
similarity index 100%
rename from migrations/0055_a_mapping_is_not_a_fact.sql
rename to migrations/0019_a_mapping_is_not_a_fact.sql
diff --git a/migrations/0021_graph_error.sql b/migrations/0021_graph_error.sql
deleted file mode 100644
index 67a072f8..00000000
--- a/migrations/0021_graph_error.sql
+++ /dev/null
@@ -1,8 +0,0 @@
--- 抽取失败的原因此前只进日志与 jobs.last_error,文档上什么都不留,界面无从显示。
--- graph_error 独立成列:documents.error 归解析管道所有(set_status 会清空它),互不干扰。
-ALTER TABLE documents ADD COLUMN graph_error TEXT;
-
--- 抽取任务的所有权凭证。重抽时自增即"解雇"正在跑的那个任务:它每处理完一个
--- 分块回读一次,发现 epoch 变了就安静退出,把文档让给新任务。
--- 单靠 graph_status 判断不可靠——接手者会把状态写回 extracting,旧任务无从分辨。
-ALTER TABLE documents ADD COLUMN extract_epoch INT NOT NULL DEFAULT 0;
diff --git a/migrations/0024_auto_extend_ontology.sql b/migrations/0024_auto_extend_ontology.sql
deleted file mode 100644
index bd8e9766..00000000
--- a/migrations/0024_auto_extend_ontology.sql
+++ /dev/null
@@ -1,15 +0,0 @@
--- 本体自动扩展的开关,以及"人说过不要"的记忆。
---
--- 开关:冷启动自动扩本体此前靠"本体有没有被碰过"来判断该不该跑。那个判据
--- 是从行为里推断意图,推错了会很荒唐——在提案上点一次 Add 就会永久关掉
--- 建议功能,因为那记了一条带操作人的本体动作。而且它一旦为假就永不再真,
--- 本体被冻结在第一批文档碰巧包含的词汇上,可来源是每天持续进文档的。
--- 换成显式开关:猜测没有了,冻结也没有了,"要不要替我做"由人声明。
-ALTER TABLE knowledge_bases
- ADD COLUMN auto_extend_ontology BOOLEAN NOT NULL DEFAULT TRUE;
-
--- 记忆:dismiss 此前是 DELETE,下一次抽取遇到同一个词原样插回来——用户的
--- "不要"活不过一轮抽取。开关关着时这只是恼人;开着时它变成系统覆盖人的
--- 明确决定。标记而非删除,累加与自动采纳都绕开已标记的。
-ALTER TABLE ontology_misses
- ADD COLUMN dismissed_at TIMESTAMPTZ;
diff --git a/migrations/0025_audit_outlives_targets.sql b/migrations/0025_audit_outlives_targets.sql
deleted file mode 100644
index d494ae5a..00000000
--- a/migrations/0025_audit_outlives_targets.sql
+++ /dev/null
@@ -1,15 +0,0 @@
--- 台账不该依赖它所记录的对象存活。
---
--- kb_id 原为 ON DELETE CASCADE:删掉一个知识库,它的全部审计记录随之消失——
--- 包括刚刚写下的那条 kb.deleted。删除是最需要留痕的动作,却成了唯一不留痕的。
--- actor_id 原为 ON DELETE SET NULL:删掉一个用户,他做过的每一次确认、驳回、
--- 合并都变成匿名,再也追不回是谁做的。合规审计要的恰恰是这两个场景。
---
--- 去掉两个外键,只保留 UUID 值:对象没了,记录还在,且仍指得出那个已不存在的
--- 对象。这也是后续追加哈希链的前提——链要求记录只增不删,级联删除会在链中间
--- 挖掉一段,让它断得"合法"而无从分辨。
---
--- 应用从不依赖这两处级联(只 INSERT,删 KB 走 DELETE FROM knowledge_bases,
--- 级联是数据库自己做的),(kb_id, created_at DESC) 索引保持不变,查询不受影响。
-ALTER TABLE audit_events DROP CONSTRAINT audit_events_kb_id_fkey;
-ALTER TABLE audit_events DROP CONSTRAINT audit_events_actor_id_fkey;
diff --git a/migrations/0026_audit_append_only.sql b/migrations/0026_audit_append_only.sql
deleted file mode 100644
index 44f860fb..00000000
--- a/migrations/0026_audit_append_only.sql
+++ /dev/null
@@ -1,26 +0,0 @@
--- 台账只增不改。应用本就只 INSERT,这道触发器挡的是绕过应用的那条路:
--- 运维直连数据库、一次手滑的 UPDATE、或者有人回头想抹掉自己的痕迹。
---
--- 它挡不住 superuser——那个身份可以 DROP TRIGGER 或 ALTER TABLE ... DISABLE
--- TRIGGER 之后从容修改。所以这一层的作用是把门槛从"顺手就能改"抬到"必须先
--- 动 DDL",而 DDL 本身会留在数据库日志里。要让蓄意篡改也无所遁形,得靠后续
--- 的哈希链:改动会让链在被改的那一条上断开。
---
--- 刻意不留应用层的绕过开关。审计不可变性一旦有开关,就等于没有。将来若要做
--- 保留期清理,那是特权运维动作,应显式 DROP TRIGGER、清理、再重建,全过程
--- 留在 DDL 记录里。
-CREATE FUNCTION audit_events_immutable() RETURNS trigger AS $$
-BEGIN
- RAISE EXCEPTION 'audit_events is append-only (attempted %)', TG_OP
- USING HINT = 'Audit records cannot be modified or deleted.';
-END;
-$$ LANGUAGE plpgsql;
-
-CREATE TRIGGER audit_events_no_update_delete
- BEFORE UPDATE OR DELETE ON audit_events
- FOR EACH ROW EXECUTE FUNCTION audit_events_immutable();
-
--- TRUNCATE 不触发行级触发器,单独挡一道,否则一句 TRUNCATE 就绕过了上面全部。
-CREATE TRIGGER audit_events_no_truncate
- BEFORE TRUNCATE ON audit_events
- FOR EACH STATEMENT EXECUTE FUNCTION audit_events_immutable();
diff --git a/migrations/0027_audit_client_context.sql b/migrations/0027_audit_client_context.sql
deleted file mode 100644
index b4dfb485..00000000
--- a/migrations/0027_audit_client_context.sql
+++ /dev/null
@@ -1,16 +0,0 @@
--- 台账此前只记「谁做了什么」,不记「从哪里做的」。ISO 27001 A.8.15 要求日志
--- 覆盖 Where / How,即请求的来源;没有它,一个账号被盗用后的所有活动看起来
--- 与本人操作毫无差别。
---
--- 两列都可空:后台任务(攒批裁决、定时同步)没有客户端,本就该是空。
-ALTER TABLE audit_events ADD COLUMN client_ip TEXT;
-ALTER TABLE audit_events ADD COLUMN user_agent TEXT;
-
--- 操作者的身份快照。actor_id 在 0025 之后不再有外键,用户删除时行会留下,
--- 但 LEFT JOIN users 取不到名字,界面只剩一串 UUID。把当时的邮箱与显示名
--- 一并写进记录,台账才真正自包含。
-ALTER TABLE audit_events ADD COLUMN actor_label TEXT;
-
--- 按 IP 排查(同一来源的登录失败、异常时段的活动)需要这条索引。
-CREATE INDEX audit_events_client_ip_idx ON audit_events (client_ip, created_at DESC)
- WHERE client_ip IS NOT NULL;
diff --git a/migrations/0028_proposed_type.sql b/migrations/0028_proposed_type.sql
deleted file mode 100644
index f81db152..00000000
--- a/migrations/0028_proposed_type.sql
+++ /dev/null
@@ -1,18 +0,0 @@
--- 模型提议的类型/谓词:本体装不下时,它说的那个词。
---
--- 事实那边已经有了(surface_predicate),实体这边还没有:类型不在本体里就降级成
--- concept,模型说的 "model" 只剩一个「model ×43」的总数,实体行上一字未留。
--- 后果是想加 model 类时找不出那 43 个实体——它们混在 322 个 concept 里,只能整库重抽。
-ALTER TABLE entities ADD COLUMN IF NOT EXISTS proposed_type TEXT;
-
--- 顺手改名。"表层"是造出来的词,得先解释才懂;"提议的"一眼就对,而且更准确——
--- 那不是猜测:模型读了原文得出 model,通常是对的,只是本体表达不了。
--- 真正带兜底性质的是我们存进去的 concept。
--- 幂等:改号之前这两条已在部分库里跑过(0025/0026 与另一条改动撞号,见 0030 的
--- 说明),renumber 后必须能在那些库上安全重放。
-DO $$ BEGIN
- IF EXISTS (SELECT 1 FROM information_schema.columns
- WHERE table_name = 'fact_evidence' AND column_name = 'surface_predicate') THEN
- ALTER TABLE fact_evidence RENAME COLUMN surface_predicate TO proposed_predicate;
- END IF;
-END $$;
diff --git a/migrations/0029_model_concurrency.sql b/migrations/0029_model_concurrency.sql
deleted file mode 100644
index 71a408c5..00000000
--- a/migrations/0029_model_concurrency.sql
+++ /dev/null
@@ -1,26 +0,0 @@
--- 并发限制按模型算,不按部署算。
---
--- 真正的约束是模型供应商的速率限制,那是按模型(连同 base_url)来的:本地
--- Ollama 可能只扛 2 个并发,托管 API 能吃 50——一个全局数字管两者本来就不对。
---
--- 限流放在 LLM 调用处而不是任务调度处:不调模型的任务(文件夹同步)不该受它
--- 约束,调不同模型的任务(抽取用 chat、摄入用 embedding)之间也不该互相挤。
-CREATE TABLE IF NOT EXISTS model_concurrency (
- base_url TEXT NOT NULL,
- model TEXT NOT NULL,
- max_concurrent INT NOT NULL CHECK (max_concurrent BETWEEN 1 AND 256),
- updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
- PRIMARY KEY (base_url, model)
-);
-
--- 没配过的模型走这个缺省
--- 幂等:改号前这条已在部分库跑过(0026 撞号),必须能安全重放
-ALTER TABLE deployment_settings
- ADD COLUMN IF NOT EXISTS default_model_concurrency INT NOT NULL DEFAULT 10;
-
--- worker 并发降级成外层兜底:真正的节流交给按模型的信号量,这里只防任务
--- 无限堆积。要明显大于各模型限额之和,否则被限流的任务会占满槽位把别的饿死。
--- 幂等:改号前这条已在部分库跑过(0026 撞号),必须能安全重放
-ALTER TABLE deployment_settings
- ALTER COLUMN worker_concurrency SET DEFAULT 32;
-UPDATE deployment_settings SET worker_concurrency = 32 WHERE worker_concurrency = 4;
diff --git a/migrations/0033_auto_jwt_secret.sql b/migrations/0033_auto_jwt_secret.sql
deleted file mode 100644
index 647b7d13..00000000
--- a/migrations/0033_auto_jwt_secret.sql
+++ /dev/null
@@ -1,7 +0,0 @@
--- JWT 签名密钥不再要求部署者手填。首次启动时自动生成一条存这里,
--- 于是「照 README 跑起来」和「安全」不再是两件要分别做的事——
--- 默认值 dev-secret-change-me 上生产这类事故,靠提醒是防不住的。
---
--- UTOPIA_JWT_SECRET 仍然优先于本列:轮换密钥、或者要多个实例显式对齐时,
--- 填环境变量即可,那条路没有被关掉。
-ALTER TABLE deployment_settings ADD COLUMN jwt_secret TEXT;
diff --git a/migrations/0034_ontology_language.sql b/migrations/0034_ontology_language.sql
deleted file mode 100644
index 6e0a88c9..00000000
--- a/migrations/0034_ontology_language.sql
+++ /dev/null
@@ -1,19 +0,0 @@
--- 内置本体用哪种语言播种,以及新库的默认值。
---
--- **这不是"系统语言"**(见 docs/decisions/0004)。界面语言在客户端,后端没有 locale。
--- 这一列管的是**语料的语言**:类的 description 逐字进抽取提示词,读者是正在读你文档
--- 的模型——描述与被判断的文本同语言,判断更稳。所以中国团队读英文技术文档时,
--- 界面要中文而这一列该是 'en',一个开关按不下去这两件事。
---
--- 语言只在**播种那一刻**决定内置类的措辞。此后 label/description 是这个库的数据,
--- 可编辑;改这一列不会回头重写它们。它继续管的是新描述(自动扩本体、AI 建议)写成什么语言。
-ALTER TABLE knowledge_bases ADD COLUMN ontology_lang TEXT NOT NULL DEFAULT 'en';
-ALTER TABLE deployment_settings ADD COLUMN default_ontology_lang TEXT NOT NULL DEFAULT 'en';
-
--- 取值收在 CHECK 里而不是应用层:这一列会被用来挑一张编译期常量表,
--- 写进一个没有对应表的值只会静默回落到英文,不报错——那种错最难查
-ALTER TABLE knowledge_bases
- ADD CONSTRAINT knowledge_bases_ontology_lang_chk CHECK (ontology_lang IN ('en', 'zh'));
-ALTER TABLE deployment_settings
- ADD CONSTRAINT deployment_default_ontology_lang_chk
- CHECK (default_ontology_lang IN ('en', 'zh'));
diff --git a/migrations/0035_relation_type_domains_ranges.sql b/migrations/0035_relation_type_domains_ranges.sql
deleted file mode 100644
index 5d8c5550..00000000
--- a/migrations/0035_relation_type_domains_ranges.sql
+++ /dev/null
@@ -1,34 +0,0 @@
--- domain / range 从单列改为关联表。
---
--- **为什么必须是多值**:OWL 里一个属性有多个 rdfs:domain 是常态
--- (works_at 的主语可能是 person 也可能是 organization),单列表达不了,
--- 导入时只能挑一个丢一个。FOAF 里就有这样的属性。
---
--- **为什么把列删掉而不是留着当"主 domain"**:留着就是同一件事有两处记录,
--- 而两处记录迟早分叉——今天已经在别处踩过一次(预览与落库各判一次 key 冲突,
--- 结果预览说了假话)。一处权威,读的人不必猜该信哪个。
---
--- range 只服务对象属性:数据属性的 range 是字面量类型,落在 relation_types.datatype 上。
-
-CREATE TABLE relation_type_domains (
- relation_type_id UUID NOT NULL REFERENCES relation_types(id) ON DELETE CASCADE,
- entity_type_id UUID NOT NULL REFERENCES entity_types(id) ON DELETE CASCADE,
- PRIMARY KEY (relation_type_id, entity_type_id)
-);
-
-CREATE TABLE relation_type_ranges (
- relation_type_id UUID NOT NULL REFERENCES relation_types(id) ON DELETE CASCADE,
- entity_type_id UUID NOT NULL REFERENCES entity_types(id) ON DELETE CASCADE,
- PRIMARY KEY (relation_type_id, entity_type_id)
-);
-
--- 反向查:本体页要按类列出它的属性,抽取要按类筛可用属性。
--- 主键覆盖了正向,反向得自己建
-CREATE INDEX relation_type_domains_entity_idx ON relation_type_domains (entity_type_id);
-CREATE INDEX relation_type_ranges_entity_idx ON relation_type_ranges (entity_type_id);
-
--- 回填现有属性的单个 domain。此前只有属性用得上这一列,关系一直是 NULL
-INSERT INTO relation_type_domains (relation_type_id, entity_type_id)
-SELECT id, domain_type_id FROM relation_types WHERE domain_type_id IS NOT NULL;
-
-ALTER TABLE relation_types DROP COLUMN domain_type_id;
diff --git a/migrations/0036_entity_type_parents.sql b/migrations/0036_entity_type_parents.sql
deleted file mode 100644
index 75be7b9f..00000000
--- a/migrations/0036_entity_type_parents.sql
+++ /dev/null
@@ -1,32 +0,0 @@
--- subClassOf 从单列改为关联表:一个类可以有多个父类。
---
--- **为什么必须多父**:真实词汇表里这是常态。FOAF 的 Person 同时是 foaf:Agent
--- 与 geo:SpatialThing——两个方向,不是同一根链上的祖孙。导入此前只投影第一个,
--- 于是 domain 落在另一支上的属性判定不过:latitude 的 domain 是 SpatialThing,
--- 而 person 只挂在 agent 下,那条事实抽出来了却被挡掉(报 attr_domain_mismatch)。
---
--- **is_primary 不是冗余**。左栏按树展示,一个类只能画在一处,而"画在哪一支下"
--- 是 subClassOf 集合本身答不出的问题——它是多出来的一条信息,不是同一件事记两遍。
--- 部分唯一索引保证每个类至多一个主父。
-
-CREATE TABLE entity_type_parents (
- child_id UUID NOT NULL REFERENCES entity_types(id) ON DELETE CASCADE,
- parent_id UUID NOT NULL REFERENCES entity_types(id) ON DELETE CASCADE,
- -- 左栏画树时走这一支。不参与语义,只管展示
- is_primary BOOLEAN NOT NULL DEFAULT FALSE,
- PRIMARY KEY (child_id, parent_id),
- -- 自环在这里就挡掉;更长的环由应用在写入前查(SQL 拦不住 A→B→A)
- CONSTRAINT entity_type_parents_no_self CHECK (child_id <> parent_id)
-);
-
-CREATE UNIQUE INDEX entity_type_parents_primary_idx
- ON entity_type_parents (child_id) WHERE is_primary;
-
--- 反向查:左栏要按父类找子类,域判定要沿父链上溯
-CREATE INDEX entity_type_parents_parent_idx ON entity_type_parents (parent_id);
-
--- 回填。原来的单父就是主父——它本来就是左栏画树用的那一支
-INSERT INTO entity_type_parents (child_id, parent_id, is_primary)
-SELECT id, parent_id, TRUE FROM entity_types WHERE parent_id IS NOT NULL;
-
-ALTER TABLE entity_types DROP COLUMN parent_id;
diff --git a/migrations/0037_attribute_misses.sql b/migrations/0037_attribute_misses.sql
deleted file mode 100644
index c7b07974..00000000
--- a/migrations/0037_attribute_misses.sql
+++ /dev/null
@@ -1,10 +0,0 @@
--- 词表外的谓词带着字面值时,记的是"缺一个属性"而不是"缺一个关系"。
---
--- 抽取遇到未知谓词 + 字面值宾语(`founding_date: "2015"`),从前要么整条丢掉
--- (value 有而 object 空),要么给 2015 编一个 concept 实体。现在值落进
--- object_value 挂在兜底谓词上,原词进 fact_evidence.proposed_predicate。
--- 这里补的是**给人看的那一栏**:把它记成 relation_type 会让本体提案去建一个
--- 关系,而它要的是一个属性。
-ALTER TABLE ontology_misses DROP CONSTRAINT ontology_misses_kind_check;
-ALTER TABLE ontology_misses ADD CONSTRAINT ontology_misses_kind_check
- CHECK (kind IN ('entity_type', 'relation_type', 'attribute_type'));
diff --git a/migrations/0038_ontology_embeddings.sql b/migrations/0038_ontology_embeddings.sql
deleted file mode 100644
index 6ea04863..00000000
--- a/migrations/0038_ontology_embeddings.sql
+++ /dev/null
@@ -1,18 +0,0 @@
--- 本体自己的向量。类、关系、属性各一条,用 label + description 嵌出来。
---
--- 为什么要它:今天凡是要问"这个说法对应本体里的哪一个"的地方,都是把整个本体
--- 内联进提示词——build_proposals 一次塞 1949 个 key(还只有 key 没有描述,
--- 模型据此根本判断不了"这是不是已有类型的同义说法")。有了向量就能只取候选。
---
--- 维度不定:跟 chunks.embedding 一样随工作区所选模型走,所以不建 HNSW,顺扫。
--- 本体行数以千计,顺扫完全够。
-ALTER TABLE entity_types ADD COLUMN embedding vector;
-ALTER TABLE relation_types ADD COLUMN embedding vector;
-
--- **存"当时嵌的是什么"而不是一个时间戳。**
--- 时间戳只能回答"嵌过没有",回答不了"嵌的还是不是现在这段文字"——描述改了、
--- 嵌入模型换了,向量就是陈的,而时间戳看不出来。存原文与模型名,填充任务
--- 一比对就知道该重嵌谁,也就不必去每一个改描述的写入点挂钩子(漏一个就悄悄烂掉)。
--- 本体只有几千行,存原文的代价可以忽略,而排查检索质量时它值钱。
-ALTER TABLE entity_types ADD COLUMN embedded_text text, ADD COLUMN embedded_model text;
-ALTER TABLE relation_types ADD COLUMN embedded_text text, ADD COLUMN embedded_model text;
diff --git a/migrations/0039_specific_type.sql b/migrations/0039_specific_type.sql
deleted file mode 100644
index c206611c..00000000
--- a/migrations/0039_specific_type.sql
+++ /dev/null
@@ -1,11 +0,0 @@
--- 模型对每个实体自己的说法:它认为这最具体是个什么。
---
--- 跟 proposed_type 是两回事,不能合用一列:那一列的含义是"模型要的东西本体里
--- 没有",0003 的增长回路靠它的**稀有性**设门槛。每个实体都填的话,回路会给
--- 每一个实体提议建一个新类。
---
--- 为什么需要它:清单里总有个"差不多"的。本体有 product,模型觉得够用就选了,
--- 心里那个"向量数据库软件"就此丢失——实测 17 个实体的 proposed_type 全空。
--- 而类型消解最需要的正是这个名字:短名字对短标签,比拿一段中文散文去匹配
--- schema.org 的 "A software application." 近得多。
-ALTER TABLE entities ADD COLUMN specific_type text;
diff --git a/migrations/0045_precision_needs_a_date.sql b/migrations/0045_precision_needs_a_date.sql
deleted file mode 100644
index 68a05ccf..00000000
--- a/migrations/0045_precision_needs_a_date.sql
+++ /dev/null
@@ -1,21 +0,0 @@
--- 没有日期的事实不该自称"精确到日"。
---
--- `valid_precision` 是 NOT NULL DEFAULT 'day',于是每一条根本没有 valid_from
--- 也没有 valid_to 的事实,都带着 'day' 落库。实测:国情咨文那个库 728 条、
--- ai-timeline 843 条——都是活行,都在说一句假话。任何按这个字段渲染
--- "精确到日" 的界面都会照着念。
---
--- 这不是显示瑕疵。这个产品卖的是"什么时候知道什么",而账本在**无知的地方
--- 填了一个确定的值**。默认值本身就是这条 bug:它让"没量过"和"量到日"
--- 长得一模一样。
---
--- 约束按**两端**写,不是只看 valid_from:全库有 144 条只有 valid_to 没有
--- valid_from("直到 2023 年"这类),它们的精度描述的是结束那一端,是真的。
-ALTER TABLE facts ALTER COLUMN valid_precision DROP DEFAULT;
-ALTER TABLE facts ALTER COLUMN valid_precision DROP NOT NULL;
-
-UPDATE facts SET valid_precision = NULL
- WHERE valid_from IS NULL AND valid_to IS NULL;
-
-ALTER TABLE facts ADD CONSTRAINT facts_precision_needs_a_date
- CHECK ((valid_from IS NULL AND valid_to IS NULL) = (valid_precision IS NULL));
diff --git a/migrations/0046_ended_when_unknown.sql b/migrations/0046_ended_when_unknown.sql
deleted file mode 100644
index 3322a71e..00000000
--- a/migrations/0046_ended_when_unknown.sql
+++ /dev/null
@@ -1,73 +0,0 @@
--- 账本说不出「结束了,但不知道哪天」。
---
--- `valid_to IS NULL` 一直承载两个意思。抽取提示词的规则 3 把它们并排写在一起:
---
--- If a relation is still ongoing, valid_to is null.
--- If the text states no date, use null — never invent dates.
---
--- 于是 "Prem Akkaraju, former CEO of Weta Digital" 这句——**结束是原文明说的,
--- 日期是原文没给的**——只能写成 null,然后被系统读成「至今仍是」。图会理直气壮
--- 地断言一件原文说已经结束的事。
---
--- 实测(ai-timeline,348 块):`valid_from` 覆盖 58.5%,`valid_to` 只有 8.6%。
--- 而语料里结束措辞不少:`former` 30 块、`left`/`departed` 13、`until` 8、
--- `stepped down`/`resigned` 7、`no longer`/`ceased` 5。**一条都落不进账本。**
---
--- 这跟 0045 修的是同一类缺陷:**时间模型没有表达无知的位置**。那次是「不知道
--- 精度」被写成「精确到日」,这次是「不知道何时结束」被写成「仍在继续」。
---
--- 顺带修掉一个一直存在的窄处:**一个精度列描述两个端点**。全库 556 条事实两端
--- 都有日期,它们的粒度只能共用一个值;另有 145 条只有 valid_to,那个列名写着
--- from、描述的却是 to。拆成按端记,两个问题一起没了。
---
--- 三种状态从此分得开:
---
--- 仍在持续 valid_to IS NULL valid_to_precision IS NULL
--- 结束了,不知哪天 valid_to IS NULL valid_to_precision = 'unknown'
--- 2023 年结束 valid_to = … valid_to_precision = 'year'
---
--- **不采用「把文档日期填进 valid_to 当上界」那种做法**(教科书里的 indeterminate
--- instant)。那会在列里放一个看起来确定的时间戳,每个读者都得先查精度才敢用它,
--- 而这个产品卖的正是不骗人。上界信息本来就能从证据的文档日期反推,需要时再说。
-
-ALTER TABLE facts RENAME COLUMN valid_precision TO valid_from_precision;
-ALTER TABLE facts ADD COLUMN valid_to_precision text;
-
--- **旧约束先撤,再动数据。** 0045 那条按「两端都没日期才没有精度」判,而下面第一个
--- UPDATE 恰恰要把「只有 valid_to」的行的起始精度置空——在旧约束眼里那是违规。
---
--- 这个顺序错误在空表上看不出来(UPDATE 影响 0 行),我第一版就是在一个全新的
--- 一次性库上验的,全绿;打到有数据的 dev 库上当场炸,145 行。
--- **迁移的验证库得有代表性的数据,不然验的只是语法。**
-ALTER TABLE facts DROP CONSTRAINT IF EXISTS facts_precision_needs_a_date;
-
--- 只有 valid_to 的那 145 条:那个精度描述的一直是结束端,搬过去而不是复制
-UPDATE facts
- SET valid_to_precision = valid_from_precision,
- valid_from_precision = NULL
- WHERE valid_from IS NULL AND valid_to IS NOT NULL;
-
--- 两端都有的 556 条:历史上只存过一个粒度,无从区分,只能同值复制。
--- 这是**回填的近似**,不是测量——从此以后两端各记各的
-UPDATE facts
- SET valid_to_precision = valid_from_precision
- WHERE valid_from IS NOT NULL AND valid_to IS NOT NULL;
-
--- 起始端:有日期才有精度,没日期就没有。没有 unknown——「开始了但不知道何时」
--- 与「不知道有没有开始」在这个账本里不可区分,硬加一个状态只会让读者猜
-ALTER TABLE facts ADD CONSTRAINT facts_from_precision_matches_date
- CHECK ((valid_from IS NULL) = (valid_from_precision IS NULL));
-
--- 结束端:多一个 unknown,且它**只在没有日期时**成立——有日期还说不知道,
--- 是自相矛盾,而约束正是用来挡住这种矛盾进库的。
---
--- 那句 `IS NOT NULL` 不是冗余的。少了它,`valid_to` 有日期而精度为 NULL 的行
--- 会**被放行**:`NULL IN ('year',…)` 求值是 NULL,`TRUE AND NULL` 是 NULL,
--- `NULL OR FALSE` 还是 NULL,而 CHECK 约束遇到 NULL 判通过。三值逻辑在这里
--- 是静默的——写完自测才发现,六个用例里就这一个漏网。
-ALTER TABLE facts ADD CONSTRAINT facts_to_precision_matches_date
- CHECK (
- (valid_to IS NOT NULL AND valid_to_precision IS NOT NULL
- AND valid_to_precision IN ('year', 'month', 'day'))
- OR (valid_to IS NULL AND (valid_to_precision IS NULL OR valid_to_precision = 'unknown'))
- );
diff --git a/migrations/0047_no_type_is_a_type.sql b/migrations/0047_no_type_is_a_type.sql
deleted file mode 100644
index f39f1e15..00000000
--- a/migrations/0047_no_type_is_a_type.sql
+++ /dev/null
@@ -1,59 +0,0 @@
--- 「还没判出来」不再是一个类,见 docs/decisions/0009。
---
--- 此前它是一行叫 concept 的哨兵。哨兵有名字,有名字就会撞——SKOS 的
--- skos:Concept 派生出的 key 正是 concept,而哨兵没有 IRI,导入逻辑
--- 「占位者没有 IRI 就认领它」会让它接管哨兵:所有未分类的实体一夜之间
--- 变成正经的 skos:Concept。不是撞名被跳过,是语义被静默改写。
---
--- NULL 没有名字,撞不着;也忘不掉——漏过滤一个哨兵不会有任何提示,
--- 漏处理一个 NULL 会当场报出来。
-
-ALTER TABLE entities ALTER COLUMN type_id DROP NOT NULL;
-
--- 挂在内置类上的实体一律回到未分类。
---
--- **不做"有实体就保留那个类"的挽救**:仓库至今没有 release,不存在要照顾的
--- 生产部署,而留一半内置类会让迁完的状态不确定——测试时分不清某个 organization
--- 是内置残留还是 schema.org 导进来的。宁可状态干净。
---
--- 顺序要紧:type_id 是 ON DELETE RESTRICT,不先解引用就删不掉类型行。
-UPDATE entities SET type_id = NULL
-WHERE type_id IN (SELECT id FROM entity_types WHERE builtin);
-
--- 关联表同理:属性的 domain 指向内置类时,那条关联也一并去掉。
--- 属性本身留着——它可能还挂在别的类上,而且描述与 IRI 都是有价值的
-DELETE FROM relation_type_domains WHERE entity_type_id IN (SELECT id FROM entity_types WHERE builtin);
-DELETE FROM relation_type_ranges WHERE entity_type_id IN (SELECT id FROM entity_types WHERE builtin);
-DELETE FROM entity_type_parents
-WHERE parent_id IN (SELECT id FROM entity_types WHERE builtin)
- OR child_id IN (SELECT id FROM entity_types WHERE builtin);
-
-
--- 合并回滚快照同样要松手。`entity_merges.target_type_before` 记的是"合并时目标
--- 实体原本是什么类",而它对 entity_types 的外键是 NO ACTION——**不置空就删不掉类**,
--- 迁移会在这里整条回滚。
---
--- 空库测不出来:没有合并历史就没有这一行。这条是在一个真有合并记录的库上撞出来的。
---
--- 置空而不是保留:这一列的原意是「concept 目标被具体类型升格」的回滚快照(见 0006),
--- 而升格的起点在 0009 之后就是「没有类」。撤销这类合并本来就该还原成没有类。
-UPDATE entity_merges SET target_type_before = NULL
-WHERE target_type_before IN (SELECT id FROM entity_types WHERE builtin);
-
--- 其余指向 entity_types 的外键都是 ON DELETE CASCADE,下面那条 DELETE 会顺手带走:
--- entity_retypes 里起点或终点是内置类的改类记录、type_refinement_pairs 里涉及
--- 内置类的认可配对。**都该走**——它们引用的类不存在了,留着也撤不回去。
--- 写在这里是因为级联删除不会有任何提示,而这是一张账本表。
-DELETE FROM entity_types WHERE builtin;
-
--- 唯一索引里 type_id 现在可能是 NULL,而 Postgres 里 NULL <> NULL——
--- 两个都没类型的同名实体不会被它拦住,可以并存。
---
--- **这是要的行为**:该索引的意图是「同类同名允许重复」(见 0001 P0 的两个张伟)。
--- 未分类时我们对它们是不是同一个东西知道得更少,更没有理由合并。
--- 写在这里是因为半年后看到「未分类的同名实体可以重复」会像个 bug。
-
--- 改类账本的起点也可能为空:类型消解现在最常见的动作正是「从没有类到有类」,
--- 而 entity_retypes 是它的撤销依据。这一列非空的话,第一次赋类就写不进账,
--- 于是那批改动不可撤——比不记账更糟
-ALTER TABLE entity_retypes ALTER COLUMN from_type_id DROP NOT NULL;
diff --git a/migrations/0048_retype_actor.sql b/migrations/0048_retype_actor.sql
deleted file mode 100644
index 649242f8..00000000
--- a/migrations/0048_retype_actor.sql
+++ /dev/null
@@ -1,10 +0,0 @@
--- 改类要能说出是谁改的。
---
--- `entity_retypes` 记了改动本身(何时、从哪个类到哪个类、撤没撤),唯独没记人。
--- 而这张表马上要出现在实体历史里(0001 P3a:「该补的是让改类在实体历史里显形」),
--- 一条写着「Vehicle ← 未分类」却不说谁干的记录,比不显示更容易被误读成引擎所为。
---
--- 可空 = 引擎自动裁决,跟 `entity_merges.merged_by` 已有的约定一字不差
--- (那边的注释写着「NULL = 自动合并(LLM 裁决高置信)」)。不给默认值:
--- 已有的行确实不知道是谁,编一个出来就是伪造归因。
-ALTER TABLE entity_retypes ADD COLUMN actor_id UUID REFERENCES users(id);
diff --git a/migrations/0050_label_embedding.sql b/migrations/0050_label_embedding.sql
deleted file mode 100644
index 5afdab26..00000000
--- a/migrations/0050_label_embedding.sql
+++ /dev/null
@@ -1,30 +0,0 @@
--- 类的**第二个**向量:只嵌 label,不带描述。
---
--- 类型消解对每个实体发两种查询(见 `type_resolution.rs`):一种是模型自己给的
--- 说法(`district. place`,短),一种是整段画像(长)。两种此前比的是同一批
--- `label + description` 向量——**查询分了两种形状,文档只有一种**。
---
--- 后果是短查询被同义反复的类接管。实测「杭州拱墅区」(specific_type = district)
--- 的短查询回来的是:
---
--- Map(0.308) / Park(0.345) / Country(0.347) / Museum(0.356)
---
--- 四个赢家的嵌入原文分别是 `Map\nA map.`、`Park\nA park.`、`Country\nA country.`、
--- `Museum\nA museum.`——全是一行同义反复。而正确答案 AdministrativeArea 的原文是
--- `AdministrativeArea\nA geographical region, typically under the jurisdiction of a
--- particular government.`,一百字,排不进前八。
---
--- 不是语义更近,是**长度对上了**。整体测得:被检索出来的类,嵌入原文长度中位数
--- 44,而全部 965 个类的中位数是 89——检索系统性地偏好短文本。
---
--- 「短的那一侧距离系统性地更小」这条规律,本仓库已经栽过四次(跨实体不可比、
--- 两路之间不可比、同一路两个查询之间不可比、空描述的悬空类占便宜)。前四次修的
--- 都是查询一侧,这一次是文档一侧:**两种查询就该有两份文档**,短对短、长对长。
-ALTER TABLE entity_types ADD COLUMN label_embedding vector;
-
--- 与 `embedded_text` / `embedded_model` 同一套自愈判据(见 0038):比对「当时嵌的
--- 原文与模型名跟现在对不对得上」,而不是看时间戳。改了 label、换了嵌入模型都会
--- 当场对不上,于是自动重嵌——不必在每个改 label 的写入点挂钩子,漏挂一个就悄悄烂掉。
-ALTER TABLE entity_types
- ADD COLUMN label_embedded_text text,
- ADD COLUMN label_embedded_model text;
diff --git a/migrations/0051_type_source.sql b/migrations/0051_type_source.sql
deleted file mode 100644
index 9ae58547..00000000
--- a/migrations/0051_type_source.sql
+++ /dev/null
@@ -1,43 +0,0 @@
--- 人定过的类型,引擎不许改。
---
--- `entity_retypes` 记得住「谁改的」(0048 加的 `actor_id`),但那是**事后**的账。
--- 保护要**事前**:实体身上得有一位说明这个类型是怎么来的,否则每一条读路径都
--- 只能看见 `type_id`,看不见它背后有没有人拍过板。
---
--- 今天的漏在类型消解那条路上。`entities_for_type_resolution` 的取材条件是:
---
--- AND (e.type_id IS NULL OR e.proposed_type IS NOT NULL
--- OR e.specific_type IS NOT NULL
--- OR EXISTS (SELECT 1 FROM entity_type_parents p WHERE p.parent_id = t.id))
---
--- 最后那行意味着:**人工定成 `organization` 的实体,只要 `organization` 有子类,
--- 下一轮消解照样把它拿去重判。** 抽取那条路有守卫(`resolve_type_drift` 只在
--- `type_key.is_none()` 时升格),消解这条没有。
---
--- 0009 之后还多了一种情形:「没有类型」现在可能是**人的决定**——他看过这个实体,
--- 认为本体里没有合适的类。而 `type_id IS NULL` 分不出「还没判」和「人判了,
--- 就是没有」,于是下一次抽取会给它安一个类型。这一条 0001 写不出来,因为 0009
--- 比它晚三天。
---
--- 三个取值的分工:
---
--- extracted 抽取判出来的(`resolve_type_drift` 的升格)
--- inferred 引擎裁决的(类型消解、本体长出新类后的认领)
--- human 人拍板的(实体面板直改、审核队列里点批准)
---
--- `inferred` 与 `extracted` 分开而不是合成一个「非人」:它们的可信度不同,
--- 将来若要「引擎可以改引擎的,但不能改抽取的」,判据现成。
-
-ALTER TABLE entities ADD COLUMN type_source TEXT NOT NULL DEFAULT 'extracted'
- CHECK (type_source IN ('extracted', 'human', 'inferred'));
-
--- 回填**不靠猜**:审计台账里的 entity.retyped 带 actor_id 与 target_id,
--- 那是人在实体面板上改类型时留下的唯一痕迹(那条路至今不写 entity_retypes)。
---
--- 更早的引擎改类无从追溯——`entity_retypes.actor_id` 是 0048 才有的,之前的行
--- 分不出人机。所以默认值取 `extracted`:**承认不知道,而不是断言没人碰过**。
-UPDATE entities e SET type_source = 'human'
- WHERE EXISTS (
- SELECT 1 FROM audit_events a
- WHERE a.action = 'entity.retyped' AND a.target_id = e.id
- );
diff --git a/migrations/0052_no_relation_is_no_relation.sql b/migrations/0052_no_relation_is_no_relation.sql
deleted file mode 100644
index 4d00033c..00000000
--- a/migrations/0052_no_relation_is_no_relation.sql
+++ /dev/null
@@ -1,48 +0,0 @@
--- 「说不出是什么关系」不该是一种关系。
---
--- 与 0009 对 `concept` 做的事同构。`related_to` 编码的是**抽取器抽到了一条边,
--- 但本体里没有对应的关系**——那是控制流,不是词汇。它却以 `builtin` 关系的身份
--- 躺在 `relation_types` 里,在本体页上跟真关系并排列着。
---
--- 证据在删之前量过:某个 348 块的库里 533 条事实挂在 `related_to` 上,
--- **533 条全部带着原文说法**(`fact_evidence.proposed_predicate`),一条不落。
--- 所以删掉它一个字的信息都不丢——原意一直存在证据里,被那行假词汇盖着而已。
---
--- 而且删掉之后**信息更多**:今天这 533 条边统统显示"有关联",
--- 之后各自显示原文说的 `acquired` / `runs_on` / `sued`。同一份数据,读者看得见的
--- 从一个词变成五百多个词。
---
--- 一条事实带多种说法的只占 3.0%(16/533),所以"显示哪一个"不是拦路虎:
--- 取出现最多的那个,与 `predicate_match::merge_key` 挑规范 key 同一个规矩。
---
--- **有 420 条例外,全是历史遗留。** 全库 5934 条兜底事实里,420 条拿不出原文说法,
--- 而它们**全部**来自 `Industry Corpus`(275) 与 `General`(145) 两个最早的库——
--- 那时 `add_evidence` 还没无条件记录 `proposed_predicate`。8 月 30 日之后建的库
--- 一条都没有。这类事实改完会显示成空,但它们本来显示的是"有关联",
--- 信息量同样是零,没有变糟。
---
--- **数据直接改,不做搬迁**:现在库里全是测试数据,产品未发布。
-
-ALTER TABLE facts ALTER COLUMN predicate_id DROP NOT NULL;
-
-UPDATE facts SET predicate_id = NULL
- WHERE predicate_id IN (SELECT id FROM relation_types WHERE key = 'related_to');
-
-DELETE FROM relation_types WHERE key = 'related_to';
-
--- 没有谓词的事实**显示什么**。
---
--- 做成函数而不是在每条读查询里塞一段子查询:读事实的路径有六条以上
---(图的边、实体面板、变更历史、低置信审核、文档产出、消解画像),
--- 六份同样的 SQL 迟早分叉,而分叉在这里的后果是同一条边在不同页面上叫不同的名字。
---
--- **确定性**:出现次数相同时按字典序,所以同一条事实每次显示同一个词。
-CREATE FUNCTION fact_surface_predicate(fact uuid) RETURNS text
-LANGUAGE sql STABLE AS $$
- SELECT e.proposed_predicate
- FROM fact_evidence e
- WHERE e.fact_id = fact AND e.proposed_predicate IS NOT NULL
- GROUP BY e.proposed_predicate
- ORDER BY count(*) DESC, e.proposed_predicate
- LIMIT 1
-$$;
diff --git a/migrations/0053_the_seed_grew_it_back.sql b/migrations/0053_the_seed_grew_it_back.sql
deleted file mode 100644
index 2ec32821..00000000
--- a/migrations/0053_the_seed_grew_it_back.sql
+++ /dev/null
@@ -1,25 +0,0 @@
--- 0052 删掉了 `related_to`,代码七分钟后把它种了回来。
---
--- 迁移改的是**数据**,而种子关系是**代码**:`graph.rs` 的 `DEFAULT_RELATION_TYPES`
--- 里那一行还在,`ensure_default_ontology` 在建库、看本体页、**每次抽取**时都会跑,
--- 于是 `ON CONFLICT (kb_id, key)` 找不到行就重新插一条。实测账本:
---
--- 0052 应用于 08-30 17:54 → 全库 related_to 归零
--- bench demo-autoextend → 08-30 18:01 又长出一条 builtin=true
---
--- 比"没删干净"更糟的是第二层:0052 同时删掉了抽取提示词里那条排除过滤
---(当时的理由是"行都没有了,不需要记得别列它")。行既然还在,结果就是
--- `related_to` **第一次被列进提示词给模型看**。0001 量过这件事的代价:
--- 359 次使用里 321 次是模型从清单上挑的,只有约 38 次是代码降级——
--- 逃生舱一旦摆上台面,模型就不再去说原文究竟说了什么。
---
--- 代码那半边这次一起改了(种子表与中文表里的 related_to 都已删除)。
--- 这条迁移只负责把已经长回来的行清掉。
---
--- **只删 builtin 的。** 谁想自己建一个叫 related_to 的关系是他的自由——
--- 那是一个人做的决定,与这里要消灭的"程序状态伪装成词汇"是两回事。
-
-UPDATE facts SET predicate_id = NULL
- WHERE predicate_id IN (SELECT id FROM relation_types WHERE key = 'related_to' AND builtin);
-
-DELETE FROM relation_types WHERE key = 'related_to' AND builtin;
diff --git a/migrations/0054_owl_axioms.sql b/migrations/0054_owl_axioms.sql
deleted file mode 100644
index 75b4c7bf..00000000
--- a/migrations/0054_owl_axioms.sql
+++ /dev/null
@@ -1,44 +0,0 @@
--- 本体自己声明的公理落库,给一致性检查当判定依据(0002 R0)。
---
--- 解析那一步已经做完(#121):`TransitiveProperty` / `SymmetricProperty` /
--- `AsymmetricProperty` / `IrreflexiveProperty` / `disjointWith` 现在都投影得出来,
--- 但字段只活在内存里,投影完就丢。这个迁移给它们腾位置。
---
--- **为什么非要有它们**:开发库里 143 对双向事实,`alias_of` 那 14 条是**对的**
--- (别名本来就双向),`produces` 那 88 条几乎肯定是错的。区分这两者的东西只能
--- 来自本体——没有公理,一致性检查就只能拿启发式冒充判定,而 0001 判据 2
--- 写着「本体是引导不是执法」,0002 的整个立论是「用公理裁决」。
-
--- 属性公理。跟 `functional` / `inverse_functional` 并排——它们本来就是同一族,
--- 只是那两个先落库了。
---
--- **默认 false 而不是 NULL**:OWL 是开放世界,但一致性检查只能按写下来的判。
--- 「没声明」与「声明为否」在这里后果相同——都不构成报矛盾的依据——所以不必
--- 用三态去区分一个不影响行为的差别。
--- **列名带 is_ 前缀不是风格洁癖**:`symmetric` 与 `asymmetric` 都是 Postgres
--- 保留字(`BETWEEN SYMMETRIC`),裸用会在 `ADD COLUMN` 那一行就报语法错。
--- 加引号能绕过去,但那要求之后每一处写这两列的 SQL 都记得加——漏一处就是
--- 运行时才炸。改名一次,后面都不必记。
-ALTER TABLE relation_types
- ADD COLUMN is_transitive BOOLEAN NOT NULL DEFAULT FALSE,
- ADD COLUMN is_symmetric BOOLEAN NOT NULL DEFAULT FALSE,
- ADD COLUMN is_asymmetric BOOLEAN NOT NULL DEFAULT FALSE,
- ADD COLUMN is_irreflexive BOOLEAN NOT NULL DEFAULT FALSE;
-
--- 类互斥。**存成一张表而不是数组列**:要查的问题是「A 与 B 互斥吗」,
--- 那是一次点查;数组列查起来要么全表扫要么建 GIN,而这里的语义就是一条边。
---
--- 与 `entity_type_parents` 同构——同样是类与类之间的一条关系。
-CREATE TABLE entity_type_disjoint (
- kb_id UUID NOT NULL REFERENCES knowledge_bases(id) ON DELETE CASCADE,
- a_id UUID NOT NULL REFERENCES entity_types(id) ON DELETE CASCADE,
- b_id UUID NOT NULL REFERENCES entity_types(id) ON DELETE CASCADE,
- -- 两个方向各存一行(导入侧已经把公理的对称性展开了)。主键因此天然去重,
- -- 而查询不必关心调用方从哪一头问
- PRIMARY KEY (kb_id, a_id, b_id),
- -- 自己跟自己互斥是无意义的声明,挡在门口比留着让检查去猜好
- CHECK (a_id <> b_id)
-);
-
--- 「跟这个类互斥的有哪些」是唯一的查法(一致性检查拿实体的类去问)
-CREATE INDEX entity_type_disjoint_a_idx ON entity_type_disjoint (kb_id, a_id);
diff --git a/migrations/0056_users_can_be_retired.sql b/migrations/0056_users_can_be_retired.sql
deleted file mode 100644
index 46ee6213..00000000
--- a/migrations/0056_users_can_be_retired.sql
+++ /dev/null
@@ -1,24 +0,0 @@
--- 管理员可以停用一个账号。**软删除,不是 DELETE。**
---
--- 硬删删不掉:审计事件、合并日志、改类账本、口径确认——它们的 `actor_id`
--- 指着这个人,而那些记录是审计材料,人走了仍然要能回答「当时是谁做的」。
--- 真去 DELETE 只有两个结果:要么被外键挡住(那些列是裸外键),要么级联把
--- 审计一起删掉。两个都不是我们要的。
---
--- 所以停用 = 打一个时间戳。**归因保住,访问断掉**。
-ALTER TABLE users ADD COLUMN deactivated_at TIMESTAMPTZ;
-
--- 谁停的。同样是裸外键——停用者自己也可能被停用,而那条记录还得在
-ALTER TABLE users ADD COLUMN deactivated_by UUID REFERENCES users(id);
-
--- **唯一的 email 约束要放停用的账号一马。**
---
--- 从前 email 是全表唯一。停用之后那个地址还占着位置,于是同一个人回来、
--- 或者同一个邮箱转给别人,都建不了新账号——而「停用」不该等于「这个邮箱
--- 永久报废」。改成部分唯一索引:只约束在职的。
---
--- 代价写在前面:停用过的账号里可以有重复 email,`find_user_by_email`
--- 因此必须带 `deactivated_at IS NULL`——它本来就要带(不然停用的人还能登录),
--- 这里只是让那一句同时也是正确性的保证,而不只是权限的。
-ALTER TABLE users DROP CONSTRAINT IF EXISTS users_email_key;
-CREATE UNIQUE INDEX users_email_active_idx ON users (email) WHERE deactivated_at IS NULL;