feat: add scoped workflow instance queries and SDK pagination

2026-09-18 08:34:45 +08:00
parent 17a8e0126c
commit 082898e705
33 changed files with 1598 additions and 18 deletions
--- a/docs/07-data-model.md
+++ b/docs/07-data-model.md
@@ -35,7 +35,7 @@

 ## 3. 实体清单

-当前共 35 个实体：初始迁移包含 30 个，000003 增加进程会话头和迟到证据，000010 增加应用共享额度，000013 增加结果流与不可变结果快照。迁移自身另有 `orbit_schema_migrations` 记录。
+当前共 36 个实体：初始迁移包含 30 个，000003 增加进程会话头和迟到证据，000010 增加应用共享额度，000013 增加结果流与不可变结果快照。000024 增加固定流程版本的查询范围。迁移自身另有 `orbit_schema_migrations` 记录。

 | 模块 | Go 模型 | 数据表 |
 | --- | --- | --- |
@@ -65,6 +65,7 @@
 | pulse | `Occurrence` | `pulse_schedule_occurrences` |
 | weave | `Definition` | `weave_definitions` |
 | weave | `DefinitionVersion` | `weave_definition_versions` |
+| weave | `VersionScope` | `weave_version_scopes` |
 | weave | `Instance` | `weave_instances` |
 | weave | `Step` | `weave_steps` |
 | weave | `Activation` | `weave_activations` |
@@ -230,3 +231,9 @@ PollState新增FirstRound和FirstRoundAttemptsUsed，记录当前激活的首个
 ## 流程历史查询索引

 000023_workflow_signal_history只为weave_signals增加(namespace_id,workflow_id,accepted_at,id)分页索引，保留全部原信号数据和状态。仍为35个持久化实体/305个直接字段声明，无新增字段或外键；HTTP/SDK的摘要和详情字段均有中文注释。[历史查询](api/workflow-history.md)明确区分当前逻辑步骤与指定历史激活，不以当前代次替换旧来源。基础测试禁止000008之后再次引入数据库引用约束，真实MySQL升级及readiness验证外键为0。
+
+## 固定版本查询范围与实例分页（000024）
+
+VersionScope新增6个中文注释字段：命名空间、定义版本、定义、原摘要、去重队列JSON、索引创建时间；当前36个实体、311个直接持久化字段声明，全部有中文注释。版本范围不可更新，发布与范围同事务，读取摘要还要核验原定义和关联，不以派生索引授予权限。回填仅遍历DSL步骤，忽略常量中相同字段；旧版本及实例原文不修改。
+
+7个新实例复合索引加现有业务键索引覆盖定义/业务键/状态8种组合，按创建时间与ID分页；全部保留无外键和无级联。范围校验、迁移性能边界和接口见[查询手册](api/workflow-queries.md)。
--- a/docs/08-development-plan.md
+++ b/docs/08-development-plan.md
@@ -28,28 +28,28 @@
 | P1 任务受理闭环 | 应用凭据与作用域权限、队列、幂等提交、查询、待执行取消、受理事件；SDK 客户端 | API/SDK 创建查询闭环；重复键与内容冲突、响应未确认重报、跨命名空间拒绝、参数边界 | 已完成并通过阶段回归（见 P1 报告；真实断路/提交 ACK 丢失注入留后续故障阶段） |
 | P2 Worker 执行闭环 | WSS 接入、能力/容量、领取与开始、租约、续租、结果确认、排空与恢复；Worker SDK | 真 Worker 执行；失联/重连/重复确认/旧尝试拒绝；业务效果未知转核查；节点故障接管 | 已完成并通过阶段回归：服务端、自动 SDK、历史查询、完整 Schema 与真实进程强杀恢复；测试拓扑和剩余生产故障矩阵见 P2 验收报告 |
 | P3 Pulse 完整能力 | 安全重试、延时、Cron/固定间隔、漏跑策略、计划版本、运行中取消、并发许可、配额/背压、可靠结果订阅、批量受理、独立任务核查/人工重试、查询筛选与事务Outbox接入 | 多实例领取/触发竞争、重试上限、取消竞争、队列隔离、积压恢复、事件重复交付 | 已完成平台功能阶段验收：[原范围逐项核对](reports/phase-3.md)、[本轮完整回归](reports/phase-3-delay-recovery.md)。补齐相对延迟、改参数关联示例和四种重试全停恢复场景；20个可运行示例全部通过。全平台生产门槛及SDK首版交付剩余项仍按P6–P7推进 |
