feat(datasource): 将文本 ftrace 规范化为 Proto Source tables

[qiqingzhixin]

Closes #217

交付内容

• 文本 ftrace 逐行严格解析为 generated FtraceEvent，首批覆盖 25 类事件，不再维护私有事件 Arrow Schema。
• 文本与 HTrace 共用 descriptor-derived relation、typed emitter、8,192 行 bounded spool、preflight 和 Dataset writer。
• 一个文本文件形成一个 TracePluginResult；每个 CPU 一个 detail；CPU 内事件保持来源顺序，每条事件只选择一个 oneof payload。
• root provenance 对无 profiler envelope 的文本来源允许 NULL；缺失事实通过 Proto optional presence 表达。
• 已知字段错误输出 event、field、line、reason 结构化诊断，并写入 operation log；未知事件继续确定性汇总。
• protobuf Source compiler 通过 descriptor field path 生成通用 incremental subtree appender，不包含 text ftrace 专用 FQN、relation 名或 Rust 类型。
• 增加 Proto semantic overlay 治理清单和 25 类逐字段兼容矩阵。

架构图与调用链路

flowchart TB
    subgraph H[HTrace Datasource]
        direction TB
        H0[CLI import hitrace]
        H1[materializer::import_hitrace]
        H2[hitrace::decode_file_with_report]
        H3[LongTermHitraceSink]
        H4[PluginEnvelope claimant]
        H5[NativeHookSourceCapture]
        H6[ProfilerPayloadCapture]
        H7[full-root generated emitter]
        H8[PreparedImport]
        H0 --> H1 --> H2
        H2 --> H3 --> H8
        H2 --> H4 --> H5 --> H6 --> H7
    end

    subgraph T[Text ftrace Datasource]
        direction TB
        T0[CLI import ftrace]
        T1[import_text_ftrace]
        T2[ftrace_text::decode_reader]
        T3[generated FtraceEvent]
        T4[TextFtraceSourceCapture]
        T5[incremental root/subtree emitters]
        T6[clock_domain]
        T0 --> T1 --> T2 --> T3 --> T4 --> T5
        T1 --> T6
    end

    subgraph S[Shared descriptor-derived Proto Source mechanism]
        direction TB
        S0[descriptor relation plan / codegen]
        S1[generated SourceTableLayout]
        S2[SourceTableCapture<br/>one instance per import]
        S3[8192-row bounded relation spool]
        S4[PreparedSourceTables preflight]
        S0 --> S1
        S1 -. constructs .-> S2
        S2 --> S3 --> S4
    end

    subgraph P[Dataset publication]
        direction TB
        P0[dataset_writer::DatasetWriter]
        P1[Parquet Dataset]
        P0 --> P1
    end

    S0 -. generates .-> H7
    S0 -. generates .-> T5
    H7 --> S2
    T5 --> S2
    S4 --> H8
    H8 --> P0
    S4 --> P0
    T6 --> P0

Loading

• HTrace decoder 同时驱动 LongTermHitraceSink 与 PluginEnvelope claimant；前者保留 clock、规范化 sched_switch 和完整性校验，后者写入 descriptor-derived Source tables。
• 文本 parser 只产生 typed Proto；TextFtraceSourceCapture 只管理文本 root、CPU detail 和 repeated index。
• 两条链路共用 relation plan、codegen、layout、capture、bounded spool、preflight 和 Dataset writer，但 HTrace 使用 full-root emitter，文本使用 incremental root/subtree emitters。
• SourceTableLayout 是每个 capture 实例的构造输入，不是逐事件运行时节点。
• HTrace 由 PreparedImport 合并 legacy normalized tables 与 PreparedSourceTables；文本把 clock_domain 与 PreparedSourceTables 直接交给同一 Dataset writer。
• 同一架构图已写入兼容矩阵，避免 PR 描述与代码文档漂移。

最终候选复验

最终候选 SHA：fae80f2

