资源输入与求值

统一函数与读取能力

FunctionDef 保存规范身份、签名和 Code／Native 实现来源；CodeProgram 在函数身份之外保存 Code 函数体，NativeFunction 选择受信的 Rust 实现。返回数据或 Content 不划分函数类别。所有调用共用绑定、具体实例、执行入口与结果检查；内容结果才需要 Shape、Item 边界及呈现绑定。

read_text(source: Path) -> String 是标准库的 Rust-native 函数，仅接受 Path，不执行 String 转换。text／embed 也是 Rust-native 函数，但返回 Content。分号声明本身不赋予读取实现，JS／HTML 只描述 Content 节点的呈现。

CallSite 明确区分 Markup 与 Code；独立 Markup 只传字面量参数，读取在 notc 函数体中发生。求值器另以 Runtime／Comptime 表达能力阶段；comptime 不允许直接或间接读取。函数别名、重导出、文件后缀或模块标签不会改变能力。

FunctionDef 保存函数实现来源；序列化输入中的实现信息须一致，冲突时拒绝。

同步输入接口

core 定义不依赖宿主资源系统的接口：

trait EvaluationInputs {
    fn file(&self, path: &ResourcePath) -> InputRead;
}

enum InputRead {
    Ready(Arc<[u8]>),
    Failed(InputError),
    Pending,
}

查询只接受已绑定的身份，不重新解释相对路径，不提供目录枚举、写入或网络。宿主返回共享不可变字节，read_text 负责 UTF-8 解码并构造受既有值大小预算约束的 String。InputError 只保存资源事实，不缓存某个页面的 span 或 Diagnostic。

Pipeline.evaluatewithinputs 及带 Limits 的入口返回 Complete(Evaluation) 或 NeedResources。未准备的读取不会暴露部分树，也不运行 after_evaluate。普通 evaluate 不访问磁盘或 CWD，仅在实际执行读取时诊断缺少能力。

Evaluation.dependencies 记录实际请求的 ResourcePath，包括缓存命中、缺失与拒绝；未消费 Path 或未执行分支不构成读取依赖。读取失败使用实际 read_text 调用的来源和范围，沿已有内容错误边界恢复，保留展开链；其余兄弟内容继续呈现。

输入批次

一轮构建使用一个 Vault／ResourceSession，所有页面共享按需加载的输入。在同一授权读取能力下，每个逻辑路径的首次读取结果固定为本批次的字节、错误或 Pending，后续请求复用该结果。文件变化由下一轮构建接收；不同文件在各自首次使用时读取。

宿主在读取前配置授权与预算。直接构造 ResourceSession 时默认没有数据授权；Vault.new 明确授予项目根。Vault.withreadroots 替换授权列表，空列表拒绝所有数据读取。读取根、Resources.source_root 的词法绑定根和 publication／Book mounts 的发布根互不授予能力。

Resources.readroot 返回显式的 ResourceReader，其 readbounded 在根边界内有界读取。ResourceSession 保存首次结果，后端无须提供文件版本查询。数据缓存按授权读取能力隔离；源码字节只有经同一能力加载，才能直接复用为磁盘数据输入。收窄授权不能复用更宽能力的读取证明。不支持有界接口的后端仅可通过 Resources.read 加载源码，不能借已有源码缓存取得数据读取能力。

FsResources 使用 cap-std 的目录 capability，将授权检查与实际打开维持在同一根边界内；允许根内 symlink，不允许指向根外，拒绝非普通文件。读取至多取得 limit + 1 字节，以判断超限；Memory／Overlay 先检查已知长度，再复制。单文件、会话缓存和请求数分别受限：

宿主通过 InputLimits 与 Limits 调整预算；缓存命中也消耗请求额度。拒绝判断发生在缓存访问之前，缓存已有源码不会扩大数据权限。实际输入字节不自动进入 Assets、组件参数或公开 URL；读取内容只有被 Code 显式转换为 Content 后才成为正文。

Resources.sourceshared 提供共享 UTF-8 源码；ResourceSession 在有界字节读取成功后保留解码文本或 UTF-8 失败。同一规范路径的命中共享文本存储，但每次逻辑调用仍经过 sourcebytes 计费，不能借文本缓存避开读取预算，也不授予数据访问能力。

文件系统后端在首次有界读取前后检查同一文件句柄的元数据，读取期间发生变化作为该文件的 IO 失败缓存，不影响其他输入。缓存命中、文档求值与发布不重新扫描已读文件。

显式逻辑路径加源码是文档覆盖输入，不要求落盘。每个路径首次登记的文本供本轮的资源读取使用；已消费的读取保持原结果，后续登记不替换它，也不使批次失效。SSG 先登记全部生成／编辑页面，再求值，使跨页读取取得准备后的文本，而非旧磁盘内容。

新构建、编辑和资源准备重试创建新的 Vault。CLI 的 serve／listen 和 LSP 在输入更新后开始新批次；输入缓存与 comemo 计算缓存分离，新批次仍可复用未变化的模块编译与导入绑定。

批次内的配置与成功模块装配缓存不改变该输入规则：模块图命中仍按相同依赖遍历顺序请求源码，输入失败与额度不足仍阻止分析。DocumentHandle 只保留本 Vault 配置下某个文档源码快照的环境，供后续求值与 HTML 绑定使用；它不把输入会话放入 Analysis，也不将批次缓存扩展为跨构建快照。

浏览器准备

PreparedInputs 复用 files，另以 failures 保存 NotFound、AccessDenied、NotFile、TooLarge 或 IO 失败；incomplete 表示允许的缺失字节尚未准备。未指定这些字段的旧协议仍是闭合快照，缺失就是 NotFound。readroots 可显式替换项目根授权。moduleurls 只表示呈现入口可用，不声称已经准备空文件，也不授予数据访问。

describeprepared、renderprepared 和 analyze_prepared 遇到未准备输入时返回同一协议，不返回可发布的部分结果：

{"need_resources":[{"root":"/project","path":"data/intro.txt"}]}

web/project-inputs.js 将该逻辑身份与宿主声明的目录 URL 映射核对，在单文件与总量限制内准备字节或明确失败，然后创建新视图同步重跑。默认只允许 rootURL 的逻辑根；额外 resourceRoots 显式声明逻辑根与 URL，不从 import 或组件目录推导数据权限。

准备过程限制请求数、重试轮次和读取字节，不重复获取确认失败，不进行无进展重试。AbortSignal 与文档 generation 防止过期结果覆盖新修订；输入批次之间不共享旧的成功或失败缓存。未完成时保留上一份完整预览。

资源输入接口提供受授权的输入字节与读取结果，JSON／TOML 解码由 Data 处理。