droboticflow/docs/adr/0010-source-backed-slice-revisions.md

11 KiB
Raw Permalink Blame History

0010:源引用切片修订与独立源校验

日期:2026-10-17

状态:2026-10-17 已按批准计划在 Fanyu 启用,线上仅完成只读核验,尚未完成生产 100 浏览器容量验收。程序默认开关仍关闭。

背景与范围

用户授权实施源视频、原始 PTS 和 IMU 复用,并以新增 36 核、120 GB 为预算规划 100 人并发。原路径在每次切片确认、返工修订时重编码视频、生成 CSV,轻量编辑与媒体处理共用队列。BOS 原始对象没有可靠的版本 ID,仅记录路径不足以冻结审核证据。

决定

  1. ANNOTATION_SOURCE_INDEX=true 才产生 droboticflow.source-slice-index/v1 修订。关闭时保留原物理修订路径,历史物理修订继续读取、审核、交付。

  2. 每个 Run 的源版本第一次使用时,完整验证双目解码帧数、媒体时钟、PTS 顺序、共享边界、IMU 有效配对。原始硬件时间允许有间隔,不把硬件时间当作视频播放时间。

    媒体时钟以候选标称帧率逐帧核对,不使用已舍入的总时长除以帧数反推周期。每帧允许 max(0.1ms, 半个视频时间单位) 的量化误差,总时长允许一个时间单位的终点舍入误差(最低 0.1ms);标称帧率本身不代替实际帧序校验。重复时间戳、超出量化范围的帧序间断及总时长不一致仍拒绝。

  3. 校验后将两路视频、两份 PTS、一份 IMU 固定到 system/runs/<run>/annotation-sources/<fingerprint>/。BOS 使用条件复制,不能覆盖已有固定对象;本地使用完整临时文件及原子发布。源版本变化必须重新验证,旧修订继续引用自己的固定版本。

  4. 证书以校验和、gzip 保存于既有 timeline 索引集合。独立持久化校验队列负责冷源;轻量修订等待时让出执行槽,不消耗崩溃重试次数。校验租约续期,超时可恢复。

    旧时间轴队列的早期兼容规则见下方 2026-11-11 更新;当前用户确认创建的 source-v1: 请求优先于历史时间轴工作,使用现有 ID/状态索引。

  5. 后续每个修订只写修订清单、每片 annotation 和 synchronization JSON。记录半开硬件时间窗、双目各自帧区间及播放偏移,保留完整覆盖、舍弃理由、动作与审核冻结校验。

  6. 最终验收使用已固定的完整源媒体和切片逻辑时间映射;不依赖重新生成的逐片视频、PTS、IMU。切片本地时间和双目源时间分别转换,元数据就绪后才挂载播放器。

  7. 旧目录交付仍在终审之后按帧生成保留切片媒体和 CSV,舍弃区间不产生交付媒体。该阶段仍有转码成本,与交互式切片队列分离。

    源索引修订中,固定源校验及切片同步证据明确记录 imu.sampleCount=0 的保留切片允许交付仅含表头的 imu.csv。实际样本数仍须与同步证据一致,非空样本仍须满足窗口与 accel/gyro 配对校验;历史物理修订的非空要求保持不变。

与 ADR 0005 的关系

本决定替代 ADR 0005 中“内部审核始终依赖逐片物理视频”的实现约束,保留审核冻结和舍弃判定语义。

新的 JSON-only 源索引交付是 v2 协议,含固定完整源的逻辑键、哈希、双目帧区间。它只能交给有权读取完整源、承诺按区间解析的下游。完整源含舍弃区间,因此不能把它视为“物理交付视频不含舍弃区间”的等价替代。该变化尚未得到交付协议批准,必须同时显式设置 PART_INDEX_DELIVERY=true 和 SOURCE_INDEX_DELIVERY=true;仅有旧开关时拒绝新源索引 JSON 交付。目录交付无需放宽旧契约。上线启用前必须确认实际工作流使用哪种交付方式。

2026-10-21:MP4 呈现终点量化兼容与旧任务恢复

逐帧时间戳和解码帧数检查保持原要求。总时长检查还需考虑 MP4 编辑列表使用的 movie timescale,而非只看视频 track time base:新的终点容差为原容差与 min(movie tick + track tick + 浮点余量, 半个帧周期) 的较大值。无法读取有效 movie clock 时维持原容差,不扩大放行范围。

B06/part0002、B14/part0001、B18/part0003 的本地样本均为连续 30fps,packet 时长全部是 512 track tick;编辑列表导致呈现总时长少 5 个 track tick,约 0.326ms。不得将此误认为丢帧,也不得直接删除时长检查或统一放宽一帧。兼容处理不改源文件、硬件 PTS、统一边界或已有证书,不以忽略编辑列表重新定义播放起点。整帧截短、帧数差异和逐帧断档仍拒绝。

没有 sliceWorkflow 的旧任务仍按已有正式生成证据识别。只有草稿而没有有效生成证据的任务不能凭前端推断进入标注;允许操作者显式按服务器保存的完整快照恢复生成,复用持久作业、租约和版本竞争机制,并保留动作、描述及分类。已确认工作区之外还存在较新的本人自动保存草稿时,恢复采用该草稿,与页面恢复内容一致;归属、版本、时间或数据格式无法核对时停止,不能猜选或清空。恢复模式需跨失败重试保留,避免再次退回旧工作区。恢复不是清空后重新切片。

成本、兼容性与回退

