# ADR 0008: HoloLake native composition and human projection

- Status: implemented and accepted in the signed local desktop runtime
- Date: 2026-08-18
- Source of intent: 冰朔在本轮对话中的自然语言纠正与验收要求

## Natural-language acceptance root

冰朔要求把 HoloLake 的功能模块做成可由人格体原生理解和组合的“乐高积木”。内部不以 Word、
PowerPoint、Excel 或其他外来办公文件作为运行格式；外来格式只经过导入转译进入 HoloLake，
导出时再按人类选择转译出去。HoloLake 内部保存轻量、稳定、可校验的原生对象。

人格体处理的是原生对象、模块插口和组合关系。人类不需要阅读内部格式，而是看到同一份数据的
动态投影：表格、分类、对比、仪表盘、柱状图，以及以后继续登记的其他视图。视图是可替换的
投影配方，不是复制出来的不同文件。多个数据源和多个模块必须能够像积木一样进入同一组合容器。

教育行业第一阶段的完成条件不是静态预览，而是：第一组原生模块已经可用；组合内核真实执行；
人类投影真实渲染；并用冰朔当前账号的 HoloLake 知识数据或本机真实文件生成一组可见演示，
在签名安装到桌面的 HoloLake 运行制品中完成验收。

## Decision

1. 建立 `hololake.native-object/v1`：列定义、行、值、来源回执和数据摘要均为受限 JSON 对象，
   不携带脚本、HTML 或外部执行能力。
2. 建立 `hololake.composition-module/v1`：每个模块声明类型、输入口、输出口、权限、确定性和边界。
3. 建立 `hololake.composition-recipe/v1`：有向无环组合图只引用已登记模块；系统验证类型、环、
   账号范围和资源上限后执行。
4. 建立 `hololake.human-projection/v1`：表格、分类、对比、仪表盘和柱状图共享同一个执行结果，
   投影层没有数据所有权，也不能绕过原生内核写入。
5. 教育初始化频道装载“组合视图”作为第五个原生模块。首个真实配方读取当前账号已有的知识目录
   元数据，按来源或目录分类，计算文档数、字节数或重复数，并让人类即时切换投影。
6. 当前阶段的组合执行保持只读。后续写回必须另设能力、预览、人工确认、修订锁和回执，不能
   从渲染组件直接获得写权限。

## Stage-one acceptance checklist

- [x] 原生对象格式、模块清单、组合配方和投影结果均有机器可读契约。
- [x] 未登记模块、类型不匹配、组合环、跨账号来源和越界资源必须失败关闭。
- [x] 表格、分类、对比、仪表盘和柱状图都由同一份执行结果实时渲染。
- [x] 人类可以选择维度、指标和投影组合，系统重新执行受限组合图。
- [x] 演示读取冰朔当前 HoloLake 账号的真实知识目录，不以硬编码样例冒充真实运行。
- [x] 教育初始化频道存在真实可访问的组合视图入口。
- [x] Node 合同测试、Rust 内核测试、前端测试和生产构建通过。
- [x] 桌面安装版完成签名安装并在真实界面验收；未完成公证时不得声称公众已获得更新。
- [x] 每一阶段完成后重新逐条核对本清单；偏差必须在继续前修正。

## Installed acceptance

签名安装版沿主世界、光湖分域、教育行业进入原生组合视图，读取当前账号 129 条真实知识对象，
总量显示约 1.0 MB，并形成 14 个真实分类。五种投影同屏可见；另一次验收把对比和分类卸下，
只保留仪表盘、柱状图和明细表，并把指标从文档数量切换为数据量，原生内核重新执行并生成新回执。

界面极快切换指标时曾观察到“左侧待执行配方”先于“右侧上一执行结果”更新，造成单位短暂错配。
最终实现已让右侧维度、指标、单位和可见视图全部绑定到执行回执，左侧只表示下一次配方；重新构建、
签名和安装后复验通过。最终桌面二进制 SHA-256 为
`2a26acae4a706c0ff9919b85f77826a6ca71b650ec22209befd30cd1456c92f3`。

Apple 公证和更新器私钥仍未配置，因此本验收不等于公众发布。

## Open-source donor rule

只使用官方仓库和官方文档核验候选。可以学习成熟项目的数据模式、声明式视图语法、无头组件和
查询计划，但不能整体嵌入重型协作软件，也不能让第三方项目接管 HoloLake 的身份、存储、权限、
组合执行或 UI 正本。任何复制的代码或新增依赖都必须记录来源、版本、许可证和实际用途。

## Rejected alternatives

- 把 Word、PowerPoint 或 Excel 当作内部原生格式：文件重、结构不稳定，也不适合人格体组合执行。
- 每种图表保存一份独立数据：会产生副本漂移，破坏“同一数据、多种投影”。
- 只在 React 中拼一套静态演示：不能证明 HoloLake 系统正在执行组合协议。
- 让模型自由生成并执行任意图表脚本：绕过模块登记、类型检查、账号边界和资源上限。
- 复制一整套飞书、钉钉或其他办公系统：体量和权限模型与 HoloLake 的轻量原生目标冲突。

## Evidence targets

- `contracts/native-composition-runtime.json`
- `src-tauri/src/native_composition.rs`
- `src/modules/native-composition/`
- `src/main.tsx`
- `src/styles.css`
- `scripts/native-composition-runtime.test.mjs`