Aethera/APPLY.md

应用方式

这个包基于 0477a7e1b66481b53c44fc537328a23670054180，包含此前所有 Observation 累计修改，不依赖 git。

在解压目录执行：

python apply_all.py <Aethera 仓库根目录>

apply_all.py 会覆盖累计的 kernel/kernel/include/observation、同步门面与 Taskflow 修改文件，再按 0477a7e1... 的精确旧代码块修改 Taskflow runtime、Render3D 和 GPU Completion Service。

本阶段新增 Frame_Attention.hpp。frame_ready 到达后只生成一条 event=frame_attention 的结构化 Tracy Message，把同一 Frame 已经存在的事实汇总到一起：

• Frame render / graph start / graph-to-submit / backend prepare / submit path / completion tail wall time。
• Datoviz 已有 GPU render / total timestamp。
• uploaded/readback bytes、upload、queue/fence wait、shader/pipeline create 等关键 Resource activity。
• 当前 Vulkan pending submissions / frames in flight。
• 当前 GPU Completion Service in-flight / active / capacity，以及累计 capacity exhausted / error 数。

这个 Snapshot 不新增 Plot、不新增业务计时点、不伪造历史 Zone，也不自动判定 CPU-bound/GPU-bound。Taskflow 和 Lock 不复制统计到 Snapshot，继续直接看 Tracy 原生 Worker Zone / Lock timeline。

为了让 Snapshot 能读取同一时刻的服务状态，Vulkan.hpp 新增只读 Vulkan_State，GPU_Completion.hpp 新增只读 GPU_Completion_State。这些只用于 Observation 展示，不参与业务或调度。GPU Completion 镜像状态只在 Tracy 实际连接时更新。

前面累计的 Context、Frame、Vulkan submission/fence completion、GPU timestamp、Synchronization/Lock、Resource、Taskflow ready/wait、Frame→Taskflow correlation、Frame timing 和 GPU Completion backpressure 全部包含在本包中。CPU Memory profiling 仍未伪接。

人工审查本阶段可看 patches/frame_attention_observation.patch；实际应用仍以累计 apply_all.py 及其四个精确 patch 脚本为准。 本阶段在 Frame_Attention.hpp 上继续增加 event=frame_attention_index。它不会重新采样任何数据，只从同一个 Frame Attention Snapshot 派生少量可搜索事实标签：resource_activity、upload_wait、pipeline_build、frame_overlap、non_frame_submission、completion_queue_gap、completion_saturated。

Index 与完整 Snapshot 分开发送；没有任何标签时不发送。标签只用于 Tracy 文本筛选和快速定位，不代表自动根因判断。例如 frame_overlap=true 只是说明 Snapshot 时刻多个 Frame submission 同时在 flight。

人工审查本阶段新增内容可看 patches/frame_attention_index.patch。

本阶段继续补 Frame Policy / CPU admission 观测。新增 kernel/kernel/include/observation/Frame_Policy.hpp，并只在 Throttled_Latest_only::Private::publish_state() 这个已有状态发布出口读取权威 State/三槽 phase 后投影 Tracy Plot。Scene、Sink、Timer callback 不新增 Observation 参数或 Tracy 宏。

新增趋势包括 TimerTicks、DroppedTimerTicks、CompletedFrames、Idle/Rendering/Ready/SendingSlots、EffectiveFPS、render/send capacity，以及 Frame Policy 已有滑动统计的 average/P95/stddev。Observation 不建立新的滑动窗口，也不自动把 dropped tick 判成 GPU 问题。

Tracy.hpp 新增 double Plot 薄封装 AETHERA_TRACE_PLOT_D，直接使用 Tracy 原生 TracyCPlot。人工审查本阶段可看 patches/frame_policy_observation.patch；实际应用由 patches/apply_frame_policy_observation.py 完成。

本阶段继续把 Frame Policy 调度域状态接到单 Frame 的统一定位入口。Frame_Policy.hpp 新增只用于 Observation 的最小状态镜像：policy_revision、timer_ticks、dropped_timer_ticks、completed_frames 和 idle/rendering/ready/sending 槽位数量。镜像只在 Tracy 已连接且 publish_state() 已经产生权威状态时更新，不保存第二套 FPS/P95/StdDev 窗口。

每个 frame_ready 的 Frame_Attention 旁会额外发送一条 event=frame_policy_context Message，带同一 Frame 的 root/frame/generation 和最近一次已发布 Frame Policy 状态。它只提供“该 Frame 完成时 CPU admission 调度域是什么状态”的上下文，不伪造 parent/correlation，也不把累计 dropped tick 自动解释成当前 Frame 的根因。

本阶段增加 Observation 自身的数据质量 guardrail。Tracy_Text_Sink 不再在 1024-byte 上限处静默截断半个字段；每个 name=value 字段要么完整写入，要么整字段省略。只有真实发生字段省略时才写 Aethera.Observation.TextTruncations、Aethera.Observation.TruncatedRequiredBytes，并发送一条短 event=observation_text_truncated Message 标明 message/zone/task_zone channel。正常路径不新增 Message/Plot，也不扩大 1024-byte 栈缓冲。