2026-11-11 用户要求完整源校验通过后才能领取,替代旧时间轴成功及旧任务免校验的兼容放行。所有新任务和已经排队的旧任务必须完成媒体与传感器校验,成功作业写入源指纹;只完成时间轴、无完整源指纹的历史 completed 记录保持待补验,不得直接视为有效。读取和领取不触发解码或批量补写;旧完成记录通过受控重校验入口恢复。已领取任务保留标注、草稿、版本、归属和历史,失败不自动回池,补验不自动重跑工作流。API 和校验器须协调升级,旧任务补验成本及生产授权边界见源数据校验与标注准入。

2026-10-22 补充:普通失败重试不能以旧确认覆盖页面恢复的较新草稿。重试核对确认内容指纹;内容不同需操作者显式按当前保存内容重新确认,保留旧快照及已有动作。后台完成时再次核对,旧队列作业亦适用,不自动回填或重算历史时间。具体契约见 标注时间完整性。

  • 固定源每 Run/源版本复制一次,不是跨 Run 去重;首用仍消耗解码 CPU、读取带宽与一份源大小的存储,之后修订为 JSON。
  • 固定源不随旧修订目录清理;目前没有自动 GC,以免删除在途审核及已交付索引引用。启用前评估容量,后续需基于引用和保留期设计 GC。
  • Worker 识别源索引输入时必须使用 ANNOTATION_SOURCE_PACKAGE_IMAGE 指定的不可变 package 镜像摘要;旧 package 镜像不支持该协议,缺配置即启动任务前拒绝。
  • API、修订处理器、独立校验器、Worker 和独立 package 算子必须全部先升级再启用。不能只更新 API。
  • 默认不启动历史回填。新字段为可选,保留旧任务与物理修订恢复路径。
  • 一旦产生源索引修订,旧 API/Worker 不能消费这些修订。回退应先停止新源修订入口、保留兼容的新读者/交付组件,让在途任务完成;不得直接全量退到不认识新协议的旧镜像。

验证与未完成项

合成媒体验证覆盖重启、重复确认、源替换、固定文件损坏、冷源延期、不转码修订及真实媒体目录交付。100 个独立合成身份在本地 HTTP/Mongo 上完成状态查询、任务池、草稿保存和切片确认,使用 15 分钟/27,000 帧/180 万行 IMU 的索引量级;不等价于生产 HEVC 解码、网络与 100 浏览器播放测试。

本地带会话认证的终审浏览器使用合成 HEVC 验证 Movi 挂载、切片源偏移、逐帧、仅右相机与片尾停止。首次切片定位还覆盖了媒体就绪事件丢失:定位队列在就绪轮询中重新派发未完成目标,无需额外用户按键;行为测试覆盖该恢复路径。

首轮保存 p95 约 2 秒,根因是同项目写保护锁串行。2026-10-17 用户随后授权本地实施分区锁及完整回归,后续两轮本地保存 p95 为 389 / 308 ms;实现、两阶段升级要求与限制见 ADR 0011。程序默认仍为旧协议;Fanyu 已按批准的 barrier → striped 顺序激活,其他环境及未来变更仍须另行授权。

2026-11-09:送检失败的数据保留

已有返工或动作内容不得通过普通切片生成替换为空工作区。失败送检的持久输入在作业替换前必须留存;只有已发布对应正式标注版本并进入质检,才允许按原保留策略清理旧修订。失败快照写入不成功时停止替换,不能继续清理。旧客户端排队作业同样执行发布前保护。契约与回退风险见 送检恢复保护。

2026-11-11:隔离异常任务、旧任务限界过渡

用户确认优先保障正常开工,将看板和查询优化与全面强制补验分开发布。默认仍为严格完整源校验;仅 API 与切片处理器显式设置相同 ANNOTATION_LEGACY_SOURCE_CUTOFF=2026-11-12T00:00:00Z 时启用本次过渡。该 UTC 边界对应洛杉矶 11 月 11 日 16:00,生产配置须随具体发布计划审批。

过渡仅适用于截止时间前创建、状态 completed、没有完整源指纹且未标记完整重校验的旧时间轴,以及没有源索引物化/作业的原物理流程。任何已知失败、排队或运行的关联源作业、跨组织/项目/Run 记录、已知指纹不匹配均继续阻断。新任务、显式完整补验和源索引流程维持严格校验;读取不触发补验。

列表仍返回服务端可领取判定;空 sourceValidationStatus 仅表示没有准入阻断,不是完整源证书。任务详情对过渡记录返回 unverified、required=false,不写造假的 fingerprint,不将后台作业改成成功。异常任务保留工作区、草稿、归属及审核历史,不清空、不自动回池;管理员保留异常查询入口。

后台补验/源修复按独立固定清单及生产数据授权执行;补验状态不通过改写旧时间轴成功证据来隐藏失败。实际补验期间进入严格校验的任务可能暂时阻断,须有明确窗口或使用独立受审查的后台审计方案,不能声称无中断。收紧回严格默认前,先核对旧任务和公共池的真实证书准备度;移除配置会重新阻断尚未完成补验的旧任务,不能盲目回退。

2026-11-11:作业优先模式替代全量校验前置

用户明确要求先恢复正常作业,批准将全量源校验退出标注、切片、送检和已发布审核的前置路径。本决策在 API/处理器显式配置 ANNOTATION_SOURCE_VALIDATION_MODE=advisory 时替代上述严格准入及限界过渡规则;默认严格路径仍保留。

作业只建立必需的基础帧映射和冻结源身份,权限、版本、帧边界与送检数据保留保护继续执行。基础索引采用独立 ID/正文协议,不冒充完整校验;原审计作业和证书不被覆盖。已发布审核优先读取冻结索引。真实基础读取失败单条隔离并释放容量名额,不清空标注或更改归属。发布、兼容与回退边界见作业优先恢复。