World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
//! 业务规则的存取(0021 / #277)。求值在 `utopia-reason::rules`,接进物化在
//! `reasoning::materialize`;这里只管「人写下来的那几条规则怎么进库、怎么取回」。
//!
//! **判据是人写的。** 这个模块没有任何一处由模型生成规则的入口——与 0002 对
//! 公理的态度同一条线。
use serde_json::json;
use sqlx::PgPool;
use utopia_core::{AppError, AppResult};
use uuid::Uuid;
/// 内建 `is_a` 谓词:派生归类的结论落在它上面(0021 决策 2)。
///
/// **按需建,不在建库时铺。** 一个从不写规则的库不该多出一个它看不懂的谓词
/// ——与 #231 给 `metric` / `dimension` 做的选择一致。
pub async fn ensure_is_a(pool: &PgPool, kb_id: Uuid) -> AppResult<Uuid> {
if let Some((id,)) =
sqlx::query_as::<_, (Uuid,)>("SELECT id FROM relation_types WHERE kb_id = $1 AND key = $2")
.bind(kb_id)
.bind(IS_A)
.fetch_optional(pool)
.await?
{
return Ok(id);
}
let id = Uuid::now_v7();
sqlx::query(
"INSERT INTO relation_types (id, kb_id, key, label, kind, datatype, builtin, description)
VALUES ($1, $2, $3, 'is a', 'attribute', 'text', TRUE, $4)
ON CONFLICT (kb_id, key) DO NOTHING",
)
.bind(id)
.bind(kb_id)
.bind(IS_A)
.bind("A class a rule concluded for this entity. Derived, and it never replaces the asserted type.")
.execute(pool)
.await?;
// ON CONFLICT 命中说明并发建过了,取回那一条
let (id,): (Uuid,) =
sqlx::query_as("SELECT id FROM relation_types WHERE kb_id = $1 AND key = $2")
.bind(kb_id)
.bind(IS_A)
.fetch_one(pool)
.await?;
Ok(id)
}
pub const IS_A: &str = "is_a";
#[derive(sqlx::FromRow)]
struct RuleRow {
id: Uuid,
/// 当前定义是第几版(0060)。迁移给每条老规则补了第 1 版,所以总有
version: Option<i32>,
name: String,
description: String,
subject_type_id: Uuid,
subject_label: Option<String>,
conclusion: String,
conclude_type_id: Option<Uuid>,
conclude_type_label: Option<String>,
conclude_predicate_id: Option<Uuid>,
conclude_predicate_label: Option<String>,
conclude_value: Option<serde_json::Value>,
conclude_expr: Option<serde_json::Value>,
enabled: bool,
join_predicate_id: Option<Uuid>,
join_predicate_label: Option<String>,
derived_count: i64,
capped: i32,
}
/// 条件查询回来的一行:规则、组号、属性谓词及其标签、比较方式、操作数
type ConditionRow = (
Uuid,
i32,
Uuid,
Option<String>,
String,
Option<serde_json::Value>,
String,
);
/// 一条条件,界面与 API 共用的形状。
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct ConditionInput {
/// 组号:同组「与」,组间「或」(0029)。**缺省 0**——不带组的调用方
/// 送来的就是一组合取,与从前一模一样
#[serde(default)]
pub group: i32,
pub predicate_id: Uuid,
pub op: String,
#[serde(default)]
pub operand: Option<serde_json::Value>,
/// Which side of a joined pair this condition reads: `x` is the rule
/// subject and `y` is the entity reached by the one declared join edge.
#[serde(default = "default_condition_side")]
pub side: String,
}
fn default_condition_side() -> String {
"x".to_string()
}
fn validate_name(name: &str) -> AppResult<&str> {
let name = name.trim();
if name.is_empty() || name.chars().count() > 80 {
return Err(AppError::invalid(
"bad_rule_name",
"A rule needs a name of 1-80 characters.",
));
}
Ok(name)
}
/// 建一条规则。**校验在这里做完**:条件的 op 与操作数形状、谓词必须是属性、
/// 结论的两种形状各自完整——库里的 CHECK 是最后一道,报错信息却是给人看的。
#[allow(clippy::too_many_arguments)]
pub async fn create(
pool: &PgPool,
kb_id: Uuid,
name: &str,
description: &str,
subject_type_id: Uuid,
conclusion: &str,
conclude_type_id: Option<Uuid>,
conclude_predicate_id: Option<Uuid>,
conclude_value: Option<serde_json::Value>,
// 算出来的结论那棵树(0032)
conclude_expr: Option<serde_json::Value>,
join_predicate_id: Option<Uuid>,
conditions: &[ConditionInput],
) -> AppResult<Uuid> {
let name = validate_name(name)?;
if conditions.is_empty() {
// 空合取恒真,会把整个类归进去——挡在入口比在求值器里默默不推更早
return Err(AppError::invalid(
"no_conditions",
"A rule needs at least one condition; without one it would conclude for every entity of the class.",
));
}
validate_conditions(pool, kb_id, conditions, conclusion == "relation").await?;
validate_conclusion(
pool,
kb_id,
&ConclusionInput {
kind: conclusion.to_string(),
type_id: conclude_type_id,
predicate_id: conclude_predicate_id,
value: conclude_value.clone(),
expr: conclude_expr.clone(),
join_predicate_id,
},
)
.await?;
validate_join_shape(conclusion, join_predicate_id)?;
exists(
pool,
kb_id,
"entity_types",
subject_type_id,
"unknown_class",
"That class is not in this base.",
)
.await?;
let id = Uuid::now_v7();
let mut tx = pool.begin().await?;
sqlx::query(
"INSERT INTO attribute_rules
(id, kb_id, name, description, subject_type_id, conclusion,
conclude_type_id, conclude_predicate_id, conclude_value, conclude_expr,
join_predicate_id)
VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)",
)
.bind(id)
.bind(kb_id)
.bind(name)
.bind(description.trim())
.bind(subject_type_id)
.bind(conclusion)
.bind(conclude_type_id)
.bind(conclude_predicate_id)
.bind(&conclude_value)
.bind(&conclude_expr)
.bind(join_predicate_id)
.execute(&mut *tx)
.await
.map_err(|e| match e {
sqlx::Error::Database(ref d) if d.is_unique_violation() => AppError::invalid(
"duplicate_rule",
"A rule with that name already exists here.",
),
other => AppError::Db(other),
})?;
insert_conditions(&mut tx, id, conditions).await?;
record_version(&mut tx, kb_id, id).await?;
tx.commit().await?;
Ok(id)
}
/// 改一条规则:条件整组替换。
///
/// **不做逐条的增删改**——条件是一个合取整体,替换比对着 seq 打补丁好读,
/// 也没有「改到一半」的中间状态。
/// 结论的一次改写。**两种形状各自完整地给**,不做「只改类、别的不动」——
/// 结论的三格是互相定义的,部分更新会留下 typing 却带着值这种半截状态。
pub struct ConclusionInput {
/// typing | attribute | computed
pub kind: String,
pub type_id: Option<Uuid>,
pub predicate_id: Option<Uuid>,
pub value: Option<serde_json::Value>,
/// 算出来的结论那棵树(0032)。`computed` 时必给,别的两支必空
pub expr: Option<serde_json::Value>,
/// X --join--> Y 的那条边,只在 relation 结论时非空
pub join_predicate_id: Option<Uuid>,
}
#[allow(clippy::too_many_arguments)]
pub async fn update(
pool: &PgPool,
kb_id: Uuid,
rule_id: Uuid,
name: Option<&str>,
description: Option<&str>,
enabled: Option<bool>,
conditions: Option<&[ConditionInput]>,
conclusion: Option<&ConclusionInput>,
) -> AppResult<()> {
let name = name.map(validate_name).transpose()?;
if let Some(cs) = conditions {
if cs.is_empty() {
return Err(AppError::invalid(
"no_conditions",
"A rule needs at least one condition.",
));
}
let (old_conclusion, old_join) = sqlx::query_as::<_, (String, Option<Uuid>)>(
"SELECT conclusion, join_predicate_id
FROM attribute_rules
WHERE id = $2 AND kb_id = $1",
)
.bind(kb_id)
.bind(rule_id)
.fetch_optional(pool)
.await?
.ok_or(AppError::NotFound)?;
let joined = conclusion
.map(|c| c.kind.as_str() == "relation")
.unwrap_or(old_conclusion == "relation");
validate_conditions(pool, kb_id, cs, joined).await?;
let join = if joined {
conclusion.and_then(|c| c.join_predicate_id).or(old_join)
} else {
None
};
validate_join_shape(if joined { "relation" } else { "other" }, join)?;
}
if let Some(c) = conclusion {
validate_conclusion(pool, kb_id, c).await?;
validate_join_shape(&c.kind, c.join_predicate_id)?;
}
let mut tx = pool.begin().await?;
let res = sqlx::query(
// 结论给了就整组换(三格一起),没给就一格不动——COALESCE 在这里
// 不够用:把 typing 改成 attribute 要把 conclude_type_id 置回 NULL,
// 而 COALESCE 恰恰做不到「显式清空」
"UPDATE attribute_rules
SET name = COALESCE($3, name),
description = COALESCE($4, description),
enabled = COALESCE($5, enabled),
conclusion = COALESCE($6, conclusion),
conclude_type_id = CASE WHEN $6 IS NULL THEN conclude_type_id ELSE $7 END,
conclude_predicate_id = CASE WHEN $6 IS NULL THEN conclude_predicate_id ELSE $8 END,
conclude_value = CASE WHEN $6 IS NULL THEN conclude_value ELSE $9 END,
conclude_expr = CASE WHEN $6 IS NULL THEN conclude_expr ELSE $10 END,
join_predicate_id = CASE WHEN $6 IS NULL THEN join_predicate_id ELSE $11 END,
updated_at = now()
WHERE id = $2 AND kb_id = $1",
)
.bind(kb_id)
.bind(rule_id)
.bind(name)
.bind(description.map(str::trim))
.bind(enabled)
.bind(conclusion.map(|c| c.kind.as_str()))
.bind(conclusion.and_then(|c| c.type_id))
.bind(conclusion.and_then(|c| c.predicate_id))
.bind(conclusion.and_then(|c| c.value.clone()))
.bind(conclusion.and_then(|c| c.expr.clone()))
.bind(conclusion.and_then(|c| c.join_predicate_id))
.execute(&mut *tx)
.await?;
if res.rows_affected() == 0 {
return Err(AppError::NotFound);
}
if let Some(cs) = conditions {
sqlx::query("DELETE FROM attribute_rule_conditions WHERE rule_id = $1")
.bind(rule_id)
.execute(&mut *tx)
.await?;
insert_conditions(&mut tx, rule_id, cs).await?;
}
if conditions.is_some() || conclusion.is_some() {
// 在持有规则行锁的事务内校验最终条件,保留条件和并发更新都不能绕过。
let reads_y_without_join: bool = sqlx::query_scalar(
"SELECT EXISTS (
SELECT 1 FROM attribute_rules r
JOIN attribute_rule_conditions c ON c.rule_id = r.id
WHERE r.kb_id = $1 AND r.id = $2
AND r.join_predicate_id IS NULL AND c.subject_side = 'y'
)",
)
.bind(kb_id)
.bind(rule_id)
.fetch_one(&mut *tx)
.await?;
if reads_y_without_join {
return Err(AppError::invalid(
"condition_side_without_join",
"Only a joined rule can read the other side of an edge.",
));
}
}
// 定义变了才开新版本;改名、改描述、开关不算(0060)
record_version(&mut tx, kb_id, rule_id).await?;
tx.commit().await?;
Ok(())
}
/// 定义的快照(0060):规则说了什么——主类、结论那几格、连接谓词、条件。名字、
/// 描述和开关不在其中,它们是标签和开关,改了不等于规则换了说法。
///
/// **与迁移 0076 里回填第 1 版的表达式一字不差**:版本变没变是拿这份 JSON 比出来的,
/// 两处形状不一样就会把没改的规则也开成新版本
const DEFINITION_SQL: &str = "jsonb_build_object(
'subject_type_id', r.subject_type_id,
'conclusion', r.conclusion,
'conclude_type_id', r.conclude_type_id,
'conclude_predicate_id', r.conclude_predicate_id,
'conclude_value', r.conclude_value,
'conclude_expr', r.conclude_expr,
'join_predicate_id', r.join_predicate_id,
'conditions', COALESCE((SELECT jsonb_agg(jsonb_build_object(
'group', c.group_seq, 'seq', c.seq, 'side', c.subject_side,
'predicate_id', c.predicate_id, 'op', c.op, 'operand', c.operand)
ORDER BY c.group_seq, c.seq)
FROM attribute_rule_conditions c WHERE c.rule_id = r.id), '[]'::jsonb))";
/// 定义变了就开新版本:关掉当前的,序号加一。没变什么都不做。回当前版本的 id。
///
/// 在写规则的同一个事务里跑:定义和它的版本要么一起落,要么一起不落
async fn record_version(
tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
kb_id: Uuid,
rule_id: Uuid,
) -> AppResult<Uuid> {
let now: serde_json::Value = sqlx::query_scalar(&format!(
"SELECT {DEFINITION_SQL} FROM attribute_rules r WHERE r.id = $1"
))
.bind(rule_id)
.fetch_one(&mut **tx)
.await?;
let current: Option<(Uuid, i32, serde_json::Value)> = sqlx::query_as(
"SELECT id, seq, definition FROM attribute_rule_versions
WHERE rule_id = $1 AND superseded_at IS NULL",
)
.bind(rule_id)
.fetch_optional(&mut **tx)
.await?;
let seq = match current {
Some((id, _, definition)) if definition == now => return Ok(id),
Some((id, seq, _)) => {
sqlx::query("UPDATE attribute_rule_versions SET superseded_at = now() WHERE id = $1")
.bind(id)
.execute(&mut **tx)
.await?;
seq + 1
}
None => 1,
};
let id = Uuid::now_v7();
sqlx::query(
"INSERT INTO attribute_rule_versions (id, kb_id, rule_id, seq, definition)
VALUES ($1, $2, $3, $4, $5)",
)
.bind(id)
.bind(kb_id)
.bind(rule_id)
.bind(seq)
.bind(&now)
.execute(&mut **tx)
.await?;
Ok(id)
}
/// 一版:id、序号、定义、记录时间起止、此刻凭它成立的结论条数
type VersionRow = (
Uuid,
i32,
serde_json::Value,
chrono::DateTime<chrono::Utc>,
Option<chrono::DateTime<chrono::Utc>>,
i64,
);
/// 一条规则的定义史,新的在前(0060)。每一版带它的记录时间起止、此刻凭它成立的
/// 结论条数,和定义里提到的类与谓词的标签——历史里的 id 可能已经改名甚至删掉,
/// 标签按现在能查到的给,查不到的界面显示 id
pub async fn versions(
pool: &PgPool,
kb_id: Uuid,
rule_id: Uuid,
) -> AppResult<Vec<serde_json::Value>> {
let rows: Vec<VersionRow> = sqlx::query_as(
"SELECT v.id, v.seq, v.definition, v.recorded_at, v.superseded_at,
(SELECT count(*) FROM derived_facts d
WHERE d.attribute_rule_version_id = v.id AND d.invalidated_at IS NULL)
FROM attribute_rule_versions v
WHERE v.kb_id = $1 AND v.rule_id = $2
ORDER BY v.seq DESC",
)
.bind(kb_id)
.bind(rule_id)
.fetch_all(pool)
.await?;
if rows.is_empty() {
// 规则不存在,或不在这个库:两者对调用方都是 404
let known: Option<Uuid> =
sqlx::query_scalar("SELECT id FROM attribute_rules WHERE id = $2 AND kb_id = $1")
.bind(kb_id)
.bind(rule_id)
.fetch_optional(pool)
.await?;
if known.is_none() {
return Err(AppError::NotFound);
}
}
let uuid_at =
|v: &serde_json::Value, k: &str| -> Option<Uuid> { v.get(k)?.as_str()?.parse().ok() };
let mut classes: Vec<Uuid> = Vec::new();
let mut predicates: Vec<Uuid> = Vec::new();
for (_, _, d, _, _, _) in &rows {
classes.extend(uuid_at(d, "subject_type_id"));
classes.extend(uuid_at(d, "conclude_type_id"));
predicates.extend(uuid_at(d, "conclude_predicate_id"));
predicates.extend(uuid_at(d, "join_predicate_id"));
for c in d
.get("conditions")
.and_then(|c| c.as_array())
.into_iter()
.flatten()
{
predicates.extend(uuid_at(c, "predicate_id"));
}
}
let mut labels: serde_json::Map<String, serde_json::Value> = serde_json::Map::new();
for (table, ids) in [("entity_types", classes), ("relation_types", predicates)] {
if ids.is_empty() {
continue;
}
let found: Vec<(Uuid, String)> =
sqlx::query_as(&format!("SELECT id, label FROM {table} WHERE id = ANY($1)"))
.bind(&ids)
.fetch_all(pool)
.await?;
for (id, label) in found {
labels.insert(id.to_string(), serde_json::Value::String(label));
}
}
Ok(rows
.into_iter()
.map(
|(id, seq, definition, recorded_at, superseded_at, derived_count)| {
json!({
"id": id,
"seq": seq,
"definition": definition,
"recorded_at": recorded_at,
"superseded_at": superseded_at,
"derived_count": derived_count,
"labels": labels,
})
},
)
.collect())
}
/// 删一条规则。它推出来的派生行随 `ON DELETE CASCADE` 一起走——**规则没了,
/// 凭它得出的结论就没有依据了**,留着无从解释。
pub async fn delete(pool: &PgPool, kb_id: Uuid, rule_id: Uuid) -> AppResult<()> {
let res = sqlx::query("DELETE FROM attribute_rules WHERE id = $2 AND kb_id = $1")
.bind(kb_id)
.bind(rule_id)
.execute(pool)
.await?;
if res.rows_affected() == 0 {
return Err(AppError::NotFound);
}
Ok(())
}
/// 列出规则,连同条件与「现在推出了多少条」。
pub async fn list(pool: &PgPool, kb_id: Uuid) -> AppResult<Vec<serde_json::Value>> {
let rules: Vec<RuleRow> = sqlx::query_as(
"SELECT r.id, r.name, r.description, r.subject_type_id,
st.label AS subject_label,
r.conclusion, r.conclude_type_id, ct.label AS conclude_type_label,
r.conclude_predicate_id, cp.label AS conclude_predicate_label,
r.conclude_value, r.conclude_expr, r.enabled,
r.join_predicate_id, jp.label AS join_predicate_label,
(SELECT v.seq FROM attribute_rule_versions v
WHERE v.rule_id = r.id AND v.superseded_at IS NULL) AS version,
(SELECT count(*) FROM derived_facts d
WHERE d.attribute_rule_id = r.id AND d.invalidated_at IS NULL)
AS derived_count,
r.capped_at_last_run AS capped
FROM attribute_rules r
JOIN entity_types st ON st.id = r.subject_type_id
LEFT JOIN entity_types ct ON ct.id = r.conclude_type_id
LEFT JOIN relation_types cp ON cp.id = r.conclude_predicate_id
LEFT JOIN relation_types jp ON jp.id = r.join_predicate_id
WHERE r.kb_id = $1
ORDER BY r.created_at",
)
.bind(kb_id)
.fetch_all(pool)
.await?;
if rules.is_empty() {
return Ok(Vec::new());
}
let ids: Vec<Uuid> = rules.iter().map(|r| r.id).collect();
let conds: Vec<ConditionRow> = sqlx::query_as(
"SELECT c.rule_id, c.group_seq, c.predicate_id, p.label, c.op, c.operand,
c.subject_side
FROM attribute_rule_conditions c
JOIN relation_types p ON p.id = c.predicate_id
WHERE c.rule_id = ANY($1)
ORDER BY c.rule_id, c.group_seq, c.seq",
)
.bind(&ids)
.fetch_all(pool)
.await?;
Ok(rules
.into_iter()
.map(|r| {
let conditions: Vec<serde_json::Value> = conds
.iter()
.filter(|c| c.0 == r.id)
.map(|(_, group, pid, plabel, op, operand, side)| {
json!({
"group": group,
"side": side,
"predicate_id": pid,
"predicate_label": plabel,
"op": op,
"operand": operand,
})
})
.collect();
json!({
"id": r.id,
"name": r.name,
"description": r.description,
"subject_type_id": r.subject_type_id,
"subject_label": r.subject_label,
"conclusion": r.conclusion,
"conclude_type_id": r.conclude_type_id,
"conclude_type_label": r.conclude_type_label,
"conclude_predicate_id": r.conclude_predicate_id,
"conclude_predicate_label": r.conclude_predicate_label,
"conclude_value": r.conclude_value,
"conclude_expr": r.conclude_expr,
"join_predicate_id": r.join_predicate_id,
"join_predicate_label": r.join_predicate_label,
"enabled": r.enabled,
"version": r.version.unwrap_or(1),
"derived_count": r.derived_count,
"capped": r.capped,
"conditions": conditions,
})
})
.collect())
}
/// Read-only descriptions of stored computation trees. Reuse the write-side
/// shape/depth check, then resolve every leaf in one query scoped to this base.
/// Invalid trees or unavailable attributes are reported as unavailable, not null.
pub async fn describe_expressions(
pool: &PgPool,
kb_id: Uuid,
expressions: &[&serde_json::Value],
) -> AppResult<Vec<Option<String>>> {
let reads: Vec<_> = expressions.iter().map(|e| validate_expr(e).ok()).collect();
let mut ids: Vec<Uuid> = reads.iter().flatten().flatten().copied().collect();
ids.sort();
ids.dedup();
let mut names = std::collections::HashMap::new();
if !ids.is_empty() {
let rows: Vec<(Uuid, String, String)> = sqlx::query_as(
"SELECT id, key, label FROM relation_types WHERE kb_id=$1 AND id=ANY($2)",
)
.bind(kb_id)
.bind(&ids)
.fetch_all(pool)
.await?;
for (id, key, label) in rows {
// Keys keep distinct attributes identifiable even when labels coincide.
let name = if label.is_empty() || label == key {
key
} else {
format!("{label} [{key}]")
};
names.insert(id, name);
}
}
Ok(expressions
.iter()
.zip(reads)
.map(|(e, valid)| valid.and_then(|_| expression_text(e, &names)))
.collect())
}
// Only called after validate_expr has accepted the tree and bounded its depth.
fn expression_text(
raw: &serde_json::Value,
names: &std::collections::HashMap<Uuid, String>,
) -> Option<String> {
use utopia_reason::rules::Arith;
if let Some(attr) = raw.get("attr") {
return names.get(&attr.as_str()?.parse::<Uuid>().ok()?).cloned();
}
if let Some(value) = raw.get("const") {
return Some(
value
.as_str()
.map(|s| s.trim().to_string())
.unwrap_or_else(|| value.to_string()),
);
}
let op = match Arith::parse(raw.get("op")?.as_str()?)? {
Arith::Add => "+",
Arith::Sub => "-",
Arith::Mul => "*",
Arith::Div => "/",
};
Some(format!(
"({} {op} {})",
expression_text(raw.get("l")?, names)?,
expression_text(raw.get("r")?, names)?
))
}
/// 命中查询回来的一行:派生 id、实体 id 与名字、结论、区间两端、前提的可读形态
type MatchRow = (
Uuid,
Uuid,
String,
Option<Uuid>,
Option<String>,
Option<String>,
Option<String>,
Option<chrono::DateTime<chrono::Utc>>,
Option<chrono::DateTime<chrono::Utc>>,
Option<String>,
Option<String>,
Vec<String>,
);
/// 一条规则此刻标了哪些实体。
///
/// **规则卡片上那个数字要点得动**:二十个实体还能一个个点开看,两百个就只能
/// 靠这份列表。前提也带回来——「凭哪几条读数」与结论本身同样是答案的一半。
pub async fn matches(
pool: &PgPool,
kb_id: Uuid,
rule_id: Uuid,
limit: i64,
offset: i64,
) -> AppResult<(Vec<serde_json::Value>, i64)> {
let total: (i64,) = sqlx::query_as(
"SELECT count(*) FROM derived_facts d
WHERE d.kb_id = $1 AND d.attribute_rule_id = $2 AND d.invalidated_at IS NULL",
)
.bind(kb_id)
.bind(rule_id)
.fetch_one(pool)
.await?;
let rows: Vec<MatchRow> = sqlx::query_as(
// 结论读出来要是人看的那个名字。库里存的是类的 key/IRI(归类)或
// 字面值(属性),两者都不该原样端上来
"SELECT d.id, e.id, e.canonical_name,
o.id, o.canonical_name,
COALESCE(ct.label,
d.object_value #>> '{value}',
d.object_value ->> 'class'),
rp.label,
d.valid_from, d.valid_to, d.valid_from_precision, d.valid_to_precision,
COALESCE(
(SELECT array_agg(
COALESCE(pr.label, '?') || ' = '
|| COALESCE(fd.object_value #>> '{value}',
fd.object_value #>> '{class}', '?')
ORDER BY fd.seq)
FROM derivation_premises fd
LEFT JOIN relation_types pr ON pr.id = fd.predicate_id
WHERE fd.derived_fact_id = d.id),
ARRAY[]::text[]
)
FROM derived_facts d
JOIN entities e ON e.id = d.subject_id
LEFT JOIN entities o ON o.id = d.object_id
JOIN attribute_rules ar ON ar.id = d.attribute_rule_id
LEFT JOIN entity_types ct ON ct.id = ar.conclude_type_id
LEFT JOIN relation_types rp ON rp.id = d.predicate_id
WHERE d.kb_id = $1 AND d.attribute_rule_id = $2 AND d.invalidated_at IS NULL
ORDER BY e.canonical_name, d.valid_from, d.id
LIMIT $3 OFFSET $4",
)
.bind(kb_id)
.bind(rule_id)
.bind(limit)
.bind(offset)
.fetch_all(pool)
.await?;
Ok((
rows.into_iter()
.map(
|(
id,
entity_id,
name,
object_id,
object_name,
concluded,
relation_label,
from,
to,
fp,
tp,
premises,
)| {
json!({
"derived_id": id,
"entity_id": entity_id,
"entity": name,
"object_id": object_id,
"object_entity": object_name,
"concluded": concluded,
"relation_predicate": relation_label,
"valid_from": from,
"valid_to": to,
"valid_from_precision": fp,
"valid_to_precision": tp,
"premises": premises,
})
},
)
.collect(),
total.0,
))
}
async fn insert_conditions(
tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
rule_id: Uuid,
conditions: &[ConditionInput],
) -> AppResult<()> {
// seq 在**组内**编号:(rule, group, seq) 才是一条条件的位置,两组各自从 0 起
let mut next: std::collections::HashMap<i32, i32> = std::collections::HashMap::new();
for c in conditions {
let seq = next.entry(c.group).or_insert(0);
sqlx::query(
"INSERT INTO attribute_rule_conditions
(id, rule_id, group_seq, seq, predicate_id, op, operand, subject_side)
VALUES ($1, $2, $3, $4, $5, $6, $7, $8)",
)
.bind(Uuid::now_v7())
.bind(rule_id)
.bind(c.group)
.bind(*seq)
.bind(c.predicate_id)
.bind(&c.op)
.bind(&c.operand)
.bind(&c.side)
.execute(&mut **tx)
.await?;
*seq += 1;
}
Ok(())
}
/// 结论的校验。**建与改共用这一份**——分成两处写,改一次就能绕过建时的判据,
/// 而库里的 CHECK 只会回一个约束名,读的人无从知道错在哪一格。
async fn validate_conclusion(pool: &PgPool, kb_id: Uuid, c: &ConclusionInput) -> AppResult<()> {
match c.kind.as_str() {
"typing" => {
let t = c.type_id.ok_or_else(|| {
AppError::invalid("no_class", "A typing rule needs the class it concludes.")
})?;
exists(
pool,
kb_id,
"entity_types",
t,
"unknown_class",
"That class is not in this base.",
)
.await?;
// 归类结论落在内建 is_a 上,第一次写这种规则时把它建出来
ensure_is_a(pool, kb_id).await?;
Ok(())
}
"attribute" => {
let p = c.predicate_id.ok_or_else(|| {
AppError::invalid(
"no_predicate",
"An attribute rule needs the attribute it sets.",
)
})?;
if c.value.is_none() {
return Err(AppError::invalid(
"no_value",
"An attribute rule needs the value it sets.",
));
}
attribute_predicate(pool, kb_id, p).await
}
// 算出来的属性(0032):谓词照旧要在,值换成一棵算式树
"computed" => {
let p = c.predicate_id.ok_or_else(|| {
AppError::invalid(
"no_predicate",
"A computed rule needs the attribute it sets.",
)
})?;
let Some(expr) = c.expr.as_ref() else {
return Err(AppError::invalid(
"no_expression",
"A computed rule needs the expression it computes.",
));
};
// **这几条挡在入口而不是留给求值器。** 读不懂的树在求值时只会
// 「这条规则什么都不推」,而写它的人看不见任何理由(`not_in`
// 那次就是这么丢的,见 #494)
let reads = validate_expr(expr)?;
if reads.is_empty() {
return Err(AppError::invalid(
"constant_expression",
"A computed rule that reads no attribute is a constant; set the value directly.",
));
}
for r in reads {
attribute_predicate(pool, kb_id, r).await?;
}
attribute_predicate(pool, kb_id, p).await
}
// A relation conclusion names the edge itself, so both ends are
// entities. The join edge and the conclusion may be different declared
// predicates: supplies supplies(Y, Z) can conclude upstream_of(X, Z).
"relation" => {
let p = c.predicate_id.ok_or_else(|| {
AppError::invalid(
"no_predicate",
"A relation rule needs the relation it concludes.",
)
})?;
relation_predicate(pool, kb_id, p).await
}
_ => Err(AppError::invalid(
"bad_conclusion",
"A conclusion is a typing, an attribute, a computed attribute or a relation.",
)),
}
}
/// 一棵算式树的校验,返回它读到的谓词。
///
/// **形状不对就说清哪里不对。** 库里的 CHECK 只管「computed 得有一棵树」,
/// 树自己长得对不对得在这里判——否则一棵写坏的树要等到下一次物化才表现为
/// 「这条规则不推东西」,而那时候没有任何地方说得出为什么。
fn validate_expr(raw: &serde_json::Value) -> AppResult<Vec<Uuid>> {
let expr = utopia_reason::rules::Expr::from_json(raw)
.map_err(|e| AppError::invalid(e.code(), e.message()))?;
let mut reads = Vec::new();
expr.predicates(&mut reads);
Ok(reads)
}
/// 条件的校验。**报错要说人话**:库里的 CHECK 只会回一个约束名。
async fn validate_conditions(
pool: &PgPool,
kb_id: Uuid,
conditions: &[ConditionInput],
joined: bool,
) -> AppResult<()> {
for c in conditions {
let op = utopia_reason::rules::Op::parse(&c.op).ok_or_else(|| {
AppError::invalid(
"bad_op",
"A condition compares with >, >=, <, <=, a range, a set (in or not in), or presence.",
)
})?;
let side = utopia_reason::rules::Side::parse(&c.side).ok_or_else(|| {
AppError::invalid(
"bad_condition_side",
"A condition reads x (the rule's subject) or y (the joined entity).",
)
})?;
if !joined && side != utopia_reason::rules::Side::X {
return Err(AppError::invalid(
"condition_side_without_join",
"Only a joined rule can read the other side of an edge.",
));
}
attribute_predicate(pool, kb_id, c.predicate_id).await?;
// ADR 0032 already permits expression thresholds. Validate the same AST
// and same-base attribute references as computed conclusions; sets,
// ranges and presence retain their separate operand contracts.
if matches!(
op,
utopia_reason::rules::Op::Gt
| utopia_reason::rules::Op::Gte
| utopia_reason::rules::Op::Lt
| utopia_reason::rules::Op::Lte
) {
if let Some(expr) = c.operand.as_ref().filter(|v| v.is_object()) {
for predicate in validate_expr(expr)? {
attribute_predicate(pool, kb_id, predicate).await?;
}
continue;
}
}
let shaped = match op {
utopia_reason::rules::Op::Present => c.operand.is_none(),
utopia_reason::rules::Op::NotIn => c
.operand
.as_ref()
.and_then(|v| v.as_array())
.is_some_and(|a| !a.is_empty()),
utopia_reason::rules::Op::Between => c
.operand
.as_ref()
.and_then(|v| v.as_array())
.is_some_and(|a| a.len() == 2 && a.iter().all(|x| x.as_f64().is_some())),
utopia_reason::rules::Op::In => c
.operand
.as_ref()
.and_then(|v| v.as_array())
.is_some_and(|a| !a.is_empty()),
_ => c.operand.as_ref().is_some_and(|v| {
v.as_f64().is_some()
|| v.as_str()
.and_then(|s| s.trim().parse::<f64>().ok())
.is_some()
}),
};
if !shaped {
return Err(AppError::invalid(
"bad_operand",
"That comparison does not match the value it was given: a threshold needs a number, a range needs two, a set needs at least one entry, and presence takes none.",
));
}
}
Ok(())
}
/// 条件与属性结论只能落在 kind='attribute' 的谓词上——规则读的是这个实体
/// 自己的字面值,关系(实体到实体)不参与(0021 决策 3)。
async fn attribute_predicate(pool: &PgPool, kb_id: Uuid, id: Uuid) -> AppResult<()> {
let row: Option<(String,)> =
sqlx::query_as("SELECT kind FROM relation_types WHERE id = $2 AND kb_id = $1")
.bind(kb_id)
.bind(id)
.fetch_optional(pool)
.await?;
match row.as_ref().map(|(k,)| k.as_str()) {
Some("attribute") => Ok(()),
Some(_) => Err(AppError::invalid(
"not_an_attribute",
"A rule reads this entity's own attributes; a relation to another entity cannot be a condition.",
)),
None => Err(AppError::invalid(
"unknown_predicate",
"That attribute is not in this base.",
)),
}
}
async fn relation_predicate(pool: &PgPool, kb_id: Uuid, id: Uuid) -> AppResult<()> {
let row: Option<(String,)> =
sqlx::query_as("SELECT kind FROM relation_types WHERE id = $2 AND kb_id = $1")
.bind(kb_id)
.bind(id)
.fetch_optional(pool)
.await?;
match row.as_ref().map(|(k,)| k.as_str()) {
Some("relation") => Ok(()),
Some(_) => Err(AppError::invalid(
"not_a_relation",
"A join or relation conclusion names an edge between two entities.",
)),
None => Err(AppError::invalid(
"unknown_predicate",
"That relation is not in this base.",
)),
}
}
/// Keep the conclusion and its join edge as one replaceable shape. The database
/// CHECK is the last line of defence; these errors say which half is missing.
fn validate_join_shape(kind: &str, join_predicate_id: Option<Uuid>) -> AppResult<()> {
match (kind == "relation", join_predicate_id.is_some()) {
(true, true) | (false, false) => Ok(()),
(true, false) => Err(AppError::invalid(
"no_join_predicate",
"A relation rule needs the relation that connects X to Y.",
)),
(false, true) => Err(AppError::invalid(
"join_without_relation",
"Only a relation conclusion can name a join predicate.",
)),
}
}
async fn exists(
pool: &PgPool,
kb_id: Uuid,
table: &str,
id: Uuid,
code: &'static str,
message: &'static str,
) -> AppResult<()> {
let sql = format!("SELECT 1 FROM {table} WHERE id = $2 AND kb_id = $1");
let row: Option<(i32,)> = sqlx::query_as(&sql)
.bind(kb_id)
.bind(id)
.fetch_optional(pool)
.await?;
row.map(|_| ())
.ok_or_else(|| AppError::invalid(code, message))
}