验证	结果	本次耗时
cargo +stable test -p kat-datasource --features protobuf-source-contract-fixture incremental_relation --quiet	2/2 通过；覆盖通用 incremental subtree 与非法 descriptor path 诊断	96.23s（包含首次 feature 构建）
cargo +stable test -p kat-datasource --test text_ftrace_import_contract --quiet	9/9 通过	2.67s
cargo +stable test -p kat-datasource same_source --quiet	25 类 synthetic relation 合同及 HTrace/text parity 通过	10.21s
cargo +stable test --workspace --quiet	全部可运行测试通过；0 failure	84.19s
cargo +stable clippy --workspace --all-targets -- -D warnings	通过	3.85s
cargo +stable fmt --all -- --check	通过	-
git diff --check origin/codex/issue-213-ftrace-source-capture...HEAD	通过	-

workspace 中依赖真实设备、隔离 Windows profile 或 KAT_TEST_PYTHON 的既有测试按其声明条件忽略。PR Guard 已通过。

已复验的数据合同

• 仓库压缩真实文本 fixture trace/kat_hitrace_text.ftrace.gz（测试时解压）：4 类、9,043 条事件全部落表：
  • sched_switch: 6,005
  • sched_wakeup: 3,032
  • sched_wakeup_new: 4
  • print: 2
• 8,193 条 synthetic 流跨越 8,192 行 spool 边界，CPU 内 repeated order 保持一致。
• 第 8,193 条出现已知损坏事件时，完整 Import 失败且不发布/覆盖目标。
• 25 类 synthetic 同源输入在 HTrace 与文本路径下得到相同 Proto relation schema、presence、oneof 和共享事实。
• CLI 已知字段损坏返回结构化 event/field/line/reason，成功结果返回空 compatibility_issues。

历史真实设备验证材料

以下结果来自 2026-08-19 的同一 tracefs ring buffer 重叠采集，已记录在兼容矩阵；原始设备 capture 当前不在仓库，因此本次不能重新执行，只作为历史设备证据：

• 文本快照 8,756 条，HTrace 12,164 条。
• 忽略已确认的来源字段差异并按文本微秒精度对齐后，8,748 条完全匹配。
• 5 条文本边界事件未进入 HTrace；其余 3 条属于快照/纳秒对齐边界。
• HTrace wire 中 7,894 条事件未编码 TGID/comm，4,270 条显式 tgid=0；另有 43 条非零 PID 事件显式空 comm。
• 问题已定位到设备 ftrace-plugin 的 TGID/comm 字典填充/读取，不是文本转换、KAT Proto 解码或 Parquet 写入。

本 PR 保留各来源事实，不增加启发式回填；待与 HTrace/ftrace-plugin 负责人确认后另行处理。

Draft 原因与剩余验收

仓库当前没有 Issue #217 所述真实 25 类、44,344 条 fixture，因此尚不能提供：

• 44,344 条 common event 总数和真实 25 类逐表计数；
• 真实复杂样本 unsupported event 为零；
• 真实复杂样本 oneof join 完整性；
• 同一真实复杂来源的完整 HTrace/text 逐表 parity。

补齐经 review 的真实 fixture 或可重复设备采集产物后转 Ready for review。

依赖

这是堆叠 PR，base 为开放 PR #215 的 head 分支 codex/issue-213-ftrace-source-capture。#215 合并后应把本 PR base 更新为 main。

[ohfei]

kat-pr-review 总评（e069df1…fae80f2）

结论：当前不建议转 Ready 或合并，保持 Draft。

• 业务主管：三星
• 架构师：三星
• Infra 专家：五星
• 共发现：2 个 P1、3 个 P2；未发现重复实现成熟生态能力的问题。

[P1] 文本 root/config 把缺失事实发布成了 Proto 默认值

Issue #217 要求缺失标量不得伪造成 0/空字符串，Proto3 默认值只有在有“与缺席等价”的证据时才能使用；同时明确不为文本来源伪造 version。

实际路径以 TracePluginResult::default() 建根，并只设置 TracePluginConfig.clock、其余采用 Default 后发布整个 config root：

• text_ftrace_source_capture.rs:34
• text_ftrace_import.rs:69

