@stalfh233/omc-cli 0.6.15 → 0.6.17

package/dist/lanes/businessrule.js

@@ -141,12 +141,25 @@ export function registerBusinessRuleLane(tools) {
             // key (schemaCode+ruleCode), so the row id is rarely needed.
             const fullRows = args.full === true;
             const visible = args.onlyCustom === true ? rows.filter((row) => row.defaultRule !== true) : rows;
+            const statusLag = visible.some((row) => row.enabled === true && String(row.status ?? "") !== "ENABLED");
             return {
                 schemaCode: args.schemaCode,
                 modelPresent: true,
                 // r28g F18：list 投影的是 PUBLISH 行；运行时可执行性以 rule.get / rule.enable.verified 为准。
                 source: "published-list",
                 executableHint: "rules[].enabled/status 来自 PUBLISH 投影；运行时判定读 DRAFT（rule.get 的 enabled+ruleStatus，或 rule.enable 回执的 executable/verified）。不要仅凭本面判定可 rule.run。",
+                ...(statusLag
+                    ? {
+                        statusLag: true,
+                        statusNote: "本面 status 是 PUBLISH 投影列，与 rule.get 的 ruleStatus 可不同；检测到 enabled=true 而 status 非 ENABLED 的滞后行——enabled=true 才是分发真相，运行时以 rule.get/enable 复核",
+                    }
+                    : {
+                        // r35a-F7（真机 2026-11-06）：`status` 与 rule.get 的 `ruleStatus` 是
+                        // **不同 wire 列**，可一个 ENABLED 一个 DISABLED（探针实测
+                        // list status=ENABLED/ruleVersion=1 vs get ruleStatus=DISABLED/0）。
+                        // 常态化给一句短注（~90B/次），避免把本面 status 当运行时真相。
+                        statusNote: "本面 status 是 PUBLISH 投影列，与 rule.get 的 ruleStatus 可不同；运行时是否生效以 rule.get/enable 为准",
+                    }),
                 ...(args.onlyCustom === true ? { filtered: { onlyCustom: true, total: rows.length, returned: visible.length } } : {}),
                 ...(endpointFamily ? { endpointFamily } : {}),
                 rules: visible.map((row) => ({
@@ -154,6 +167,7 @@ export function registerBusinessRuleLane(tools) {
                     name: row.name,
                     enabled: row.enabled,
                     status: row.status,
+                    ...(row.enabled === true && String(row.status ?? "") !== "ENABLED" ? { statusLag: true } : {}),
                     ...(row.ruleVersion !== undefined ? { ruleVersion: row.ruleVersion } : {}),
                     ...(row.defaultRule !== undefined ? { defaultRule: row.defaultRule, preset: row.defaultRule === true } : {}),
                     // ticket-80's update-mode readback teaches following the same-code
@@ -270,6 +284,14 @@ export function registerBusinessRuleLane(tools) {
                 code: wanted,
                 scanned: { models: scoped.length, rules: scannedRules, ...(parseFailures > 0 ? { parseFailures } : {}) },
                 matches,
+                // r35a-F4（真机 2026-11-06）：matches:[] 曾被当成「可安全删除」的依据，
+                // 而探针实测该字段**被表单引用**（form.get draftControlCodes）且出现在
+                // 流程节点权限里——本面两者都没扫。散文字段不承担安全契约：结构化声明。
+                coverage: {
+                    scanned: ["businessrule"],
+                    notScanned: ["datarule", "form", "workflow.permissions", "workflow.bindings", "onlinejs", "listview"],
+                    note: "matches:[] 只代表 businessrule 面零命中；datarule/form/流程权限/视图等未扫描（离线 graph references 覆盖更广，见其 coverage），不可据此判定可安全删除",
+                },
                 ...(scope !== undefined ? { applicationResolution: applicationResolutionOf(scope) } : {}),
                 ...(matches.length === 0
                     ? {

package/dist/lanes/field.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { ENDPOINTS } from "../endpoints.js";
 import { fieldChangeWireBody, fieldUpdateWireBody, prepareFieldChange, prepareFieldUpdate } from "../field-change.js";
-import { aggregationSelfSchemaMessage, aggregationTargetsOwnSchema, choicesArg, childColumnsOf, FIELD_PROPERTY_TYPES, fieldOptionsArg, fieldTypeLabel, numericalScaleWarning, propertyTypeArg, relativeCodeArg, stripAggregationPrefix, subFieldArg, SYSTEM_FIELD_CODES, } from "../field-families.js";
+import { aggregationSelfSchemaMessage, aggregationTargetsOwnSchema, choicesArg, childColumnsOf, FIELD_PROPERTY_TYPES, fieldOptionsArg, fieldTypeLabel, numericalScaleWarning, propertyTypeArg, relativeCodeArg, stripAggregationPrefix, subFieldArg, SYSTEM_FIELD_CODES, assertFieldFamilyAllowed, assertSelectionChoicesAllowed, } from "../field-families.js";
 import { capabilityArg, environmentArg } from "../args.js";
 import { governedRead } from "../read.js";
 import { writeTool } from "../write.js";
@@ -442,6 +442,10 @@ export function registerFieldLane(tools) {
                 },
             };
         },
+        preflight: (args) => {
+            assertSelectionChoicesAllowed(args);
+            assertFieldFamilyAllowed(args);
+        },
         rollback: fieldRollbackSpec("field.create"),
     });
     writeTool({
@@ -732,10 +736,12 @@ async function fieldUpdateDryRun(session, args) {
                 }),
         };
     }
+    const impact = await collectFieldDeleteImpact(session, args, { full: true });
     return {
         wouldChange: changes.length > 0,
         changes,
         ...(dataImpact !== undefined ? { dataImpact } : {}),
+        impact,
         schemaCode: args.schemaCode,
         code: args.code,
     };
@@ -951,6 +957,11 @@ async function collectFieldDeleteImpact(session, args, options) {
         ...(counted.note ? { dataRowsNote: counted.note } : counted.dataRows === "unknown" ? { dataRowsNote: "拿不到行数：data.list total 不可用" } : {}),
         references,
         dependentUpdates: surfaces.dependentUpdates,
+        coverage: {
+            scanned: options.full ? ["businessrule", "form", "listview", "onlinejs", "data"] : ["form", "listview", "onlinejs", "data"],
+            notScanned: options.full ? ["workflow.permissions", "workflow.bindings", "rule.conditions"] : ["businessrule", "workflow.permissions", "workflow.bindings", "rule.conditions"],
+            coveredSurfaces: options.full ? ["businessrule", "form", "listview", "onlinejs", "data"] : ["form", "listview", "onlinejs", "data"],
+        },
         ...(unknowns.length > 0 ? { unknown: unknowns } : {}),
         note: options.full
             ? "完整影响面（规则+表单+视图+在线JS+行数）。删除不会自动清理依赖面残留。"
@@ -1062,6 +1073,7 @@ async function runFieldUpdate(session, args) {
         ...(args.propertyEmpty !== undefined ? ["propertyEmpty"] : []),
     ];
     const unverifiable = submittedPropertyEmpty !== undefined && !hasReadBackPropertyEmpty ? ["propertyEmpty"] : [];
+    const impact = await collectFieldDeleteImpact(session, args, { full: false });
     return {
         performed: { errcode: performed.errcode },
         ...(prepared.conditionCompiled !== undefined && prepared.conditionCompiled.length > 0
@@ -1069,6 +1081,7 @@ async function runFieldUpdate(session, args) {
             : {}),
         readback: {
             face: "draft",
+            impact,
             fieldPresent: after !== undefined,
             ...(after?.name !== undefined ? { name: after.name } : {}),
             ...(typeof after?.name_i18n === "string" ? { name_i18n: after.name_i18n } : {}),

package/dist/lanes/list-view.js

@@ -476,23 +476,6 @@ export function registerListViewLane(tools) {
             schemaCode: z.string().min(1),
             name: z.string().min(1),
             code: z.string().optional().describe("视图 code；省略时**默认取 schemaCode**（与 listview.get / listview.list / rollback 的默认视图口径一致）。平台侧 code 必填，本工具会替你填，不要再依赖不回执的猜测（r26 真机：不传直接被 errcode 10005「编码不能为空」拒绝，白跑一轮线上往返）"),
-            // r29b F5a: create 没有列参数。接受 fieldCodes 只是为了给可执行 nextCommand，
-            // 避免未知键算法给出「fieldCodes→code」这种南辕北辙的建议。
-            fieldCodes: z.array(z.string()).optional().describe("本工具不配列——若传了会拒绝并指引 listview.configure"),
-        },
-        // dry-run 不跑 execute——fieldCodes 必须在 preflight 拦，否则 dry-run 仍会放行。
-        preflight: (args) => {
-            if (Array.isArray(args.fieldCodes) && args.fieldCodes.length > 0) {
-                const code = args.code ?? args.schemaCode;
-                throw new ToolInputError({
-                    status: "error",
-                    blocker: "tool-input-invalid",
-                    tool: "listview.create",
-                    message: "listview.create 不接受列参数：先 create（schemaCode/name/code），再 listview.configure 配 fieldCodes。" +
-                        "不要把 fieldCodes 当成 create 的拼写错误去改成 code。",
-                    nextCommand: `omc call listview.configure --args '${JSON.stringify({ schemaCode: args.schemaCode, code, fieldCodes: args.fieldCodes })}'`,
-                });
-            }
         },
         execute: async (session, args) => {
             // r26 真机：`code` 在 schema 里可选，但三处读面/rollback 都用
@@ -500,16 +483,6 @@ export function registerListViewLane(tools) {
             // `errcode 10005 编码不能为空`，探针白跑一轮。默认视图 code 就是
             // schemaCode（listview.list 的 hint 也这么写），这里对齐。
             const code = args.code ?? args.schemaCode;
-            if (Array.isArray(args.fieldCodes) && args.fieldCodes.length > 0) {
-                throw new ToolInputError({
-                    status: "error",
-                    blocker: "tool-input-invalid",
-                    tool: "listview.create",
-                    message: "listview.create 不接受列参数：先 create（schemaCode/name/code），再 listview.configure 配 fieldCodes。" +
-                        "不要把 fieldCodes 当成 create 的拼写错误去改成 code。",
-                    nextCommand: `omc call listview.configure --args '${JSON.stringify({ schemaCode: args.schemaCode, code, fieldCodes: args.fieldCodes })}'`,
-                });
-            }
             // Ticket 81: read the header FIRST — a same-code retry short-circuits
             // with the existing view and sends ZERO create wires (the live
             // post-timeout retry otherwise answers 303002 编码重复).

package/dist/lanes/model.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { ENDPOINTS } from "../endpoints.js";
-import { assertFieldFamilyAllowed, choicesArg, fieldOptionsArg, nameI18nJson, propertyTypeArg, relationTargetOf, relativeCodeArg, SYSTEM_FIELD_CODES, subFieldArg, } from "../field-families.js";
+import { assertFieldFamilyAllowed, assertSelectionChoicesAllowed, choicesArg, fieldOptionsArg, nameI18nJson, propertyTypeArg, relationTargetOf, relativeCodeArg, SYSTEM_FIELD_CODES, subFieldArg, } from "../field-families.js";
 import { fieldChangeWireBody, prepareFieldChange, sameFieldChange } from "../field-change.js";
 import { executeFormDraftWrite, executeFormPublishWrite } from "../form-support.js";
 import { mapBounded } from "../support.js";
@@ -393,7 +393,11 @@ export function registerModelLane(tools) {
                 // delete). Same SYSTEM_FIELD_CODES set field.list uses.
                 const visibleColumns = all ? listviewColumns : listviewColumns.filter((column) => !SYSTEM_FIELD_CODES.has(String(column.propertyCode)));
                 const listview = listviewFace && listviewFace.columns
-                    ? { code: listviewFace.code ?? schemaCode, columnCount: visibleColumns.length, columns: visibleColumns.map((column) => ({ propertyCode: column.propertyCode, propertyType: column.propertyType, visible: column.visible })) }
+                    ? {
+                        code: listviewFace.code ?? schemaCode,
+                        columnCount: visibleColumns.length,
+                        columns: visibleColumns.map((column) => ({ propertyCode: column.propertyCode, propertyType: column.propertyType, visible: column.visible })),
+                    }
                     : undefined;
                 const ruleRows = Array.isArray(ruleFace?.rules) ? ruleFace.rules : [];
                 // All rules are kept: the platform pre-creates trigger rows (Create/Update/
@@ -433,6 +437,7 @@ export function registerModelLane(tools) {
                 const workflow = draftFace?.exists === false || (draftFace === undefined && publishedFace === undefined)
                     ? (draftFace && draftFace.schemaCode ? { exists: false } : undefined)
                     : {
+                        exists: true,
                         workflowCode: summary?.workflowCode ?? workflowCode,
                         published: publishedFace?.published === true || pubSummary?.templateType === "PUBLISH",
                         activities: Array.isArray(summary?.activities) ? summary.activities.map((activity) => ({ code: activity.code, type: activity.type, name: activity.name, participant: activity.participant })) : [],
@@ -447,6 +452,7 @@ export function registerModelLane(tools) {
                 const absent = fieldRefusalErrcode === 300004 || faceErrcodes.get("field.list") === 300004;
                 const modelPresent = absent ? false : fieldFace !== undefined && !fieldRefused ? true : undefined;
                 return {
+                    code: schemaCode,
                     schemaCode,
                     ...(modelName !== undefined ? { name: modelName } : {}),
                     ...(modelPresent !== undefined ? { modelPresent } : {}),
@@ -482,12 +488,24 @@ export function registerModelLane(tools) {
                     return result;
                 return {
                     schemaCode: result.schemaCode,
+                    // r35a-F3：compact 投影必须保留 code（model.list 有 code，inspect 此前
+                    // 只剩 schemaCode，`--jq '[].code'` 必 pathMiss 白跑一轮）。
+                    ...(result.code !== undefined ? { code: result.code } : {}),
                     fieldCodes: (result.fields ?? []).map((field) => field.code),
                     form: result.form,
                     listview: result.listview ? { code: result.listview.code, columnCount: result.listview.columnCount } : undefined,
                     ruleCodes: (result.rules ?? []).map((rule) => rule.code),
                     datarules: result.datarules,
-                    workflow: result.workflow ? { workflowCode: result.workflow.workflowCode, published: result.workflow.published } : undefined,
+                    // r35a-F2：workflow 摘要必须恒有 exists 布尔——compact 投影此前把它丢了，
+                    // 真机（走 compact 的分支）于是永远读不到 exists（探针只能靠
+                    // missedEntries 反推「缺失=有流程」，语义反直觉且有安全风险）。
+                    workflow: result.workflow
+                        ? {
+                            exists: result.workflow.exists !== false,
+                            workflowCode: result.workflow.workflowCode,
+                            published: result.workflow.published,
+                        }
+                        : { exists: false },
                     hint: result.hint,
                 };
             },
@@ -1299,6 +1317,8 @@ export function registerModelLane(tools) {
             ];
             if (violations.length > 0)
                 throw new ToolRefusalError({ status: "refused", blocker: "business-code-invalid", message: "code 未过出门前校验；按 validation 修正（长度/风格/保留字）", validation: violations });
+            for (const entry of entries)
+                assertSelectionChoicesAllowed(entry);
             for (const entry of entries)
                 prepareFieldChange(fieldChangeInputOf(args.code, entry));
         },
@@ -1495,8 +1515,10 @@ function fieldEntriesOf(args) {
     if (Array.isArray(args.fields) && args.fields.length > 0) {
         if (args.fieldCode !== undefined || args.fieldName !== undefined || args.propertyType !== undefined)
             throw new ToolRefusalError({ status: "refused", blocker: "configure-model-fields-exclusive", message: "fields[] 与单字段参数（fieldCode/fieldName/propertyType）互斥；多字段用 fields[]，单字段用旧三元组" });
-        for (const entry of args.fields)
+        for (const entry of args.fields) {
+            assertSelectionChoicesAllowed(entry);
             assertFieldFamilyAllowed({ ...entry });
+        }
         return args.fields.map((entry) => ({ code: entry.code, name: entry.name, propertyType: entry.propertyType, ...withLegacy(entry) }));
     }
     if (typeof args.fieldCode !== "string" || typeof args.fieldName !== "string" || typeof args.propertyType !== "string")
@@ -1506,6 +1528,7 @@ function fieldEntriesOf(args) {
             message: "configure_model 需要 fields[]（多字段）或 fieldCode+fieldName+propertyType（单字段）",
         });
     const legacy = { code: args.fieldCode, name: args.fieldName, propertyType: args.propertyType, ...withLegacy(args) };
+    assertSelectionChoicesAllowed(legacy);
     assertFieldFamilyAllowed(legacy);
     return [legacy];
 }

package/dist/lanes/organization.js

@@ -531,10 +531,17 @@ export function registerOrganizationLane(tools) {
             remarks: z.string().optional(),
             corpId: z.string().min(1).optional().describe("组织 corpId，默认当前登录企业；传 \"other\" 表示非组织分组角色"),
         },
-        execute: async (session, args) => {
+        preflight: (args) => {
             if (!args.roleGroupCode && !args.roleGroupId) {
-                throw new ToolInputError({ message: "必须给 roleGroupCode（推荐）或 roleGroupId；先 org.role.list 取 groups 码表" });
+                throw new ToolRefusalError({
+                    status: "refused",
+                    blocker: "role-group-required",
+                    nextCommand: "omc call org.role.list --args '{}'",
+                    message: "必须给 roleGroupCode（推荐）或 roleGroupId；先 org.role.list 取 groups 码表",
+                });
             }
+        },
+        execute: async (session, args) => {
             const { groups } = await readRoleTree(session);
             if (groups.length === 0) {
                 throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: "org.role.list 未解析出任何角色组；先确认组织树可读，不要盲建角色" });

package/dist/lanes/runtime-data.js

@@ -55,6 +55,7 @@ function dataListCompactProjection(result) {
             if (value.length > 0)
                 compact.listArtifactHint =
                     "items 已外置（truncatedKeys 含 items）：完整行见 artifact（detailArtifactId / fetch）。同信封三分法：ids=本页全部 id；itemsPreview=ids 前 3 个的引用（仅 {id}，不是第二份行）；items=[] 表示正文在 artifact。";
+            compact.itemsExternalized = true;
             continue;
         }
         // 这两个键由本函数按 items 现算，handler 不再重复内联。
@@ -921,12 +922,12 @@ export function registerRuntimeDataLane(tools) {
             columns: z.array(z.string().min(1)).optional().describe("列投影别名（=displayFields）"),
             // r29b F9: data.load/save/update 都叫 fields；list 面原先只有 displayFields/columns。
             fields: z.array(z.string().min(1)).optional().describe("列投影别名（=displayFields；与 data.load/data.save/data.update 的 fields 同语义）"),
-            orders: z.array(z.object({ field: z.string().min(1), dir: z.enum(["ASC", "DESC"]) })).optional(),
+            orders: z.array(z.object({ field: z.string().min(1), dir: z.enum(["ASC", "DESC"]) })).optional().describe("运行面 query/list 不支持服务端排序；排序请用 listview.configure 的 sorts（视图级）或在本地对 items 排序"),
             mobile: z.boolean().optional(),
             showTotal: z.boolean().default(true),
             page: z.number().int().min(0).default(0),
             size: z.number().int().min(1).max(200).default(10),
-            all: z.boolean().optional().describe("true 时自动翻页聚合全部结果（内部按 size=200 逐页拉取，安全上限 1000 行；超过时回 truncated:true + missingCount，别当全集）——存量盘点/数据核对用，替代手动循环翻页。与 page 互斥（all 固定从第 0 页起）"),
+            all: z.boolean().optional().describe("true 时自动翻页聚合全部结果（size=200 逐页，上限 1000 行，超出 resultTruncated:true）；与 page 互斥；默认 size=10，视图 pagingSetting.pageSize 不生效"),
             full: z.boolean().optional().describe("内联完整列表结果；默认大结果只返回计数与 detailFile"),
             // r31 (2026-10-31 real machine): agents pass `query: {field: value}` as a
             // filter — zod would STRIP the unknown key silently and the server
@@ -943,6 +944,14 @@ export function registerRuntimeDataLane(tools) {
                     tool: "data.list",
                     message: '没有 `query` 参数——过滤用 `filter: {"op":"eq","field":"<字段>","value":"<值>"}`（或 `filters` 数组=AND、`filterGroup` 嵌套）。r31 真机：`query:{...}` 被静默忽略、total 不变，极易误判为"无数据/已过滤"。',
                 });
+            if (args.orders !== undefined)
+                throw new ToolInputError({
+                    status: "error",
+                    blocker: "invalid-input",
+                    tool: "data.list",
+                    message: "运行面 query/list 不支持服务端排序；排序请用 listview.configure 的 sorts（视图级）或在本地对 items 排序。",
+                    nextCommand: `omc call listview.configure --env <env> --args '${JSON.stringify({ schemaCode: args.schemaCode, sorts: args.orders })}'`,
+                });
             let condition;
             let fromDsl = false;
             try {
@@ -1094,7 +1103,7 @@ export function registerRuntimeDataLane(tools) {
                     const firstPage = extractBizObjectPage(first.data);
                     const total = Number(firstPage.total ?? 0);
                     if (total === 0 || firstPage.content.length === 0)
-                        return { schemaCode: args.schemaCode, total: 0, page: "all", size: 0, pagesFetched: 0, items: [], ...(choiceFilterFields.length > 0 ? { filterValueHint: choiceFilterValueHint(choiceFilterFields) } : {}) };
+                        return { schemaCode: args.schemaCode, total: 0, page: "all", size: 0, pagesFetched: 0, items: [], itemsCount: 0, itemsReturned: 0, resultTruncated: false, itemsExternalized: false, ...(choiceFilterFields.length > 0 ? { filterValueHint: choiceFilterValueHint(choiceFilterFields) } : {}) };
                     const rows = [...firstPage.content];
                     const target = Math.min(total, CAP);
                     let pageIndex = 1;
@@ -1154,6 +1163,9 @@ export function registerRuntimeDataLane(tools) {
                         // 形状常量：脚本按 result.items 取数（与内联态一致），itemsCount 与
                         // total 的差就是被截断的条数——不再只靠 size 反推。
                         itemsCount: collected.length,
+                        itemsReturned: collected.length,
+                        resultTruncated: truncatedByCap,
+                        itemsExternalized: false,
                         // r29b F8 的 ids/itemsPreview 由 compact（外置时）现算，不在这里内联——
                         // 内联会让小结果越过 2048B 外置阈值，反而把 items 挤成 []。
                         ...(truncatedByCap
@@ -1190,9 +1202,13 @@ export function registerRuntimeDataLane(tools) {
                             if (probeError instanceof WireError && probeError.kind === "business" && probeError.errcode === 300004) {
                                 return {
                                     status: "refused",
-                                    blocker: "wire-business",
+                                    blocker: "schema-not-found",
                                     errcode: 300004,
-                                    message: `数据模型不存在（${args.schemaCode}）——运行面读取前模型必须已创建并发布字段；先 model.create / configure_model（存在性判据用 model.inspect 的 modelPresent）`,
+                                    schemaCode: args.schemaCode,
+                                    exists: false,
+                                    total: 0,
+                                    message: `数据模型不存在（${args.schemaCode}）——运行面读取前模型必须已创建并发布字段。`,
+                                    nextCommand: "omc call model.list --args '{}'",
                                 };
                             }
                         }
@@ -1280,6 +1296,10 @@ export function registerRuntimeDataLane(tools) {
                     })(),
                     ...(choiceFilterFields.length > 0 && Number(total ?? 0) === 0 ? { filterValueHint: choiceFilterValueHint(choiceFilterFields) } : {}),
                     totalPages,
+                    itemsCount: items.length,
+                    itemsReturned: items.length,
+                    resultTruncated: false,
+                    itemsExternalized: false,
                     page: page.page ?? requestedPage,
                     size: page.size ?? args.size ?? 20,
                     ...(pageOutOfRange ? { pageOutOfRange: true, emptyPage: true } : {}),
@@ -2238,6 +2258,8 @@ export function registerRuntimeDataLane(tools) {
                     ...readback,
                     workflowInstanceId: effectiveInstanceId,
                     objectId,
+                    // The submit response often has no workItemId; when the engine created
+                    // the next todo, its first item is the authoritative continuation id.
                     workItemId: typeof performedData.workItemId === "string" ? performedData.workItemId : null,
                     sequenceStatus,
                     submittedData: approvalDelta ? projectApprovalReadback(loadedRecord, Object.keys(formData ?? {})) : projectReadbackRecord(loadedRecord, args),
@@ -2290,6 +2312,8 @@ export function registerRuntimeDataLane(tools) {
                         }
                         if (nextWorkItems.length > 0) {
                             readback.nextWorkItems = nextWorkItems;
+                            if (readback.workItemId === null)
+                                readback.workItemId = nextWorkItems[0].workItemId;
                             const nextName = nextWorkItems[0].activityName ?? nextWorkItems[0].activityCode ?? "下一节点";
                             if (rejected) {
                                 readback.returnedTo = {

package/dist/lanes/workflow-contract.js

@@ -78,6 +78,7 @@ export const WORKFLOW_WIRE = Object.freeze({
     workItemFilter: "WorkItemSearchVO.filterWorkflowInstanceId is a NOT-equal exclusion (BizWorkitemServiceImpl.toSearchWorkItemsCriterion:400-402), so exact instance filtering is client-side",
     bizObjectResolution: "GET /api/api/runtime/workflow/getBizObjectByWfInstanceId resolves bizObjectId/schemaCode; a failed lookup leaves the identity null and never drops the todo",
     mutuallyExclusiveBinding: "同一处理器绑定多条规则时它们**全部执行、无互斥**：审批通过/驳回这类互斥结果不要用两条各自 FIXED 赋值都绑 end（bench22 病灶）——通过绑 end（endEventHandler）或规则 Available，驳回绑 cancel（cancelEventHandler）或规则 Cancel，或用一条多分支图（生产 case_info_update 只在 endEventHandler 绑一条 updateData 多分支图）；workflow.bindRule 回读在 bizActions.length>1 时给 advisory",
+    participantRoleValidation: "写前参与人校验：PARTICIPANT 的 FindUserByRole(<org>,\"<roleCode>\",\"<order>\") 会与 org.role.list 的真实角色 code 比对；缺失即拒绝 workflow-participant-role-not-found，并给 activityCode/activityName/roleCode、最多 5 个 candidates 与 nextCommand。org.role.list 读取失败时 fail-open，不阻断写入。{Originator} 是发起人关键字，不按角色校验；所有 PARTICIPANT 都是 {Originator} 时给 approval-by-originator warning。",
     userSearch: "POST /api/api/organization/user/search，@RequestBody {wd (关键字，必填), page, size, filterType?} → PageVO<UserVO>{totalElements,totalPages,content[{id,name,username,userId,departmentId,corpId,status}]}（UserController.search:337-341；缺 wd 报 10005 关键字不能为空）。用于把姓名解析成真实用户，构造参与者对象 type 3=用户（type 2=角色）",
 });
 /** Workflow template object (workflow/update|publish raw body). */
@@ -117,6 +118,7 @@ export const WORKFLOW_LANE_CONTRACT = Object.freeze({
         bizObjectResolution: WORKFLOW_WIRE.bizObjectResolution,
         mutuallyExclusiveBinding: WORKFLOW_WIRE.mutuallyExclusiveBinding,
         userSearch: WORKFLOW_WIRE.userSearch,
+        participantRoleValidation: WORKFLOW_WIRE.participantRoleValidation,
     }),
     wireBindings: Object.freeze({
         templateShape: Object.freeze([behaviorBinding("test/ticket-112-workflow-template-merge.test.ts#workflow.update merges onto the draft", assertWorkflowContract)]),
@@ -135,6 +137,7 @@ export const WORKFLOW_LANE_CONTRACT = Object.freeze({
         bizObjectResolution: Object.freeze([emitterBinding("workflow-support.resolveBizObjectIdByInstance", assertWorkflowContract)]),
         mutuallyExclusiveBinding: Object.freeze([behaviorBinding("test/issue-14-workflow-bind-rule.test.ts#workflow.bindRule merges endEventHandler", assertWorkflowContract)]),
         userSearch: Object.freeze([behaviorBinding("test/round4-org-user-search.test.ts#org.user.search resolves a user by name into participant fields", assertWorkflowContract)]),
+        participantRoleValidation: Object.freeze([behaviorBinding("test/workflow-participant-role.test.ts#workflow.update refuses an unknown FindUserByRole role before the wire", assertWorkflowContract)]),
     }),
     evidence: Object.freeze([
         ".scratch/omc-approval-workflow/acceptance/s29-probe-20260910012330184.md",
@@ -160,7 +163,7 @@ export const WORKFLOW_LANE_CONTRACT = Object.freeze({
         }),
         "workflow.update": Object.freeze({
             scope: WORKFLOW_SCOPE,
-            description: "写入工作流模板草稿（`/api/api/workflow/update`，raw template JSON body）。cli 以当前草稿为基线做 merge，未列出的既有节点保留：**模板缺 START 或 END 时自动按增量 merge（部分模板），给全 START..END 才整模板替换**；也可显式 `merge:true/false`。**连线三种写法选一**：`routes`（recipe 写法）/ `edges`（同义）/ `rules`（平台 DTO 字段名，`get_draft` 读回原样）——同传两种会被拒（`workflow-routes-ambiguous`）；merge 是并集（草稿边 + 你的边），**绝不删边**，若结果会比草稿少边则拒绝（`workflow-merge-would-drop-routes`，回 routesBefore/After + 缺失连线），dry-run 也会给出 `routesBefore/routesAfter/routesAdded/routesDropped`。**节点形状**：新增节点必须给 `type`/`activityType`（可选 START/PARTICIPANT/END…），`activityCode` 命中草稿既有节点时可省（类型/名称继承草稿）；**字段权限只发改动行**——`propertyPermissions` 是载荷体积的主要来源（整模板单次常到 1.0–1.4MB，超过 `--args-file` 上限 `CLI_ARGS_MAX_BYTES`=1MB 会被拒），权限编辑只需 `activities:[{activityCode, propertyPermissions:[{propertyCode,…}]}]`。**节点字段权限也走这里**：不必读 `get_draft --full`——直接发 `activities:[{activityCode, propertyPermissions:[{propertyCode, visible, editable, required, summary, subPropertyPermissions}]}]`（**type 可省**：activityCode 命中草稿节点时类型/名称继承草稿，不会铸 `_2` 新码；**改名=同 code 原地生效**——工具把新名写入 `name_i18n`（zh/zh_TW/en），activityName 平台侧保持首建值，读回以 `renamedInPlace.displayName` 为准；只有**类型变更**才铸新码并弃旧码），工具按 propertyCode 合并到草稿对应节点（未列的字段权限保留；`merge:true` 也可同用）——没有单独的权限工具，别把「找不到入口」当成不支持（dogfood 实测该误判会假阻塞）。`summary` **无需配置**：工具合并时自动补 `summary:true`（平台怪癖——缺省进不了运行时 `activitySummaries`、`form/load` 读不到你的 `editable:false`；显式传 `false` 才保留）；子表字段用 `subPropertyPermissions`（同样自动补）。**子表属性不可设 `required:true`**（接口形状接受但设计器节点字段配置不支持，存入后无法渲染——工具直接拒 `workflow-child-table-not-required`）；子表整行只配 visible/editable，字段级必填配到子表内部字段所在节点。**新增节点用语义 code**（如 `approval_finance`），不要模仿草稿的 `ActivityN` 再加 `_1/_2` 后缀。**设计器默认自动补齐**（调用方显式传值优先）：填写节点（{Originator}）自动生成子表操作按钮 `buttonPermission.childTableBtns`（每个子表 ADD/DELETE/IMPORT/EXPORT 启用、BATCH_UPDATE 禁用——API 建的流程缺这份模板，设计器里子表按钮会全部不勾）；`permittedAction` 归一为设计器默认（填写节点 showReject:false 不能驳回自己，审批节点 rejectToStart:true 驳回回发起节点）。用 `npm run test:live-permission`（非管理员参与者）验收，管理员会被后端强制 `e:true` 掩盖。",
+            description: "写入工作流模板草稿（`/api/api/workflow/update`，raw template JSON body）。cli 以当前草稿为基线做 merge，未列出的既有节点保留：**模板缺 START 或 END 时自动按增量 merge（部分模板），给全 START..END 才整模板替换**；也可显式 `merge:true/false`。**连线三种写法选一**：`routes`（recipe 写法）/ `edges`（同义）/ `rules`（平台 DTO 字段名，`get_draft` 读回原样）——同传两种会被拒（`workflow-routes-ambiguous`）；merge 是并集（草稿边 + 你的边），**绝不删边**，若结果会比草稿少边则拒绝（`workflow-merge-would-drop-routes`，回 routesBefore/After + 缺失连线），dry-run 也会给出 `routesBefore/routesAfter/routesAdded/routesDropped`。**节点形状**：新增节点必须给 `type`/`activityType`（可选 START/PARTICIPANT/END…），`activityCode` 命中草稿既有节点时可省（类型/名称继承草稿）；**字段权限只发改动行**——`propertyPermissions` 是载荷体积的主要来源（整模板单次常到 1.0–1.4MB，超过 `--args-file` 上限 `CLI_ARGS_MAX_BYTES`=1MB 会被拒）。**节点字段权限也走这里**：不必读 `get_draft --full`——直接发 `activities:[{activityCode, propertyPermissions:[{propertyCode, visible, editable, required, summary, subPropertyPermissions}]}]`（**type 可省**：activityCode 命中草稿节点时类型/名称继承草稿，不会铸 `_2` 新码；**改名=同 code 原地生效**——工具把新名写入 `name_i18n`（zh/zh_TW/en），activityName 平台侧保持首建值，读回以 `renamedInPlace.displayName` 为准；只有**类型变更**才铸新码并弃旧码），工具按 propertyCode 合并到草稿对应节点（未列的字段权限保留；`merge:true` 也可同用）——没有单独的权限工具，别把「找不到入口」当成不支持（dogfood 实测该误判会假阻塞）。`summary` **无需配置**：工具合并时自动补 `summary:true`（平台怪癖——缺省进不了运行时 `activitySummaries`、`form/load` 读不到你的 `editable:false`；显式传 `false` 才保留）；子表字段用 `subPropertyPermissions`（同样自动补）。**参与人写前校验**：`FindUserByRole(…,\"<roleCode>\",…)` 与 org.role.list 比对，未知角色拒 `workflow-participant-role-not-found`（带候选）；全 `{Originator}` 给 `approval-by-originator` warning。**子表属性不可设 `required:true`**（接口形状接受但设计器节点字段配置不支持，存入后无法渲染——工具直接拒 `workflow-child-table-not-required`）；子表整行只配 visible/editable，字段级必填配到子表内部字段所在节点。**新增节点用语义 code**（如 `approval_finance`），不要模仿草稿的 `ActivityN` 再加 `_1/_2` 后缀。**设计器默认自动补齐**（调用方显式传值优先）：填写节点（{Originator}）自动生成子表操作按钮 `buttonPermission.childTableBtns`（每个子表 ADD/DELETE/IMPORT/EXPORT 启用、BATCH_UPDATE 禁用——API 建的流程缺这份模板，设计器里子表按钮会全部不勾）；`permittedAction` 归一为设计器默认（填写节点 showReject:false 不能驳回自己，审批节点 rejectToStart:true 驳回回发起节点）。",
         }),
         "workflow.publish": Object.freeze({
             scope: WORKFLOW_SCOPE,
@@ -208,11 +211,11 @@ export const WORKFLOW_LANE_CONTRACT = Object.freeze({
         }),
         "workitem.list": Object.freeze({
             scope: "runtime workflow work-item query",
-            description: "查询当前登录人的待办（`GET /api/api/runtime/workflow/search_workitems`）。WorkItemSearchVO 经 @ModelAttribute 传参，服务端以登录态注入 userId，故无需传处理人——结果天然是「我的待办」。返回每项 workItemId(id) + workflowInstanceId(instanceId) + activityName + state；并尽力经 `GET /api/api/runtime/workflow/getBizObjectByWfInstanceId` 解析 bizObjectId/schemaCode 供 data.submit 审批。`workflowInstanceId` 为客户端精确过滤（服务端 WorkItemSearchVO.filterWorkflowInstanceId 实为 notEqualsTo 排除，不能用于命中实例）；带该过滤时 total 为过滤后的条数，原服务端总数在 unfilteredTotal。**想知道「流程停在哪」，用 `workflow.instanceActivity`，不要靠反复 workitem.list**——待办查询只返回在办项，实例停住时永远是空数组。",
+            description: "查询当前登录人的待办（`GET /api/api/runtime/workflow/search_workitems`）。WorkItemSearchVO 经 @ModelAttribute 传参，服务端以登录态注入 userId，故无需传处理人——结果天然是「我的待办」。返回每项完整键集：`workItemId, workflowInstanceId, workflowCode, activityCode, activityName, state, sequenceNo, originator, originatorName, participant, participantName, bizObjectId, schemaCode`；外置大结果另带 `itemsCount, ids, itemsPreview, truncated, truncatedKeys, omittedKeys, detailFile/detailSha256`，其中 itemsPreview 为前 3 个 `{id}` 引用。并尽力经 `GET /api/api/runtime/workflow/getBizObjectByWfInstanceId` 解析 bizObjectId/schemaCode 供 data.submit 审批。`workflowInstanceId` 为客户端精确过滤（服务端 WorkItemSearchVO.filterWorkflowInstanceId 实为 notEqualsTo 排除，不能用于命中实例）；带该过滤时 total 为过滤后的条数，原服务端总数在 unfilteredTotal。**想知道「流程停在哪」，用 `workflow.instanceActivity`，不要靠反复 workitem.list**——待办查询只返回在办项，实例停住时永远是空数组。",
         }),
         "workflow.instanceActivity": Object.freeze({
             scope: "runtime workflow instance node-state diagnosis",
-            description: "按实例查全部节点状态（`GET /api/api/runtime/workflow/list_workflow_instance_activity`，WorkflowMaintenanceAssembler.listActivateActivity）。返回模板里每个活动节点的 activityCode/activityName/activityType + status（1=当前激活，0=已完成或未到达）+ 解析出的 participants（含姓名/id）。用于「data.submit 回 PROCESSING 但没有下一待办」的自诊断：例子 `omc call workflow.instanceActivity --args '{\"workflowInstanceId\":\"<id>\"}'`。当没有任何节点 status=1 时，readback 的 diagnosis.code=no-active-activity 并列出排查顺序（参与人为空的审批节点 → 参与人写法 → 容器日志 GetParticipantInfo error）。审批推进正常时该工具不需要——data.submit 的 readback.nextSubmit 已给出下一级参数。",
+            description: "按实例查全部节点状态（`activities[].status` 数字枚举：`1=当前激活/持有待办`、`0=已完成或尚未到达`，别与实例级 `instanceStatus:\"PROCESSING\"` 混用——后者只表示流程仍在运行）。返回每个节点 `{activityCode,activityName,activityType,status,participantCount,participants:[{name,id}],sheetTrigger?}`（`GET /api/api/runtime/workflow/list_workflow_instance_activity`，WorkflowMaintenanceAssembler.listActivateActivity）。用于「data.submit 回 PROCESSING 但没有下一待办」的自诊断：例子 `omc call workflow.instanceActivity --args '{\"workflowInstanceId\":\"<id>\"}'`。当没有任何节点 status=1 时，readback 的 diagnosis.code=no-active-activity 并列出排查顺序（参与人为空的审批节点 → 参与人写法 → 容器日志 GetParticipantInfo error）。审批推进正常时该工具不需要——data.submit 的 readback.nextSubmit 已给出下一级参数。",
         }),
     }),
 });
@@ -241,6 +244,7 @@ export function assertWorkflowContract() {
     assertDescriptionCarries(WORKFLOW_LANE_CONTRACT, "org.role.list", ["organization/role/list", "type", "Originator"]);
     assertDescriptionCarries(WORKFLOW_LANE_CONTRACT, "org.department.list", ["organization/department/tree", "parentId"]);
     assertDescriptionCarries(WORKFLOW_LANE_CONTRACT, "org.user.search", ["organization/user/search", "wd", "type 3"]);
+    assertDescriptionCarries(WORKFLOW_LANE_CONTRACT, "workflow.update", ["FindUserByRole", "workflow-participant-role-not-found", "approval-by-originator"]);
     for (const [key, field] of Object.entries(WORKFLOW_EVENT_HANDLER_FIELDS)) {
         if (!WORKFLOW_WIRE.bindRuleChain.includes(key))
             throw new Error(`workflow contract bind-rule chain must mention the ${key} handler key`);