Jyotisha/docs/tasks/PROGRESS-report-density-fix2-20260923.md

# PROGRESS-report-density-fix2-20260923 · BUG-1011 快照 SQL E2BIG 修复

## 当前状态（2026-09-23）

**实现已完成，真实数据库验证仍待 Gitea Linux 门禁。** 本轮从更正后的 `origin/staging` 基线 `451a58089a2eaa8c7e5ae1f0648199b008aa0dc2` 建立独立 worktree；没有修改旧的 `staging-gate-red-20260923` worktree。BUG-1011 尚不能标记 resolved。

| 项 | 事实 |
| --- | --- |
| 工作树 / 分支 | `.worktrees/report-density-fix2-20260923` / `codex/report-density-fix2-20260923` |
| 基线 | `451a58089a2eaa8c7e5ae1f0648199b008aa0dc2`（任务书更正提交） |
| 根因 | 约 428,557 字节的完整快照 SQL 被放进 `psql -c` 单个 argv；Linux `MAX_ARG_STRLEN` 约 131,072，门禁真实报 `spawnSync docker E2BIG` |
| 本机 Docker | CLI/daemon 存在，Server `29.8.0`；创建 compose 网络时报 `all predefined address pools have been fully subnetted`，未清理其他会话网络 |
| 远端门禁 | 前一 run 2857 / validate job 6347 唯一失败仍是本 BUG；本轮代码尚未推送，暂无新 run |
| 状态 | investigating；等待真实 PostgreSQL 快照测试和完整数据库套件证据 |

## 实现与范围审计

### G1：专用 stdin 单事务 helper

- `frontend/tests/helpers/postgres-fixture.ts` 新增 `psqlScriptAs(role, password, sql)`。
- 既有 `psql` 与 `psqlAs` 的签名、argv、事务行为保持不变；未迁移其他数据库测试调用。
- 新 helper 通过 stdin (`input: sql`) 传输 SQL，使用 `-X -At -v ON_ERROR_STOP=1 --single-transaction -f -`，并设置 `maxBuffer: 16 * 1024 * 1024`。
- `database-personal-report-sections.test.ts` 仅把完整快照写入调用和大 JSON 读回调用切换到新 helper；其他 `psql` / `psqlAs` 调用保持原样。
- 完整虚构 reader Markdown、engine packet、snapshot JSON 构造、哈希、幂等/首版保留、owner-read RLS 与越权断言均未裁剪、删除或弱化。
- 新增 `database-postgres-fixture-contract.test.ts`：真实 fixture 路径构造 UTF-8 SQL 大于 131,072 字节，验证 `set_config(..., true)` 后续可见，并验证超过 1 MiB 的 stdout 能完整取回。这些运行时合同仍需可用 Docker 才能执行。

### G2：原值 / 新值 / 原因

| 原值 | 新值 | 原因 |
| --- | --- | --- |
| 完整快照写入使用 `fixture.psqlAs(...)`，SQL 作为单个 `-c` 参数 | 仅该大快照写入使用 `fixture.psqlScriptAs(...)`，SQL 经 stdin、整段单事务执行 | 避免 Linux `E2BIG`，同时保留 `set_config(..., true)` 所依赖的事务语义 |
| 完整快照读回使用默认 `fixture.psql(...)` 输出缓冲 | 该大 JSON 读回使用新 helper 的显式 16 MiB `maxBuffer` | 避免完整 payload 超过 Node 默认 1 MiB stdout 缓冲而产生 `ENOBUFS`；不改变断言 |
| 无大脚本运行时合同 | 新增超 argv 限制 SQL、事务本地设置可见性和大 stdout 合同 | 防止后续回退到 argv 传输或移除显式输出缓冲 |

## 验证账本

| 检查 | 结果 |
| --- | --- |
| `./node_modules/.bin/tsc --noEmit` | 通过，0 错 |
| `npm run lint` | 通过，0 error；保留仓库既有 119 条 warning，未顺修无关 warning |
| 受影响文件 ESLint | 通过，0 error |
| `tests/postgres-fixture-contract.test.ts` | 2/2 通过（不启动 Docker） |
| `tests/database-postgres-fixture-contract.test.ts` | 失败于 `startPostgresFixture()` 创建网络：`all predefined address pools have been fully subnetted`；未执行 SQL，不是 helper 或产品断言失败 |
| `tests/database-personal-report-sections.test.ts` | 同一 Docker 网络创建错误；未执行迁移、快照写入、读回或 RLS 断言 |
| `npm run test:db` | 47 tests / 8 pass / 39 fail；数据库 fixture 均在 Docker 网络创建时报 `all predefined address pools have been fully subnetted`，未执行 BUG-1011 SQL；本机环境缺口 |
| `npm test` | 3,707 tests / 3,618 pass / 89 fail / 0 skipped；相对本轮此前记录的 3,704 名称基线新增 3 个合同测试，未发现 BUG-1011 引入的业务失败；失败含既有 Windows 路径、Docker 地址池、symlink EPERM 与既有断言，不能记全绿 |
| `npm run build -- --webpack` | 编译与 TypeScript 通过；页面数据阶段因 Windows Skill runtime symlink `EPERM` 在 `/api/daily-starlanguage` 失败，未取得 Static/gzip |
| `node --import tsx --test tests/postgres-fixture-contract.test.ts` | 3/3 通过（静态合同，不启动 Docker） |
| `node --import tsx --test tests/database-postgres-fixture-contract.test.ts` | 1 fail（Docker 地址池创建前阻断），2 个静态 fixture 合同通过；没有执行 SQL |
| `./node_modules/.bin/tsc --noEmit` | 通过，0 错 |
| 受影响文件 ESLint | 通过，0 error |
| `git diff --check` | 通过 |
| `git diff --check` | 已通过当前代码差异检查 |

## 硬红线核对

- 未修改 `.gitea/workflows/**`、schema、RPC、migration、生产代码或共享 `psql` / `psqlAs`。
- 未删除、skip 或弱化测试；完整快照 fixture 与断言保留。
- 未使用 `git stash`、`reset`、`clean`、`rebase` 或强推。
- 未读取或提交 `references/oracle/artifacts/pending_packets` 内容；未读取、猜测或借用凭据；未清理其他会话 Docker 资源。
- staging 推送、Gitea 新 run、publish/deploy 与 health SHA 尚未发生，不能预写成功。

## 下一步

1. 完成本机可执行的静态、前端与构建验证，并如实记录环境失败。
2. 仅提交本单允许文件；推送前 fetch 并核对远端 staging，若有并行推进则保留双方历史，不强推。
3. 推送后读取 Gitea validate 日志。只有 `database-personal-report-sections.test.ts`、新增大脚本合同和全部 `tests/database-*.test.ts` 在 Linux runner 通过，且无其他失败，才把 BUG-1011 改为 resolved；否则保留 investigating 并记录原文。