TracePluginResult.version 以及 config 的 buffer、flush、布尔开关、duration、raw_data_prefix、parse_mode 等仍是 implicit Proto3 scalar，descriptor engine 会把它们发布为非 NULL 的 ""、0、false、NORMAL。PACK 因而无法区分“来源没有该事实”和“明确配置为零/关闭”。

建议： 将 version 及文本来源无法证明的 config scalar 纳入 optional semantic overlay；只写入有来源的 clock。增加公共 Import 合同，直接查询 root/config 表并断言未知字段为 NULL、显式零值仍可区分。

[P1] 25 类公开能力只有 4 类真实样本验收

仓库 fixture 只有 4 类、9,043 条事件，真实合同也只断言这 4 类；25 类 parity 来自代码内构造的 synthetic 文本和 Proto，不能证明另外 21 类真实设备语法。但命令参考已经直接承诺支持 25 类。

• text_ftrace_import_contract.rs:287
• same_source_full_contract/mod.rs:333
• command-reference.md:34

PR 正文也承认尚缺 44,344 条真实 fixture、逐类计数、unsupported=0、真实 oneof 完整性和 HTrace/text parity。exact head 的两个 pr-guard 均失败，直接原因只是二进制 fixture 未获 approved-binary-artifact；主要 CI/full-test 被跳过。

建议： 转 Ready 前补齐可重复的 25 类真实 fixture/设备采集，通过公共 Import 断言总数、逐类计数、每个 common row 恰好一个 payload、unsupported=0 及真实 parity；完成二进制审批并让 exact head 主 CI 实际执行。

[P2] 结构化兼容诊断没有覆盖公共事件字段

兼容矩阵承诺已知字段错误统一返回 event/field/line/reason，但只有 payload parser 的错误经过 compatibility_error。CPU、timestamp、TGID、emitter comm/PID 都在包装前解析，因此失败时只有普通错误。

• ftrace_text.rs:249
• ftrace_text.rs:273

建议： 先识别 event name，再把受支持事件的公共字段与 payload 统一纳入 TextFtraceCompatibilityError，并补 CPU、timestamp、TGID、comm、PID 的 CLI 合同。

[P2] ADR-0061 未同步跨来源 provenance 原则

ADR 仍要求 profiler root 连接真实 envelope occurrence，并保留“当前只编译 Native Hook roots”的过时表述；本 PR 则把 ftrace roots 改为 nullable parent，并由文本 capture 直接以 NULL parent 建根。

• ADR-0061:11
• build.rs:162

建议： 修订或 supersede ADR，明确 HTrace adapter 必须提供真实 parent、非 envelope Datasource 使用 NULL、仅 root parent 可空，以及共享 nullable Schema 无法物理约束 HTrace parent 非空这一取舍。

[P2] 多级 incremental emitter 的写入面重叠

incremental root 和每级 subtree 都调用递归的 emit_relation，所以都能发布后代关系。当前正确性依赖调用者始终传入空 root/空 event vector，再自行维护 repeated index；生成接口本身没有表达该排他协议。

• render.rs:99
• render.rs:533

建议： 让 incremental 边成为互斥写入面：停止递归发布下一条 incremental 边，或在对应 repeated field 非空时明确失败；同时记录 repeated-index 所有权。

Infra 结论

未发现成熟方案已能满足当前约束却被重新实现。实现已复用 BufRead、prost、构建期 prost-reflect、serde_arrow、Arrow/Parquet；项目自有部分主要是文本语法和领域字段映射。libtraceevent/trace-cmd 面向 tracefs 原始记录或 trace.dat，Perfetto/Trace Streamer 在现有真实 fixture 上不能提供本次要求的完整忠实映射。

---

评审范围固定为 base e069df1ee90c8898c94c5d9385b9b2021908fbe6、head fae80f2101103af71003ab1bd30e62057a2de748。这是只读评审：未替作者运行测试；验收判断只采用 PR 作者记录、当前 CI/check 和仓库内可核验材料。后续 head 变化需重新复核。