-| P4 Weave 主流程 | SDK 定义构建与发布校验、实例、顺序/分支/结构化并行汇合、信号/定时等待、版本绑定 | 重启接续、早到/重复信号、并行竞争、内部事件重放、发布版本兼容；端到端通用流程 | 定义格式/词法类型校验、不可变发布、独立SDK及六类节点定义例子已实现，已通过[子项验收](reports/phase-4-definitions.md)；已补[有限决策器及内部结果交付](reports/phase-4-engine-core.md)；[实例受理及首批事务](reports/phase-4-admission.md)已实现；[结果消费和根接续](reports/phase-4-runtime.md)已接入后台，顺序/分支/并行及真实进程恢复已验证；[TIMER与后续POLL轮次](13-workflow-clock.md)已接入；[信号消费和最终查询竞争](14-workflow-signals.md)已接入内部运行器；[内部控制与停止结清](15-workflow-controls.md)已接入；[内部核查与TASK新激活](16-workflow-recovery.md)已接入；等待恢复已接入内部服务；实例公共API/SDK与基础可运行场景已接入；流程任务来源已接入；历史激活/轮次/信号与信号审计已接入；实例列表、统一事件时间线范围核对与更多场景继续开发 |
-| P5 Weave 恢复与查询 | 有界查询、暂停继续、取消、人工核查恢复、控制门控与审计 | 轮次与尝试独立预算；暂停/开始/回执/超时竞争；恢复保留预算；未知结果不盲目重复 | 有界查询轮次/尝试独立预算及原截止恢复已接入内部运行器；最终信号竞争及在途查询结清已接入；内部暂停/继续/取消与失败结清已接入；执行核查、步骤结论、解除核查及TASK新激活已接入；[POLL跨激活恢复](17-workflow-poll-recovery.md)已接入；等待恢复已接入内部服务；公共API/SDK已接入；流程任务来源已接入；历史激活/轮次/信号与信号审计已接入；实例列表、统一事件时间线范围核对与更多场景继续开发 |
+| P4 Weave 主流程 | SDK 定义构建与发布校验、实例、顺序/分支/结构化并行汇合、信号/定时等待、版本绑定 | 重启接续、早到/重复信号、并行竞争、内部事件重放、发布版本兼容；端到端通用流程 | 定义格式/词法类型校验、不可变发布、独立SDK及六类节点定义例子已实现，已通过[子项验收](reports/phase-4-definitions.md)；已补[有限决策器及内部结果交付](reports/phase-4-engine-core.md)；[实例受理及首批事务](reports/phase-4-admission.md)已实现；[结果消费和根接续](reports/phase-4-runtime.md)已接入后台，顺序/分支/并行及真实进程恢复已验证；[TIMER与后续POLL轮次](13-workflow-clock.md)已接入；[信号消费和最终查询竞争](14-workflow-signals.md)已接入内部运行器；[内部控制与停止结清](15-workflow-controls.md)已接入；[内部核查与TASK新激活](16-workflow-recovery.md)已接入；等待恢复已接入内部服务；实例公共API/SDK与基础可运行场景已接入；流程任务来源已接入；历史激活/轮次/信号与信号审计已接入；实例筛选分页已接入；统一事件时间线范围核对与更多场景继续开发 |
+| P5 Weave 恢复与查询 | 有界查询、暂停继续、取消、人工核查恢复、控制门控与审计 | 轮次与尝试独立预算；暂停/开始/回执/超时竞争；恢复保留预算；未知结果不盲目重复 | 有界查询轮次/尝试独立预算及原截止恢复已接入内部运行器；最终信号竞争及在途查询结清已接入；内部暂停/继续/取消与失败结清已接入；执行核查、步骤结论、解除核查及TASK新激活已接入；[POLL跨激活恢复](17-workflow-poll-recovery.md)已接入；等待恢复已接入内部服务；公共API/SDK已接入；流程任务来源已接入；历史激活/轮次/信号与信号审计已接入；实例筛选分页已接入；统一事件时间线范围核对与更多场景继续开发 |
 | P6 生产验证与运维 | 完整监控、凭据轮换、备份恢复、滚动升级、运行手册、可复现负载和故障工具 | 对照生产验收清单执行，报告环境/指标/遗留项；容量、RPO/RTO 按真实拓扑验证 | 待开发 |
 | P7 首版交付核对 | SDK 兼容与发布准备、完整 API 手册、场景示例、全量回归及交付清单 | 新接入者按文档跑通全部示例；所有首版能力可追溯到实现与测试；报告实际生产边界 | 待开发 |

 SDK、文档与示例随 P1–P5 同步开发，P7 是全量核对，不是最后才开始补文档。

