LSR 003 - Lamina C 扩展与插件规范

基本信息

• LSR 编号 003
• 标题 Lamina C 扩展与插件规范
• 作者 Ziyang-Bai
• 状态 草案
• 类型 标准规范
• 创建日期 02-04-2026
• 归属项目 编译器、虚拟机、包管理器

摘要

定义 C/C++ 扩展的最小交付、接口映射与内存/所有权约束。

技术规范

1. 最小交付物

最小交付：

• 动态库项目（可编译生成 .dll/.so/.dylib）
• Lamina 模块声明文件（默认文件名 lib.lm）

推荐目录（非强制）：

• [root]/lib.lm
• [root]/src/
• [root]/include/（可选）

2. 元数据文件（可选）

lampm.json 可选，用于补充包管理与自动构建信息；接口绑定前置条件仅为动态库与 lib.lm。

若提供 lampm.json，建议字段如下：

字段	类型	说明
name	String	包名
type	String	建议为 "extension"
language	String	C/C++ 标准版本
build.cflags	Array	编译参数
build.libs	Array	链接库列表
interface	String	接口文件路径，默认 "lib.lm"
entry	String	动态库入口函数名，默认 "lsr_init"

未提供 lampm.json 时，工具链按默认约定加载：

• 接口文件：lib.lm
• 入口符号：lsr_init
• 动态库名称：由构建系统决定

3. 接口映射语法（必需）

在 lib.lm 中使用 module 声明扩展命名空间，函数签名遵循 LSR-000：

• 静态强类型
• 参数与返回类型必须显式
• 类型标注语法采用 name Type

module example {
  # 语法：func name(param Type, ...) -> ReturnType = "c_symbol"
  func det(m matrix) -> num = "c_ext_det"
  func eig(m matrix) -> matrix = "c_ext_eig"
}

3.1 table 类型接口约束

当接口参数或返回值使用 table<K, V> 时，必须满足：

• K 必须可哈希
• 默认允许键类型：num、complex、text、bool
• 默认键类型范围仅包含：num、complex、text、bool
• 其他类型作为键需显式声明哈希语义（如 vector、matrix、set、table）

违反约束时接口绑定报错并停止生成桥接代码。

module ext_table {
  func score_of(t table<text, num>, name text) -> num = "c_ext_score_of"
  # 示例：vector 作为键需显式哈希语义
  # func bad(t table<vector, num>) -> num = "c_ext_bad"
}

3.2 复合对象内存安全与所有权协议

复合对象参数必须声明访问模式：

• @readonly：只读视图；原地写入需先 clone_if_shared
• @move：所有权转移，扩展接管生命周期

默认 @readonly。

3.2.1 引用计数约束

• @readonly 绑定必须增加持有计数，释放时归还
• @move 绑定后 Lamina 侧引用失效，生命周期转移到扩展
• 扩展持有指针需显式声明所有权

3.2.2 写入前克隆要求

在 @readonly 模式下，如需写入，必须调用运行时接口：

clone_if_shared(obj)

• 独占对象：直接返回可写对象
• 共享对象：先复制再返回可写对象

共享对象写入前必须调用该接口；运行时对未调用写入触发 ExtensionMutationViolation。

3.2.3 接口示例

module ext_safe {
  func frobenius(a matrix @readonly) -> num = "c_ext_frob"
  func consume(t table<text, num> @move) -> bool = "c_ext_consume"
}

规则：@readonly / @move 为接口注解。未声明时默认 @readonly。

4. 错误与诊断

至少支持：

• InterfaceBindError：接口映射失败
• TableKeyTypeError：table 键类型不合法
• OwnershipViolation：所有权协议违规
• ExtensionMutationViolation：未按规则写共享对象

5. 与其他 LSR 的关系

• LSR-000：核心类型系统、值语义、COW 语义
• LSR-004：标准库定义，扩展可作为补充实现
• LSR-008：量纲剥离规则（扩展无量纲入参场景）