NetbaDBPhase 7B

架构

应用语言位于
引擎边界之外。

NetbaDB 将应用语言相关问题限制在前端边界。Go、Rust 或未来的 schema 前端均应生成同一份 Canonical Schema IR。核心不检查 Go 类型，也不读取应用侧 Rust 结构体。

应用边界
Rust 嵌入式 SDK → Rust 远程客户端 → Go Protocol v1 客户端 → netbadbd
编译
Parser → AST → HIR + 类型检查 → Typed Relational IR
计划与执行
Optimizer / Planner → 同步 Executor
事务与存储
事务边界 → WAL + 恢复 → 缓冲池 + 槽页 + 堆 / B+Tree

架构边界

以下流水线为稳定的架构界面：

Application language schema
        ↓
Language frontend / SDK
        ↓
Canonical Schema IR
        ↓
Parser → HIR + type checking
        ↓
Typed Relational IR
        ↓
Optimizer / Planner
        ↓
Executor
        ↓
Transaction boundary
        ↓
Storage

当前嵌入路径

当前路径为同步执行。查询语言是有限的原生子集，不提供完整 SQL 兼容。核心不依赖 Go、网络运行时、JSON 执行 IR，或应用特有的 Rust 结构体。

Rust Schema API
    ↓
SELECT / JOIN / ORDER BY / GROUP BY + typed DML
    ↓
Typed HIR
    ↓
Logical query / DML statement plan
    ↓
Scan + nested-loop join + sort + grouped aggregate
    ↓
Join / filter / sort / aggregate / projection / limit + mutation
    ↓
Heap
    ↓
Transaction lifecycle + versioned WAL
    ↓
Buffer pool (guards, pinning, dirty writeback)
    ↓
Slotted pages
    ↓
Page manager / database file

Canonical Schema IR

netbadb-schema 用显式 Rust 结构保存数据库含义，独立于任何应用语言。一列包含稳定 ColumnId、名字、TypeSpec（物理类型 + 可选语义名）、可空性与主键元数据。

Schema::new 是可失败的构造路径，并委托 Schema::validate。校验拒绝重复的表 / 列 ID 与名字、空名字，以及空的语义类型名。规范名是前端无关的 UTF-8 身份，相等性精确且区分大小写。

每张通过校验的 TableDef 都有规范编码版本 1：以 NBTS 开头，然后是显式小端版本、表身份与按声明顺序的列。这些字节上的 SHA-256 就是 32 字节 SchemaFingerprint。Rust 枚举判别值、结构布局、Debug 输出或 map 迭代顺序都不参与。

编译阶段

当前查询子集按以下阶段编译：

source → AST → resolved / type-checked HIR → logical plan → physical plan

HIR 拥有源级解析与语义类型检查。关系 IR 拥有关系含义与列出处。规划器选择顺序扫描，以及正确性优先的 nested-loop 来实现逻辑 INNER JOIN。执行器对存储返回的行求值类型化表达式。

层与层之间传递标识符与所有权值，不会将页、帧或元组的长生命周期引用传入规划器、执行器或目录。

依赖方向

图中 A → B 表示 A 依赖 B。下层不得依赖上层策略。尤其是存储不得依赖规划器或执行器，执行器不得依赖 SDK。

netbadb-types

共享 ID、物理类型与语义类型

crates/netbadb-types

netbadb-schema

语言无关的 Canonical Schema IR

crates/netbadb-schema

netbadb-parser

小型 typed-query AST 与解析器

crates/netbadb-parser

netbadb-hir

名字解析与名义类型检查

crates/netbadb-hir

netbadb-rel

类型化逻辑关系 IR

crates/netbadb-rel

netbadb-compiler

AST → HIR → 逻辑计划

crates/netbadb-compiler

netbadb-planner

逻辑计划 → 物理计划，含 IndexScan

crates/netbadb-planner

netbadb-schema-spec

SDK Schema Spec v1 解析与指纹

crates/netbadb-schema-spec

netbadb-tooling

稳定的、由 schema 驱动的 SQL 诊断

crates/netbadb-tooling

netbadb-inspect

目录与计划检查 DTO

crates/netbadb-inspect

netbadb-protocol

Protocol v1 二进制线协议

crates/netbadb-protocol

netbadb-client

同步 Protocol v1 远程客户端

crates/netbadb-client

netbadb-server

会话、授权与阻塞式 TCP 运行时

crates/netbadb-server

netbadb-codegen

Schema Spec 校验与 Go 源码生成

crates/netbadb-codegen

netbadb-index

类型化 B+Tree 排序、节点、编解码与分裂

crates/netbadb-index

netbadb-storage

事务、WAL、页、缓冲池、堆与持久 B+Tree

crates/netbadb-storage

netbadb-executor

同步物理计划执行

crates/netbadb-executor

netbadb-core

原生嵌入式 Database API

crates/netbadb-core

netbadb-sdk

嵌入式与远程应用门面

sdk/rust

netbadbd

由清单驱动的独立 TCP 服务器

cmd/netbadbd

netbadb

离线本地检查 CLI

cmd/netbadb

跨语言策略

Go 是应用语言，不是实现语言。支持边界如下：

Rust: 原生核心、嵌入式 SDK 与 Protocol v1 远程客户端
Go: 独立 Protocol v1 客户端与生成的类型化绑定

sdk/go 是独立的标准库客户端。生成绑定会校验结果顺序、名称、物理 / 语义类型与可空性，但不生成 SQL 或查询构建 API。

设计优先级

正确性、显式不变量与类型安全优先于便利性。功能以完整、可测试的垂直切片引入。未实现的组件不以完成 API 的形式呈现。