-P4/P5定时等待与后续查询轮次的实现及回归记录见[时钟报告](reports/phase-4-clock.md)。外部信号与最终查询竞争见[信号报告](reports/phase-4-signals.md)。公共实例、控制、信号、六类恢复和操作审计已接入HTTP与独立SDK，见[公共接入报告](reports/phase-5-public-api.md)。流程任务来源及[历史查询](api/workflow-history.md)已接入，实例列表、统一事件时间线及更多恢复示例仍须核对交付。
+P4/P5定时等待与后续查询轮次的实现及回归记录见[时钟报告](reports/phase-4-clock.md)。外部信号与最终查询竞争见[信号报告](reports/phase-4-signals.md)。公共实例、控制、信号、六类恢复和操作审计已接入HTTP与独立SDK，见[公共接入报告](reports/phase-5-public-api.md)。流程任务来源及[历史查询](api/workflow-history.md)已接入，[实例筛选分页](api/workflow-queries.md)已接入，统一事件时间线及更多恢复示例仍须核对交付。

 ### P4/P5 下一步实施顺序

 1. 已实现FAIL_AFTER_SETTLED与显式取消的内部分支结清，见[控制报告](reports/phase-5-controls.md)：持久取消意图、复用Pulse取消、收集已发出查询/任务结果、等待全部已激活工作结清后才进入失败或取消终态。效果未知仍保留核查。
 2. 已实现实例暂停/继续/取消内部操作，以control_revision、操作幂等身份、明确原因及审计保护控制决定；暂停不延长原截止，继续不覆盖核查或取消状态。
 3. 已实现内部执行核查、步骤结论、解除核查及TASK新激活和旧激活隔离，见[核查报告](reports/phase-5-recovery.md)。POLL跨激活恢复已实现（见[查询恢复](17-workflow-poll-recovery.md)）；[核查后PENDING接续和独立等待重建](18-workflow-wait-recovery.md)也已接入内部服务，保留原预算、轮次、结果和证据。
