编解码器与确定性

PurRDF 为九种格式提供第一方解析器与序列化器——不封装任何第三方编解码器：

它们位于 purrdf-rdf 中，比内核高一层，可经由总括 crate 访问：

#![allow(unused)]
fn main() {
use purrdf::{parse_dataset, serialize_dataset, SerializeGraph};

let turtle = br#"
    @prefix ex: <https://example.org/> .
    ex:cat ex:says "meow" .
"#;

// 解析为冻结的、按值驻留的 RDF 1.2 数据集 IR。
let ds = parse_dataset(turtle, "text/turtle", None).expect("valid Turtle");
assert_eq!(ds.quad_count(), 1);

// 通过任一原生编解码器序列化输出——逐字节确定性的输出。
let nq = serialize_dataset(&ds, "application/n-quads", SerializeGraph::Dataset)
    .expect("serializes");
assert_eq!(nq.as_slice(), b"<https://example.org/cat> <https://example.org/says> \"meow\" .\n");
}

Open Knowledge Format bundle

原生 OKF 编解码器把按调用方 profile 配置的 RDF 1.2 数据集映射为面向智能体的、带 YAML frontmatter 的 Markdown 文件，并经由 RDF 事件扩展点把它们提升回来。OKF 是一个内存中的 bundle API，而不是又一种媒体类型：文件如何存储由调用方选择，因此同一份代码保持确定性与 wasm-clean。

OkfConfig::new 要求提供词汇命名空间、文档基准 IRI 以及可识别的 frontmatter 键。不存在内置的本体或命名空间。使用 lift_okf_bundle 驱动一个 RdfEventSink，或使用 write_okf_bundle（由 OkfWriter 这一 RdfDatasetVisitor 支撑）投影一个冻结的数据集。两个方向都总是返回损失台账。无损的 profile 得到空台账；写入时，命名图、非 profile/OWL 行以及无关的具体化节点或注解行都会被明确地逐一指出。

字节确定性

每个序列化器都是逐字节确定性的：同一数据集在每个平台、每种语言绑定中总是产生相同的字节。这是工作区的硬性不变量，而非尽力而为——任何输出路径都不允许依赖迭代顺序、时间或随机数生成器（哈希器使用固定密钥的 FixedHasher 正是出于这个原因），且黄金文件测试固定了输出的字节。

确定性使工具包的其余部分得以组合：GTS 与切片目录中的内容寻址、评审中可做差异比较的序列化结果，以及可逐字节比较的跨语言一致性向量。

诊断，而非部分解析

格式错误的输入是一个带类型的 RdfDiagnostic，编解码器能提供源位置时即附带源位置——绝不会静默地部分解析。解析时可以选择记录一张源位置区间表，以获得更丰富的诊断。诊断在核心中保持结构化（不含 SARIF）；可使用 purrdf-validate 把它们渲染为逐字节确定性的 SARIF 2.1.0，供编辑器与 CI 使用（参见 SHACL）。

有损投影会显式告知

RDF 1.2 陈述级数据（三元组项、具体化节点绑定、注解）在每一次支持 star 的往返（转换）中都得以保留。序列化到不支持 star 的投影时，这一层会被_丢弃并显式告知_：实际丢弃的数量交给机器可读的损失台账（generated/transcode-loss-matrix.json，代码 rdf12-star-unrepresentable），而不是凭空消失。同样的纪律也适用于 SPARQL 结果边界（结果格式）与 RDF↔GTS 边界。

简洁 pack 编解码器

除上述文本编解码器之外，purrdf-core 还提供一个用于不同用途的二进制编解码器：一种只读的、可直接查询压缩形式的整个数据集编码，面向大规模参考 bundle，而不是带媒体类型的交换格式。PackBuilder::build_bytes(&dataset) 把一个自包含、逐字节确定性的 pack——值字典、按图分区的简洁位图三元组，以及 RDF 1.2 侧表（具体化节点绑定、陈述注解）——写入一个 Vec<u8>。PackView::from_bytes(&[u8]) 在借用的切片上以零拷贝方式打开它，并直接针对打包后的字节回答模式查询，事先不需要任何解压或物化步骤。

当一个数据集已不再变化，需要分发、归档，或需要在每次加载都重新解析文本会过慢的规模上提供服务时，就该使用 pack：RDF 1.2（命名图、引用三元组、具体化节点、注解）得到完整支持，且 verify_pack 会依据 pack 自身解码出的内容独立地重新计算数据集的 RDFC-1.0 摘要——这是一个经认证的只读投影，而不只是一个压缩文件。库本身从不对 pack 做内存映射（每个已发布的 crate 都保持 wasm32-unknown-unknown 兼容）；想要一个持久的、大于堆的存储层的原生使用方，可以自行 mmap 该文件，再把得到的借用切片交给 PackView::from_bytes。完整契约见后端契约中的「Pack backend」一节。

确定性的嵌入伴随文件

