feat(ql3): inventory legacy data directory

docs/adr/ADR-0477-bounded-legacy-data-directory-inventory.md

@@ -0,0 +1,140 @@
+# ADR-0477：有界 Legacy Data Directory 盘点
+
+- 状态：Accepted
+- 日期：2026-08-21
+- 关联：QL-RFC-0001、ADR-0476
+
+## 上下文
+
+ADR-0476 已经证明单个生产形态 QingLong 2.x `database.sqlite` 可以经过 inspect、stage、verify、activation 和 clean/write-after
+双态回滚分类接管到 3.0，但真实部署的 `data` 目录不只有主数据库。现行 2.x 配置和实际用户目录可包含：
+
+- `config/`、`scripts/`、`db/`、`upload/`、`ssh.d/`；
+- `log/`、`syslog/`、`bak/`；
+- `repo/`、`raw/`、`dep_cache/`、历史 `deps/`；
+- 用户或插件创建的未知顶层条目。
+
+直接复用 2.x `SystemService.exportData/importData` 不满足 3.0 接管要求。该路径以 shell 拼接 `tar`，默认只覆盖数据库和上传目录，
+也没有固定资产分类、no-follow、硬链接拒绝、内容上限、确定性计划或敏感输出约束。直接打包整个 `data` 目录还会把日志、备份、
+跨架构依赖缓存、仓库 checkout、SSH 材料和未知插件资产混成一个不可审核恢复单元；对低内存路由设备尤其危险。
+
+完整目录复制之前，需要一个短生命周期、只读、确定性、按 Profile 有界的产品入口先回答：哪些资产存在、哪些可进入后续复制、哪些必须
+转换、哪些只保留为外部恢复资产、哪些应在 3.0 重新生成，以及是否存在必须人工处理的不安全或未知条目。
+
+## 决策
+
+### 1. 复用现有一次性产品入口
+
+在 `@qinglong/local-owner-cli` 的 `lifecycle/data-directory-adoption/` 内增加：
+
+- exact operation：`local-data-directory.adoption.inspect`；
+- exact options：`dataRoot` 与 `profile`；
+- 既有 `ql3-adoption run --command-file ...` 私有 command-file 入口。
+
+不新增 workspace package、第三方依赖、binary、daemon、listener、watcher、timer、数据库连接或部署对象。实现不得进入 Edge、
+Standalone、Application、AI 或 MCP 常驻闭包。
+
+### 2. 固定资产处置矩阵
+
+| 类别 | 处置 | 盘点深度 | 原因 |
+| --- | --- | --- | --- |
+| `config` | `transform` | `recursive_content` | 需要迁移到 3.0 配置模型，不能盲拷旧配置 |
+| `scripts` | `copy_reviewed` | `recursive_content` | 用户脚本是业务资产，但必须先审核安全和兼容性 |
+| `db` | `transform` | `recursive_content` | 主库由 ADR-0476 迁移，Keyv/sidecar 需独立识别 |
+| `upload` | `copy_reviewed` | `recursive_content` | 用户上传内容可保留，但必须受大小和文件类型边界约束 |
+| `ssh.d` | `transform` | `recursive_content` | 属于敏感凭据材料，后续必须进入专用私有交付协议 |
+| `log`、`syslog`、`bak` | `retain_external` | `root_only` | 作为历史/恢复资产保留，不进入默认 3.0 运行目录 |
+| `repo`、`raw`、`dep_cache`、`deps` | `regenerate` | `root_only` | checkout、原始缓存和依赖缓存应按目标架构重建 |
+
+未知顶层条目只记录数量和名称摘要，不返回原始名称，计划状态固定为 `manual_review`。本阶段不允许 caller 覆盖处置矩阵或增加任意
+include/exclude glob。
+
+### 3. No-follow、稳定身份与内容脱敏
+
+盘点要求 `dataRoot` 为当前 UID 拥有、canonical、非符号链接、group/world 不可写的非根目录。递归类别按 UTF-8 字节序确定性遍历，
+使用 `lstat` 且不跟随符号链接；只有当前 UID、group/world 不可写的普通单链接文件或目录可继续读取。符号链接、硬链接、多链接文件、
+特殊文件、错误 owner 和可被组/其他用户写入的条目只计为 unsafe，不读取其内容。
+
+普通文件通过 `O_NOFOLLOW` descriptor 读取，打开前后的 device、inode、mode、link count、UID、size、mtime 和 ctime 必须一致。
+目录遍历前后也必须保持同一稳定身份。底层文件系统错误统一映射为固定错误码
+`LOCAL_DATA_DIRECTORY_ADOPTION_CONFIGURATION_INVALID`，CLI 不返回原始路径、任意文件名或内容。
+
+结果只包含固定类别名、计数、逻辑/分配字节、宽读权限计数、unsafe 计数、SQLite 主库/Keyv/sidecar 识别计数、内容摘要、未知条目
+数量/摘要和完整 `planDigest`。宽读权限是审核信号；只有可写权限或身份/类型问题自动成为 unsafe。
+
+### 4. Edge 与 Standalone 分离预算
+
+| Profile | 最大条目 | 最大哈希字节 | 单文件上限 | 最大深度 |
+| --- | ---: | ---: | ---: | ---: |
+| Edge | 8,192 | 512 MiB | 64 MiB | 32 |
+| Standalone | 65,536 | 4 GiB | 512 MiB | 64 |
+
+目录通过增量 `opendir` 枚举，并在保存超过剩余预算的名称前失败，不先用一次性 `readdir` 将任意数量的目录项装入内存。文件使用
+64 KiB 固定缓冲区流式哈希并在关闭前清零。`root_only` 类别不递归、不读取或哈希其子项，因此依赖缓存和历史日志规模不会进入
+盘点内存或 I/O 成本。
+
+### 5. 本阶段只发布计划，不执行迁移
+
+该 operation 只读源目录并将结果写到 stdout。它不创建目录副本、归档、manifest、recovery 或 activation，不修改 2.x 数据，
+也不把目录计划自动绑定到 ADR-0476 的 SQLite plan/activation。后续 stage 必须重新验证稳定身份并显式绑定两个计划摘要；不能把本次
+inspect 输出直接当作复制授权。
+
+## 被拒绝的替代方案
+
+### 直接 tar 完整 data directory
+
+拒绝。它混合不同恢复语义、可能跟随或保存不安全链接、复制跨架构缓存，并让低配设备承担不可预测的空间和内存成本。
+
+### 为目录接管再拆一个 workspace package
+
+拒绝。该能力只有一个短生命周期产品 owner，没有独立部署、依赖或版本生命周期；放入已有 Local Owner lifecycle 垂直目录更符合
+当前包边界规则，也避免恢复“一个文件一个包”的碎片化。
+
+### 只统计文件大小，不读取内容摘要
+
+拒绝。大小和时间不能把后续 stage 绑定到已审核内容；确定性流式摘要提供最小的漂移证明，同时不输出文件内容。
+
+### 在 inspect 时复制或转换文件
+
+拒绝。盘点和 mutation 混合会让未知/不安全条目在 operator 审核前产生目标副本，也无法建立清晰的 plan-digest fence。
+
+## 影响
+
+### 正面
+
+- 完整 2.x data directory 首次获得固定、可审核的资产处置模型；
+- Edge 和 Standalone 使用不同硬预算，低配设备不会继承集群节点规模假设；
+- 未知资产、链接和权限漂移失败关闭，且不会泄露任意文件名或内容；
+- 日志、备份、仓库和依赖缓存不会污染 3.0 默认运行目录；
+- 没有增加 package 粒度、常驻资源或基础制品体积。
+
+### 代价与限制
+
+- 对递归类别执行全内容哈希，仍会产生与资产大小线性的磁盘读取；
+- 正在写入的 2.x 目录可能因稳定身份检查失败，需要先停止 writer 后重试；
+- `root_only` 只证明类别根的存在、权限和类型，不证明内部历史资产完整性；
+- 当前没有 stage/verify/restore，也没有固定物理 Edge 的耗时、RSS、磁盘峰值与断电演练；
+- 当前目录计划尚未与 SQLite activation、service-manager cutover 和 rollback lineage 形成统一证据链。
+
+## 验证
+
+- D-384 聚焦 data directory CLI：`5/5`；
+- Local Owner：`195 total / 190 pass / 5 conditional skip / 0 fail`；
+- backend：`1,535 total / 1,533 pass / 2 conditional skip / 0 fail`，`pnpm build:back` 通过；
+- 18-package clean build 与逐包测试单次退出 0；
+- package boundary、Cluster dependency、Edge import、Service Bridge import、Cluster/Worker deployment、Console 与 Console
+  distribution 八项审计全部 compatible/passed；
+- workspace 保持 18 packages，`singleSourcePackages=[]`、`shallowSourcePackages=[]`；Local Owner 为
+  `118 source / 117 nested / 1 root binary entry`；
+- 14 档 Local artifact audit 全部 compatible，基础 Edge/Standalone、Adopted、Application+AI 与 MCP 的体积和 loaded-module
+  基线未变化。
+
+本阶段不修改 PostgreSQL schema、ACL、repository、role、Pool、连接或 failover 语义，因此不重跑且不重新占有 PostgreSQL HA
+证明。
+
+## 后续
+
+- D-385：以 plan digest 和 ADR-0476 activation digest 为双 fence，设计 no-replace stage/verify manifest；
+- 对 `config`、Keyv 与 `ssh.d` 定义显式转换/私有交付协议；
+- 在固定物理 Edge/NAS 上测量完整目录盘点与 staging 的耗时、RSS、I/O、磁盘峰值和断电恢复；
+- 把 staged data directory 证据接入 systemd/OpenRC/Compose cutover 与 rollback lineage。

docs/adr/README.md

@@ -480,6 +480,7 @@
 | [ADR-0474](./ADR-0474-bounded-legacy-core-readiness-proof.md)                                                   | 有界 Legacy Core Readiness Proof                                                                                                                                                             | Accepted（OpenRC live actor 待补） |
 | [ADR-0475](./ADR-0475-legacy-system-script-open-api-compatibility.md)                                           | Legacy System、Script 与 Open API 兼容基线                                                                                                                                                    | Accepted |
 | [ADR-0476](./ADR-0476-real-legacy-sqlite-upgrade-and-rollback-rehearsal.md)                                    | 真实 Legacy SQLite 升级与回滚演练                                                                                                                                                              | Accepted |
+| [ADR-0477](./ADR-0477-bounded-legacy-data-directory-inventory.md)                                             | 有界 Legacy Data Directory 盘点                                                                                                                                                               | Accepted |
 
 ## 规则