-4. 实例/当前步骤/信号/控制/六类恢复及流程操作审计HTTP和独立SDK已接入，步骤查询返回实际激活代次；并行执行与信号回执场景已有可运行示例。激活/轮次/信号历史及信号资源审计已接入；继续补齐实例筛选分页、核对统一状态事件时间线，并提供独立轮询及恢复示例；[Pulse任务流程来源](api/task-source.md#5-流程固定来源)已交付。逐项验证原键恢复、权限、版本冲突、竞争与进程全停。
+4. 实例/当前步骤/信号/控制/六类恢复及流程操作审计HTTP和独立SDK已接入，步骤查询返回实际激活代次；并行执行与信号回执场景已有可运行示例。激活/轮次/信号历史及信号资源审计已接入；实例筛选分页已接入；继续核对统一状态事件时间线，并提供独立轮询及恢复示例；[Pulse任务流程来源](api/task-source.md#5-流程固定来源)已交付。逐项验证原键恢复、权限、版本冲突、竞争与进程全停。
 5. 转入P6/P7的生产故障、容量、运维、发布与全部文档核对。内部存储阶段通过不会提前勾选公共接口或生产验收。

-公共接入按以下调用链推进；本批已接入启动/当前详情、控制、信号、六类恢复和流程操作审计，并提供独立SDK及基础示例。任务流程来源和有界历史查询也已接入。以下实例分页、统一事件时间线范围核对和更多独立场景继续交付：
+公共接入按以下调用链推进；本批已接入启动/当前详情、控制、信号、六类恢复和流程操作审计，并提供独立SDK及基础示例。任务流程来源和有界历史查询也已接入。实例分页和独立查询示例已接入；以下统一事件时间线范围核对和更多独立场景继续交付：

 | 调用链 | 需要补齐的内容 | 验收重点 |
 | --- | --- | --- |
-| 启动与读取 | 显式固定版本启动、当前实例、步骤及当前激活代次；已补有界历史读取，后续补筛选分页 | 原键丢回执恢复、当前权限、读取快照一致性、未激活步骤语义 |
+| 启动与读取 | 显式固定版本启动、当前实例、步骤及当前激活代次；已补有界历史读取及实例筛选分页 | 原键丢回执恢复、当前权限、读取快照一致性、未激活步骤语义 |
 | 控制与信号 | 暂停/继续/取消、固定步骤和代次的信号提交及原受理回执 | control_revision与通用revision区分、迟到/旧代次、暂停期间结果收集 |
 | 核查与追踪 | 六类恢复、激活/轮次/等待/信号历史读取及信号管理审计已接入；统一状态事件时间线待核对；Pulse任务流程来源已交付 | 当前实例/步骤/任务版本、证据和显式声明、旧历史保留、有界响应和权限隔离 |
 | 通用接入场景 | 并行汇合、外部回执、有限轮询、暂停核查恢复的可运行SDK示例 | 真实Worker执行、完整进程退出后接续、未知效果保留、全链路回归 |
@@ -130,6 +130,10 @@ P4/P5定时等待与后续查询轮次的实现及回归记录见[时钟报告](

 ## 7. 文档入口

+- [实例筛选分页与SDK](api/workflow-queries.md)
+- [实例查询示例](examples/workflow-query.md)
+- [实例查询验证记录](reports/phase-5-queries.md)
+
 - [流程历史查询与SDK](api/workflow-history.md)
 - [历史查询验证记录](reports/phase-5-history.md)
 - [流程实例公共API](api/workflows.md)
--- a/docs/README.md
+++ b/docs/README.md
@@ -89,3 +89,5 @@ Orbit 不内置特定行业规则；Pulse 管理执行，Weave 管理步骤依
 2026-09-17，文档更新至 0.2：用户确认研发定义发布流程及 Weave 首版功能，明确纳入有界重复查询和暂停/继续等生产管理能力。技术细则与参数继续按建议或待定标注，未将功能确认等同于实现或验收通过。

 持续开发目标已建立。当前实现和验收进度以 [开发计划](08-development-plan.md)、[P0 报告](reports/phase-0.md)、[P1 报告](reports/phase-1.md) 与 [P2 阶段验收](reports/phase-2.md) 、[P3 安全重试报告](reports/phase-3-safe-retry.md) 、[P3 计划调度报告](reports/phase-3-schedules.md) 和 [P3 完整范围验收](reports/phase-3.md) 为准；早期设计稿中的“未实现”描述保留其编写阶段语境。
+
+[实例查询接口与SDK](api/workflow-queries.md)已接入，固定筛选沿游标分页，覆盖未执行分支的全部队列权限。
--- a/docs/api/README.md
+++ b/docs/api/README.md
@@ -49,3 +49,5 @@ P1 业务接口已遵守下述约定，后续接口继续沿用：
 ## 每个正式接口的文档模板

 实现时必须补齐：用途与权限、HTTP 方法和路径、请求头、字段类型/必填/默认值/限制、完整请求与响应、错误码、幂等与并发规则、超时/重试/取消语义、SDK 对应方法、可运行示例、兼容版本和已覆盖的回归场景。
+
+[流程实例筛选分页与权限](workflow-queries.md)已接入，固定筛选沿游标分页，覆盖未执行分支的全部队列权限。
--- a/docs/api/workflow-queries.md
+++ b/docs/api/workflow-queries.md
@@ -0,0 +1,114 @@
+# 流程实例筛选与分页
+
+状态：已实现HTTP和独立Go SDK。查询返回有限元数据，不聚合业务输入输出。单个实例的完整视图和步骤详情见[实例接口](workflows.md)，历史激活、轮次与信号见[历史查询](workflow-history.md)。
+
+## 接口与权限
+
+`GET /v1/workflows`，要求显式 `workflows:read`。命名空间取自认证凭据，不接受查询参数覆盖；返回的每个实例必须满足其**启动时固定定义版本的全部队列权限**，包含尚未执行的分支、后续步骤和POLL队列。只拥有某个已生成任务的权限不代表可以读整个流程。
+
+没有权限覆盖的实例在数据库中被过滤。指定定义/版本但当前范围没有匹配项，返回空列表；该结果不能用于断言资源不存在。只有SIGNAL/TIMER且不引用队列的版本仍需要 `workflows:read`，队列集合为空。不额外要求 `tasks:read` 或定义发布权限。
+
+| 参数 | 语义 |
+| --- | --- |
+| `definition_id` | 可选，32位小写十六进制定义ID；不传则查询命名空间内可读实例 |
+| `version` | 可选，必须同时指定definition_id；1–64位发布版本名，首位字母/数字，后续可含`_ . -` |
+| `state` | 可选：RUNNING、WAITING、CANCELLING、NEEDS_REVIEW、SUCCEEDED、FAILED、CANCELLED |
+| `paused` | 可选，只接受`true`或`false`；与state独立，false不等于不筛选 |
+| `business_key` | 可选，非空且最多191个Unicode字符，无NUL；精确匹配，保留大小写、换行和尾部空格，URL必须正确编码 |
+| `created_from` | 创建时间下界，包含；RFC3339，最多微秒精度 |
+| `created_before` | 创建时间上界，不包含；与下界同时提供时必须晚于下界 |
+| `limit` | 默认20，1–100 |
+| `cursor` | 上一页next_cursor，最多1024字节 |
+
+时间规范化到UTC，UTC年份2000–9998；拒绝微秒以下精度。拒绝未知、重复、空值参数和无效URL编码。业务键空字符串在SDK中表示不筛选；HTTP显式`business_key=`被拒绝，首版不提供“只查无业务键”条件。
+
+请求示意：
+
+```http
+GET /v1/workflows?definition_id=11111111111111111111111111111111&version=v1&state=WAITING&paused=false&business_key=object-001%20&limit=20
+Authorization: Bearer <private-token>
+```
+
+响应信封使用 `request_id` 与 `data`：
+
+```json
+{
+  "request_id": "example-request",
+  "data": {
+    "items": [{
+      "id": "22222222222222222222222222222222",
+      "namespace_id": "33333333333333333333333333333333",
+      "definition_id": "11111111111111111111111111111111",
+      "definition_version_id": "44444444444444444444444444444444",
+      "version": "v1",
+      "state": "WAITING",
+      "revision": "2",
+      "paused": false,
+      "control_revision": "1",
+      "business_key": "object-001 ",
+      "deadline_at": "2026-09-18T01:00:00Z",
+      "created_at": "2026-09-18T00:00:00Z",
+      "updated_at": "2026-09-18T00:00:00Z"
+    }]
+  }
+}
+```
+
+摘要另可包含 `cancel_requested_at`、`stop_kind`、`stop_requested_at`、`completed_at`。版本数值使用十进制字符串；state和paused可以独立变化。没有 `input`、`output`、定义正文或策略快照，读取正文使用 `GetWorkflow`。空列表为 `items: []`；没有更多结果时省略 `next_cursor`。
+
+## 翻页一致性
+
+按 `created_at DESC, id DESC` 排序，两个字段共同定位，时间相同也不会因只按时间定位而漏项。每页最多返回100条，数据库读取最多limit+1个候选用于判断下一页。队列范围在LIMIT前筛选，不全量加载后在Go中裁剪。
+
+游标绑定命名空间、全部筛选和规范化队列权限范围，不绑定页长。后续页可调整limit，不能删掉筛选重试；不同权限范围必须重新从第一页查询。队列权限顺序变化不影响游标。游标不授予权限，每页仍重新认证并核验版本归属和原定义。
+
+分页不提供跨页数据库快照。期间新建的较新实例不会出现在已有游标后，状态或paused变化可能令实例进入或离开筛选。需要长期同步应另外设计有提交水位的事件消费，不能拿列表游标代替结果订阅确认。
+
+## SDK
+
+```go
+paused := false
+query := orbit.ListWorkflowsRequest{
+    DefinitionID: definitionID,
+    Version: "v1",
+    State: "WAITING",
+    Paused: &paused,
+    BusinessKey: "object-001 ",
+    CreatedFrom: &from,
+    CreatedBefore: &before,
+    Limit: 20,
+}
+for {
+    page, err := client.ListWorkflows(ctx, query)
+    if err != nil {
+        return err // 保留筛选；不能降级成全量查询
+    }
+    for _, item := range page.Items {
+        fmt.Println(item.ID, item.State, item.ControlRevision)
+    }
+    if page.NextCursor == "" {
+        break
+    }
+    query.Cursor = page.NextCursor
+}
+```
+
+这是函数内片段，完整初始化、发布、创建、分页和取消清理见[可运行示例](../examples/workflow-query.md)。SDK采用独立 `WorkflowSummary`，不引用服务端模型。
+
+## 存储与错误边界
+
+迁移000024增加 `weave_version_scopes`，保存每个不可变版本的完整去重队列集合和原内容摘要。发布版本与范围索引同事务，升级从原DSL节点结构回填，输入/输出常量中的同名queue_id不计入范围。模型与SQL字段均有中文注释，**没有外键或级联约束**。
+
+索引只协助SQL过滤。返回前仍严格验证原定义及其摘要、队列集合、固定版本/定义/门控归属和冻结策略；数据损坏时整页失败，不返回部分已读数据，也不把缺失范围解释为无需队列权限。范围中错误增加的队列可能使合法记录被隐藏，应通过数据库运维修复损坏，不能以放宽权限绕过。列表不验证实例的完整输入/输出正文；这些数据由单实例详情与运行器按固定契约核验。
+
+八种定义/业务键/状态组合使用固定复合索引；version与paused作为附加筛选。授权过滤稀疏或paused选择性低时，扫描行数可能高于返回行数，limit不是扫描上限。P6须评估队列权限分布、数据保留量、索引写放大和查询超时预算，当前回归不构成百万租户容量结论。
+
+| 情况 | 返回 |
+| --- | --- |
+| 参数、游标、筛选或权限指纹不匹配 | 400 / INVALID_ARGUMENT |
+| 无workflows:read | 403 / PERMISSION_DENIED |
+| 当前筛选无可读记录 | 200 / 空items |
+| 关联或范围损坏 | 拒绝返回该页；可能为404或内部错误，保留原请求定位数据，禁止自动删条件重试 |
+| 数据库暂不可用 | 保留原筛选及游标按有限退避重试，不解释为无匹配记录 |
+
+本迁移按维护窗口执行：先停止旧版本的流程发布写入，完成范围回填，再启动新版服务开放发布。回填后仍由旧节点发布会生成缺少范围索引的版本，新查询会拒绝返回，不能靠重试修复；不支持新旧发布写节点无协调并行升级。旧服务没有此GET集合接口，不支持时SDK返回服务端错误，不静默降级。验证记录见[本阶段报告](../reports/phase-5-queries.md)。
--- a/docs/api/workflows.md
+++ b/docs/api/workflows.md
@@ -169,3 +169,5 @@ ListWorkflowOperations接受HistoryPageRequest：limit默认20、范围1–100
 | 503 UNAVAILABLE / 网络异常 | 提交结果可能不明，保持原键和原命令核对；SDK不自动换键 |

 已实现路由之外的路径为404。回归证据和剩余交付范围见[公共接入报告](../reports/phase-5-public-api.md)。
+
+实例集合读取 `GET /v1/workflows` 已接入筛选分页，参数、权限及SDK见[查询手册](workflow-queries.md)。
--- a/docs/examples/workflow-query.md
+++ b/docs/examples/workflow-query.md
@@ -0,0 +1,48 @@
+# 按业务关联分页查找流程
+
+场景：一个对象关联多次处理流程，管理端需要按固定定义版本、精确业务关联及时间范围查询等待中的实例，再进入详情处理。示例同时证明业务键末尾有无空格属于不同关联。
+
+源码：[workflow-query/main.go](../../sdk/go/examples/workflow-query/main.go)。服务端入口：[筛选接口](../api/workflow-queries.md)。示例发布一个SIGNAL等待流程，创建三个实例，其中两个使用相同业务键、第三个去掉尾部空格；每页1项读取匹配的两个实例，最后将三个实例取消并等待CANCELLED。
+
+## 启动
+
+需要已完成迁移的Orbit、MySQL 8.4+与Go 1.27.1。从仓库根目录使用专用开发数据库运行：
+
+```sh
+go run ./cmd/orbit-migrate up
+mkdir -p .local
+chmod 700 .local
+go run ./cmd/orbit-admin bootstrap \
+  --application query-example --namespace default --environment development \
+  --queue work --workflow-access --workflow-run-access --workflow-control-access \
+  --output .local/workflow-query.credentials.json
+go run ./cmd/orbit
+```
+
+另开终端：
+
+```sh
+cd sdk/go
+ORBIT_URL=http://127.0.0.1:8080 \
+ORBIT_CREDENTIALS_FILE=../../.local/workflow-query.credentials.json \
+go run ./examples/workflow-query
+```
+
+查询本身只要求workflows:read。此完整示例额外需要研发创建/发布、启动与控制权限，由上述bootstrap选项授予。SIGNAL等待不用Worker，也不模拟外部业务成功；正常结束通过显式取消结清。
+
+预期输出：
+
+```text
+workflow_query_verified=true matched=2 pages=2 exact_trailing_space=true
+workflow_query_cleanup=CANCELLED count=3
+```
+
+每次独立运行生成新的操作身份与定义，单次运行内发布/启动/控制分别保留稳定操作身份。输入为JSON null，输出契约为外部回执布尔值，本例不提交回执。流程120秒总时限保持有限。
+
+## 错误与清理
+
+无授权、发布失败、筛选丢失、重复项、取消失败均非零退出。输出不含凭据。网络失败不自动创建新操作或换筛选；正式业务应先持久保存请求、定义ID和原操作键，再按[实例接口](../api/workflows.md)恢复回执。
+
+正常结束保留定义、版本、已取消实例和审计。若中途退出，已有等待保留原绝对截止，不直接删除运行数据；查询当前实例，按最新control_revision发起有原因的取消，存在未知效果则进入核查流程。示例不会更改已有实例，也不清空数据库；连续运行会累积定义，达到每命名空间100个定义的上限应使用新的隔离演示命名空间，不删除生产历史规避限制。
+
+`make integration`在一次性数据库中启动真实Orbit，验证SDK与本例，并清理该次容器。跨页不是快照，实际管理界面应允许刷新第一页，并保留后续页的全部查询条件。
--- a/docs/reports/phase-5-queries.md
+++ b/docs/reports/phase-5-queries.md
@@ -0,0 +1,53 @@
+# P4/P5 实例筛选分页验证记录
+
+日期：2026-09-18。范围为 `GET /v1/workflows`、独立SDK `ListWorkflows`、固定版本查询范围迁移和完整分页示例。P4/P5整体与P6/P7仍未完成；下一项是统一状态事件时间线范围核对、独立轮询/恢复场景和阶段验收。
+
+## 实现与边界
+
+- 认证命名空间内按定义、固定版本、状态、paused、精确业务键、创建时间筛选；默认20、最多100条摘要，不读取实例的大输入输出。
+- SQL在LIMIT前按固定版本全部队列过滤，包含未执行分支。范围不是授权真相，返回前仍校验原定义/摘要、队列、固定版本/定义/门控归属及策略。
+- 游标绑定命名空间、全部规范化筛选和当前队列范围；同一时间戳用ID定位。拒绝改筛选、权限范围变化、重复或歧义JSON，不承诺跨页快照。
+- 000024只新增派生范围表、不可更新触发器及7个复合索引；回填遍历DSL步骤块，保留原版本/实例。最终表结构外键为0，无级联。当前36个模型、311个直接持久化字段有中文注释。
+- HTTP严格解析参数；SDK与服务端保持独立module。独立示例发布等待流程、验证精确分页、取消结清，不需Worker，也不模拟业务成功。
+
+接口：[查询手册](../api/workflow-queries.md)。示例：[运行说明](../examples/workflow-query.md)及[源码](../../sdk/go/examples/workflow-query/main.go)。
+
+## 环境与命令
+
+macOS arm64、Go 1.27.1、Docker MySQL 8.4.10，一次性隔离数据库。服务端编译为真实进程，SDK通过真实HTTP访问；原有Worker、恢复及订阅链路继续通过WSS回归。未使用生产数据库。
+
+```sh
+make fmt test vet build
+DOCKER=/usr/local/bin/docker make integration
+```
+
+本地工具链经Makefile的GO变量显式选择。隔离脚本只清理本次数据库容器与临时普通文件，不删除业务目录。完整脚本保留全部既有回归，增加实例查询SDK及第21个SDK示例。
+
+## 已验证
+
+| 验证 | 结果 |
+| --- | --- |
+| fmt、race单元回归、vet、服务端及独立业务示例构建 | 通过 |
+| 真实MySQL升级与定义发布基础：v7外键、v9额度旧库、模型列映射 | 通过，旧70条外键→0，323个原索引组成部分保留 |
+| 实例查询4组：8种索引组合、相同时间分页、时间边界、精确键、paused、游标及跨命名空间 | 通过 |
+| 全固定版本队列鉴权 | 通过，后续任务尚未生成时仍受第二队列权限约束；发布v2不改变v1实例范围 |
+| 无队列版本、缺失/缩小范围、策略损坏及动作权限 | 通过，拒绝损坏数据并不返回部分页 |
+| v23→v24升级 | 通过，嵌套PARALLEL/BRANCH/TASK/POLL范围正确、重复去重、常量伪queue_id排除、原版本全部字段保持、7个新增索引列序正确、外键0 |
+| 独立SDK真实HTTP | 通过，精确键/时间/版本/paused=false/游标/非法查询及三个实例取消结清 |
+| 定义与五组原流程SDK回归、原workflow示例 | 通过 |
+| workflow-query独立例子 | 通过，matched=2、pages=2、三个实例CANCELLED |
+| 完整标准集成脚本 | 通过，退出码0；21个SDK示例、2个独立业务模块、流程与Worker/订阅进程故障回归全部完成 |
+
+定向存储回归11.951秒，SDK组27.361秒，其中查询SDK2.92秒。上述数字仅是本次测试执行耗时，不是性能指标。持久化模型中文注释校验311项，缺失0；Markdown检查1067个本地链接、66个JSON块，错误0。
+
+全量回归中存储测试222.089秒、流程进程恢复49.000秒、流程SDK组26.665秒（查询SDK2.87秒）、最终Worker/订阅进程故障组95.296秒。独立Inbox/Outbox分别35.641秒/33.862秒。以上均通过，日志未出现失败。
+
+本轮定向回归最初发现三处测试夹具问题：第二队列缺少必填配额、共享Go指针同时改了多个节点导致预期队列数错误、拒绝权限的预期错误码写错。已修复夹具并完整重跑定向链路；升级逻辑没有通过放宽范围或移除校验使测试通过。
+
+## 未验证与交付余项
+
+- 没有百万租户/高选择性权限稀疏查询压测；limit限制返回候选，不保证数据库扫描行数。每页最多验证101个固定版本、队列统一排序校验；大定义、队列集合与7个新增索引的读写开销须纳入P6容量测试。
+- 没有真实生产主从切换、跨故障域高可用或生产备份恢复结论；本地既有进程强杀回归不能替代这些验收。
+- 迁移需先停止旧版本的流程发布写入，回填后由新版接管；未实现新旧发布写节点无协调并行升级。迁移全量回填既有版本，并为实例增加索引；大库需测量DDL时长、额外磁盘和维护窗口。历史定义结构损坏可能导致迁移失败，应先核查数据，不能跳过迁移或修改历史校验记录。
+- 派生范围被错误增大可能隐藏合法结果；必须保护数据库写权限并按原定义核查修复，不通过放宽业务权限绕过。关联一致性仍由代码事务保证，不引入外键。
+- 原定统一事件时间线范围核对、更多独立场景、P4/P5全范围审计和P6/P7持续推进。
--- a/docs/sdk/README.md
+++ b/docs/sdk/README.md
@@ -206,3 +206,5 @@ P2 已提供底层协议、[自动 Worker 运行器及示例](worker-runtime.md)
 已提供独立WorkflowSpecification类型及CreateWorkflowDefinition、GetWorkflowDefinition、PublishWorkflowVersion、GetWorkflowVersion四个HTTP方法。业务侧研发显式发布，服务端冻结版本；实例执行使用[StartWorkflow等方法](../api/workflows.md)，完整运行见[示例](../examples/workflow.md)。见[接口与字段](../api/workflow-definitions.md)、[结构版本1](../api/workflow-definition-format.md)、[完整可运行场景](../examples/workflow-definition.md)。

 流程任务同样调用`GetTaskSource`，kind为WORKFLOW时读取workflow中的固定版本、步骤、历史激活代次、查询轮次和直接恢复父任务。该代次不表示当前等待目标；发送信号须另读GetWorkflowStep。完整字段及兼容边界见[来源接口](../api/task-source.md#5-流程固定来源)，[workflow示例](../examples/workflow.md)实际核对三个任务来源。
+
+[ListWorkflows及完整查询示例](../api/workflow-queries.md)已接入，固定筛选沿游标分页，覆盖未执行分支的全部队列权限。