.purremb 是面向某个确切 .purrpck 的嵌入（向量嵌入）投影的原生 mmap 伴随文件。它不修改 pack，也不改变 RDF 规范标识。其排序后的节目录把有限的稠密 f32 或 f64 矩阵绑定到源 pack 的确切 SHA-256、一个经独立校验的 RDFC 摘要、完整的模型与处理契约、稳定的目标集，以及逐节与整个工件的完整性证据。EmbeddingBuilder 接受无序的行；EmbeddingStreamWriter 接受规范顺序的行，矩阵工作内存有界；两者产生相同的规范字节。

两类主体是一等公民。大型文本集合使用语料库–文档–分块的层级：UTF-8 文本保留在外部，而目标记录保留内容摘要、逻辑标识、字节与 Unicode 标量坐标、分块契约以及限定于嵌入族的 token 区间。RDF 数据使用同一个 RDF 1.2 模型来表示数据集、默认图与命名图、陈述、具体化节点绑定、注解、带方向的字面量、空节点以及递归三元组项。源局部的 pack 序号是经过校验的查找提示，绝不是标识。

Matryoshka 嵌入族只存储其最宽的稠密矩阵。每个声明的前导前缀都是一个独立的 VectorSpaceId 与 ProjectionId，因此粗粒度前缀不会被静默地与完整空间比较或替代完整空间。原始前缀行是零拷贝的跨步视图；确定性的 L2 前缀按需计算。近似索引仍是不透明的、可重建的派生工件，绑定到一个确切的前缀投影。它们绝不取代权威矩阵。

构建遵循唯一一条证据路径。首先，通过构建或独立校验确切的源 pack 获得一个 CertifiedPurrpckSource；任意的摘要声明都无法构造该类型。对于语料库，推导出 CorpusTarget、DocumentTarget::from_content 与 TextChunkTarget::from_document 记录，添加所需的层级关系，并为嵌入族矩阵中的每个文档或分块添加一个 TokenSpan。对于 RDF，从那个经过校验的 RDF 1.2 数据集推导出数据集、图、陈述、具体化节点、注解与项的目标。RDF-star 三元组项使用 RdfTermTarget::Triple；它们不进入单独的标识体系。

EmbeddingFamilyContract 定义完整的生成流水线。Matryoshka 契约列出其允许的前导维度，而其 MatrixInput 只携带最宽维度上的行，并为每个声明的空间各携带一个 ProjectionSpec。使用方通过 effective_matrix 解析一个确切的 (TargetSetId, VectorSpaceId)，并且在比较来自相互独立输入的行之前必须调用 require_compatible_vector_spaces。

大型集合在工件边界处分片：每个 .purremb 指名其自身确切的源 pack 与本地目标集，而相同的嵌入族契约保留相同的 FamilyId 与 VectorSpaceId。语料库清单与 ExternalBinding::from_bytes 绑定外部文本或其他确切工件；ExternalBinding::from_purrpck 加入经独立认证的 RDF 证据。绑定携带调用方提供的角色与媒体类型。PurRDF 不为它们发明策略或本体词汇。

EmbeddingView::from_bytes 借用任何稳定的字节切片，无论是堆上持有的、由调用方内存映射的，还是 WebAssembly 线性内存。结构性打开、完整的工件校验、确切的源校验以及经认证的源校验，都是显式的证据状态，而不是访问关卡。对文件做 mmap 的调用方，在视图或驻留的校验证书存在期间，必须保持底层字节不可变。

嵌入与 ANN 结构是敏感的派生内容：模型反演、成员推断、相似度探测、摘要字典攻击以及索引结构都可能泄露源数据的性质。容器哈希能检测损坏与过时的附着；它们不认证作者、不加密内容，也不授予访问权限。参见逐字节精确的 PURREMB v1 规范。

列式 Parquet 编解码器

purrdf::columnar 提供双向的 SQL/DataFrame 交换路径。它把任意 DatasetView 加上一个内容寻址的 blob 存储映射为五个标准 Parquet 文件（terms、quads、reifiers、annotations 与 blobs），并在不依赖 Arrow 或通用 Parquet 运行时的情况下把这一确切 profile 读回。该映射保留 RDF 1.2 三元组项、具体化节点、注解、图作用域、带方向的字面量、空节点作用域以及显式为空的命名图。

这些文件逐字节确定，可由 DuckDB 等引擎读取。每个字段以及刻意收窄的 Parquet profile 见规范性列式模式。

一致性

编解码器由 W3C rdf-tests 语法语料把关，该语料随库固化并冻结在仓库中——涵盖 N-Quads、N-Triples、RDF/XML、TriG 与 Turtle 的 264/264 个往返（转换）用例。实时记分板见 docs/CONFORMANCE.md。

相关内容

• 规范化与差异比较——当需要的是_规范的_序列化而不仅仅是确定性的序列化时。
• 驻留数据集 IR——文本编解码器解析成的目标，以及 pack 编解码器与 RdfDataset 并列实现的 DatasetView 读取扩展点。