feat: provide foreign-key-free fresh install baseline

docs/api/README.md

@@ -21,6 +21,7 @@
 | 任务 `priority` 与节点领取池 | P3 已实现有界优先级加速、应用/队列轮转 | [优先级与公平派发](priority-and-fairness.md) |
 | 凭据校验、初始化、固定操作文件轮换/撤销与回执重放 CLI | P1/P6 已实现；不提供公网管理路由，测试专用提交不明切点已回归 | [鉴权](authentication.md)、[凭据报告](../reports/phase-6-credentials.md) |
 | `orbit-admin verify` 发布前结构核验 | 已实现只读迁移、零外键和 000026–000028 固定索引检查 | [运维核验](operations.md) |
+| `orbit-admin observe snapshot` 只读运行快照 | 已实现固定状态、事件窗口和阶段耗时的有界单节点快照 | [运维核验](operations.md) |
 | `orbit-admin retention inventory` 保留清单 | 已实现带 UTC 截止时间的只读盘点；不执行归档、删除或权限变更 | [保留清单](retention.md) |
 | `sdk/go/cmd/orbit-load` 有界受理负载工具 | 已实现固定并发、无自动重试、延迟百分位和错误分类；只用于隔离环境 | [负载工具](load.md) |
 | `scripts/test-backup-restore.sh` 隔离备份恢复演练 | 已实现一次性 MySQL 逻辑备份、独立恢复、核心计数及零外键核验 | [备份恢复演练](backup-restore.md) |

docs/api/operations.md

@@ -16,3 +16,22 @@ ORBIT_MYSQL_DSN='user:password@tcp(127.0.0.1:3306)/orbit' \
 `complete=true` 表示当前二进制的迁移账本、Orbit 表零外键，以及 000026–000028 的六个有界观测索引均满足要求。命令不会证明备份可恢复、复制已确认、业务副作用已核对或生产 RPO/RTO 达标；这些仍需隔离环境恢复演练和真实拓扑验收。失败时会先输出不含 DSN/密钥的检查结果，再以非零状态退出。
 
 发布流程应先停止不兼容的旧写入节点，在隔离环境和目标维护窗口应用 `orbit-migrate up`，随后执行 `orbit-admin verify`；只有输出完整且人工核对备份、权限、连接路由后才启动新版本。verify 不是运行时协调器，多个节点可并发读取，但不能替代一次性迁移锁。
+
+## 2. 只读运行快照
+
+需要在没有开启指标监听时查看平台积压趋势，可执行：
+
+```sh
+ORBIT_MYSQL_DSN='user:password@tcp(127.0.0.1:3306)/orbit' \
+  go run ./cmd/orbit-admin observe snapshot
+```
+
+命令只执行固定索引上的只读查询，输出 `snapshot`、`sample_limit`、`event_window_seconds` 和 `scope`。任务、交付、流程、Inbox按固定状态分别采样，每个状态最多10000条；事件和阶段耗时只看最近5分钟。达到上限时 `snapshot.truncated=true`，计数只能解释为本节点有界样本，不能作为全局精确数量。命令不接受租户、状态或表名参数，也不执行修复、归档、删除和权限变更。
+
+示例：
+
+```json
+{"snapshot":{"task_states":{"WAITING":0,"LEASED":0,"RUNNING":0,"NEEDS_REVIEW":0,"SUCCEEDED":0,"FAILED":0,"CANCELLED":0},"task_oldest_age_seconds":0,"delivery_states":{"PENDING":0,"LEASED":0,"ACKED":0,"EXPIRED":0},"delivery_oldest_age_seconds":0,"workflow_states":{"RUNNING":0,"WAITING":0,"CANCELLING":0,"NEEDS_REVIEW":0,"SUCCEEDED":0,"FAILED":0,"CANCELLED":0},"workflow_oldest_age_seconds":0,"inbox_states":{"PENDING":0,"LEASED":0,"PROCESSED":0,"QUARANTINED":0},"inbox_oldest_age_seconds":0,"truncated":false,"recent_events":{},"task_terminal_latency_seconds":0,"task_terminal_latency_max_seconds":0,"workflow_terminal_latency_seconds":0,"workflow_terminal_latency_max_seconds":0,"task_accept_to_start_latency_seconds":0,"task_accept_to_start_latency_max_seconds":0,"task_accept_to_terminal_latency_seconds":0,"task_accept_to_terminal_latency_max_seconds":0,"workflow_start_to_terminal_latency_seconds":0,"workflow_start_to_terminal_latency_max_seconds":0},"sample_limit":10000,"event_window_seconds":300,"scope":"single database node; bounded sample, not a global exact count"}
+```
+
+它与 `/metrics` 共享同一有界读取实现，但不会改变指标注册器或业务状态；遇到数据库超时会返回非零状态，调用方应保留上一次成功快照并排查数据库。