Skip to content

docs: design the D4 metadata sidecar - #14

Merged
wt159 merged 1 commit into
mainfrom
docs/d4-sidecar-design
Nov 9, 2026
Merged

wt159 merged 1 commit into
mainfrom
docs/d4-sidecar-design

Conversation

@wt159

@wt159 wt159 commented Nov 9, 2026

Copy link
Copy Markdown
Owner

D4 的设计草案,先定契约再写码。

核心决定:

  1. 元数据入口用新增的 dump_pcm_data_write_ex(..., fmt),旧 write() 语义与字节输出完全不变,HAL 调用点一行不动
  2. sidecar 按 .pcm 文件粒度(分片/rollover 都产生多个文件,元数据必须跟着文件走)
  3. 打开时写首版(complete=false),关闭时补全 total_bytes/end_time;因此钩子必须挂在 file_mgr_close,否则 LRU 回收那条路径会漏
  4. 默认关闭;旧接口或格式未知时完全不生成 .json
  5. 原子写用 tmp + rename,失败只记 WARN

文档里包含对 Android HAL 的影响逐项核对表、JSON schema 与转义规则、失败矩阵、S-01~S-09 测试计划,以及 D4-A/B/C 三步拆分(A 可独立合入、行为等价)。

有两个待确认项写在最后:key 非 UTF-8 时是否改 base64;开关是否允许运行时切换。

Records the contract before any code: a new write_ex entry carries the sample
format (old write() stays byte-identical for HAL), sidecars are per .pcm file,
written once at open and finalized at every close, and the feature is off by
default so Android HAL behaviour is unchanged.

Covers failure modes, JSON escaping, the LRU interaction that forces the hook
into file_mgr, and a nine-case test plan.
@wt159
wt159 merged commit e2b57e2 into main Nov 9, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant