#Relcore

v0.2.4 preview：从 JoinWitness（单点等值关联预检）扩展而来。v0.1 只回答“这一对表 join 会不会扇出”；v0.2 回答“这条管道在哪一步、因为哪个键、扇出了多少行”。 对初审意见的逐条回应（改了什么、证据在哪、什么还没做）见 docs/REJECTION_RESPONSE.md。

#60 秒评审路径

1. 读下面三行边界：不是 DataFrame 门面、不是 SQL 引擎、不是单表校验器。
2. 跑 node bin/relcore.mjs examples/plan-tenant-fanout.json --md，看到 max_fanout=2 和 left_rows / right_rows；再跑 node bin/relcore.mjs examples/plan-budget.json，看到结构化 BUDGET_EXCEEDED。
3. 跑 node bin/relcore.mjs examples/compare-tenant-keys.json，看到 first_divergence 与 retained/lost/gained。
4. 想看优化后的计划：node bin/relcore.mjs examples/plan-revenue-by-segment.json --explain。
5. 想看实现分层：docs/ARCHITECTURE.md；想看与现有项目的关系：docs/OVERLAP_AUDIT.md；想看逐条回应：docs/REJECTION_RESPONSE.md。

#先看边界：它不是另外三个东西

#为什么需要执行层

• join 键漏了 tenant，行数从 5 悄悄变成 7；
• 管道重构后总行数没变，但实际匹配的行已经换了一批；
• 聚合前多了一层 join，金额翻倍，但报表只显示“总数”。

1. 计划：管道长什么样；
2. 基数：每一步实际多少行；
3. 证据：错了在哪、因为哪个键、哪几行。

#10 秒示例

#作为库

let orders = @relcore.read_csv(orders_text, "orders")
let customers = @relcore.read_csv(customers_text, "customers")

let result = @relcore.execute(
  @relcore.Join(
    @relcore.Scan(orders),
    @relcore.Scan(customers),
    ["customer", "tenant"],
    ["customer", "tenant"],
    @relcore.Inner,
  ),
)

let violations = @relcore.check_contracts(result.batch, result.stats, [
  @relcore.JoinCardinality(["many_to_one"]),
])

#作为 CLI

node bin/relcore.mjs examples/plan-tenant-fanout.json --md

# Relcore report

- rows: 7
- contracts: **fail**

## Plan stages

| stage | rows in | rows out | fanout | cardinality |
| --- | --- | --- | --- | --- |
| scan | 5 | 5 | 0 | - |
| scan | 4 | 4 | 0 | - |
| join:inner | 9 | 7 | 2 | many_to_many |

## Violations

- **JOIN_CARDINALITY**: join cardinality many_to_many is outside the allowed set
  - `worst_key=3:i:9|`
  - `left_rows=3,4`
  - `right_rows=2,3`

#计划对比：从哪一步开始不一样

node bin/relcore.mjs examples/compare-tenant-keys.json

{
  "ok": false,
  "baseline_rows": 7,
  "candidate_rows": 5,
  "row_diff": { "retained": 5, "lost": 2, "gained": 0 },
  "first_divergence": {
    "index": 2,
    "baseline_op": "join:inner",
    "candidate_op": "join:inner",
    "baseline_rows": 7,
    "candidate_rows": 5
  }
}

#能力面

#契约语义

#通用性矩阵

#与现有项目的关系（主动披露）

#项目结构

relcore/
├── types.mbt        # DataType / Value / Schema / Batch
├── csv.mbt          # RFC-4180 风格 CSV 读取与类型推断
├── expr.mbt         # 表达式树与三值逻辑
├── exec.mbt         # 逻辑计划 + 算子执行 + 节点统计 + 证据
├── contract.mbt     # 契约检查、节点契约、witness
├── wire.mbt         # JSON 计划/对比解析、JSONL 读取
├── api.mbt          # run / run_markdown / compare
├── api/             # JS 导出层
├── bin/relcore.mjs  # Node CLI
└── examples/        # 可复现计划与对比

#质量

moon check --target all --deny-warn
moon test --deny-warn                 # 32 项
moon test --target js --deny-warn     # 32 项
moon fmt --check
moon run examples/embed --deny-warn   # 库 API 消费者
node scripts/build.mjs
node --test tests/cli.test.mjs        # 8 项
python tests/oracle.py                # 4 组 SQLite 差分校验

• 32 项 MoonBit 测试：CSV 推断、filter/project、inner/left join、aggregate、union/distinct、JSON 计划、节点契约、join 证据、计划对比、错误路径；
• 8 项 CLI 测试：示例退出码、Markdown、缺失文件、计划对比、预算错误、explain；
• 4 组 SQLite 差分校验：fanout、组合键、按 segment 聚合、计划对比；
• examples/embed 用公开 MoonBit API（不经过 JSON/CLI）跑同一管道，输出 rows=3 violations=0；
• 所有后端 moon check --deny-warn 通过；moon test 在 wasm-gc 与 js 上通过；
• 确定性输出：同一输入产生逐字节相同的 JSON。

#边界（明确不做）

• 不是数据库：不做存储、事务、索引、恢复、权限。
• 不是分布式引擎：单进程、内存内执行；跨机调度不在范围内。
• 不是完整 SQL：当前入口是 plan IR；SQL 方言适配是后续工作。
• 不验证业务语义：契约只检查结构、基数、唯一性、空值；键是否“有意义”由使用者判断。
• 当前规模：预算通过 max_rows / max_join_rows 显式配置；受宿主内存限制，尚未实现 spill。

#路线图（十月）

#许可证