@stalfh233/omc-cli 0.0.0-stage → 0.4.0

package/dist/intent/capabilities/workflow.js

@@ -0,0 +1,458 @@
+import { ENDPOINTS } from "../../endpoints.js";
+import { wireCall, WireError } from "../../wire.js";
+import { isScalarString, pushError } from "../validation.js";
+import { toPlain } from "../yaml.js";
+import { PLATFORM_TRIGGER_RULE_CODES } from "../../lanes/rule-graph.js";
+const WORKFLOW_KEYS = new Set(["code", "name", "publish", "template", "bindRules"]);
+const BINDING_KEYS = new Set(["handler", "ruleCodes"]);
+/** 8.6.26 ActivityType enum (mirrors lanes/workflow.ts) — an illegal type is refused at apply, so catch it offline. */
+const WORKFLOW_ACTIVITY_TYPES = new Set(["START", "END", "CONNECTION", "PARTICIPANT", "SUB_INSTANCE", "CIRCULATE", "SYSTEM_ACTIVITY", "AGENT_ACTIVITY"]);
+/**
+ * Offline shape check of a declared workflow template.
+ *
+ * `workflow.update` reads activities ONLY from `template.activities`, but reads
+ * the topology from `routes`/`rules`/`edges`. A template that declares routes
+ * but no activities (bench42: the agent wrote `{nodes, edges}` — a guessed
+ * shape) therefore passes `intent validate`, and only fails at apply with
+ * `workflow.update: rules[0] references an unknown activity` (all activity codes
+ * resolve to the empty set) — aborting the whole `intent.apply` run after dozens
+ * of successful steps. Mirror the lane's accepted spellings here so the mistake
+ * is caught offline with an actionable message.
+ */
+function validateWorkflowTemplate(template, base, ctx) {
+    const rawActivities = template.activities;
+    const activityList = Array.isArray(rawActivities)
+        ? rawActivities
+        : rawActivities && typeof rawActivities === "object"
+            ? Object.keys(rawActivities).sort((a, b) => Number(a) - Number(b)).map((key) => rawActivities[key])
+            : undefined;
+    if (activityList === undefined) {
+        const hint = template.nodes !== undefined || template.edges !== undefined ? "（检测到 nodes/edges——本 DSL 用 activities/routes）" : "";
+        pushError(ctx, "intent-workflow-activities-required", `workflow.template 必须声明 activities（非空活动列表）${hint}；workflow.update 只从 activities 读节点，路由 preNode/postNode 必须指向其中的活动 code`, `${base}.activities`, "value");
+        return;
+    }
+    if (activityList.length === 0) {
+        pushError(ctx, "intent-workflow-activities-empty", "workflow.template.activities 不能为空", `${base}.activities`, "value");
+        return;
+    }
+    const codes = new Set();
+    activityList.forEach((activity, index) => {
+        if (!activity || typeof activity !== "object") {
+            pushError(ctx, "intent-workflow-activity-invalid", `activities[${index}] 必须是映射（{id|activityCode, type|activityType}）`, `${base}.activities[${index}]`, "value");
+            return;
+        }
+        const row = activity;
+        const code = row.activityCode ?? row.id;
+        if (typeof code !== "string" || code.trim().length === 0)
+            pushError(ctx, "intent-workflow-activity-code-invalid", `activities[${index}] 缺 code（id 或 activityCode）`, `${base}.activities[${index}]`, "value");
+        else
+            codes.add(code.trim());
+        const type = row.activityType ?? row.type;
+        if (typeof type !== "string" || !WORKFLOW_ACTIVITY_TYPES.has(type))
+            pushError(ctx, "intent-workflow-activity-type-invalid", `activities[${index}] 的 type 必须是 8.6.26 ActivityType（${[...WORKFLOW_ACTIVITY_TYPES].join("/")}；START/END/PARTICIPANT），得到 ${JSON.stringify(type)}`, `${base}.activities[${index}].type`, "value");
+    });
+    const rawRoutes = template.routes ?? template.rules ?? template.edges;
+    if (rawRoutes === undefined)
+        return;
+    if (!Array.isArray(rawRoutes)) {
+        pushError(ctx, "intent-workflow-routes-invalid", "workflow.template.routes 必须是列表", `${base}.routes`, "value");
+        return;
+    }
+    rawRoutes.forEach((route, index) => {
+        if (!route || typeof route !== "object") {
+            pushError(ctx, "intent-workflow-route-invalid", `routes[${index}] 必须是映射（{preNode, postNode}）`, `${base}.routes[${index}]`, "value");
+            return;
+        }
+        const row = route;
+        const pre = row.preActivityCode ?? row.preNode ?? row.pre;
+        const post = row.postActivityCode ?? row.postNode ?? row.post;
+        if (typeof pre !== "string" || !codes.has(pre))
+            pushError(ctx, "intent-workflow-route-activity-unknown", `routes[${index}].preNode "${String(pre ?? "")}" 不是任何已声明活动 code（已知：${[...codes].join("/")}）`, `${base}.routes[${index}]`, "value");
+        if (typeof post !== "string" || !codes.has(post))
+            pushError(ctx, "intent-workflow-route-activity-unknown", `routes[${index}].postNode "${String(post ?? "")}" 不是任何已声明活动 code（已知：${[...codes].join("/")}）`, `${base}.routes[${index}]`, "value");
+    });
+}
+/** Event-handler key -> draft field (mirrors workflow-contract, kept local to avoid a lane import cycle). */
+const HANDLER_FIELDS = Object.freeze({ start: "startEventHandler", cancel: "cancelEventHandler", activate: "activateEventHandler", end: "endEventHandler" });
+const HANDLER_NAMES = Object.keys(HANDLER_FIELDS);
+/**
+ * The rule codes bound per handler in a workflow draft. Only a handler carrying
+ * `bizActionType:"BIZ_RULE"` counts: the same code under another action type is
+ * NOT a rule binding, and must not make the compiler skip the bind.
+ */
+function bindingsOf(template) {
+    const result = {};
+    if (!template)
+        return result;
+    for (const [handler, field] of Object.entries(HANDLER_FIELDS)) {
+        const face = template[field];
+        const isRuleHandler = face?.bizActionType === "BIZ_RULE";
+        result[handler] = isRuleHandler && Array.isArray(face?.bizActions) ? face.bizActions.filter((value) => typeof value === "string") : [];
+    }
+    return result;
+}
+function absent(error) {
+    return error instanceof WireError && error.kind === "business" && error.errcode === 401001;
+}
+async function getOrNull(session, path, workflowCode) {
+    try {
+        return ((await wireCall(session, { path, query: { workflowCode } })).data ?? null);
+    }
+    catch (error) {
+        if (absent(error))
+            return null;
+        throw error;
+    }
+}
+function publishedOf(template) {
+    return template !== null && (template.templateType === "PUBLISH" || template.published === true);
+}
+/**
+ * The platform returns `propertyPermissions` (and nested `subPropertyPermissions`)
+ * in a NON-deterministic order — two reads of an unchanged workflow differ only
+ * by array order. The baseline fingerprint hashes the raw template, so an
+ * unordered permission array made every replan hash differently and the apply
+ * drift gate answered `intent-baseline-drifted` forever (dogfood bench50: three
+ * refused applies on an unchanged environment). Permissions are keyed by
+ * `propertyCode`, so order carries no semantics — sort them before storing.
+ */
+function sortPermissions(value) {
+    if (!Array.isArray(value))
+        return value;
+    return value
+        .map((entry) => {
+        if (!entry || typeof entry !== "object")
+            return entry;
+        const row = entry;
+        return row.subPropertyPermissions !== undefined ? { ...row, subPropertyPermissions: sortPermissions(row.subPropertyPermissions) } : row;
+    })
+        .sort((a, b) => String(a?.propertyCode ?? "").localeCompare(String(b?.propertyCode ?? "")));
+}
+/**
+ * Deep-walk the template and canonicalize EVERY `propertyPermissions` /
+ * `subPropertyPermissions` array by `propertyCode` — the platform emits them
+ * unordered on `activities[]`, `originateActivity`, and any other activity
+ * shape, and each one flips the baseline fingerprint independently.
+ */
+function canonicalizePermissions(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalizePermissions);
+    if (value === null || typeof value !== "object")
+        return value;
+    const record = value;
+    const canonical = {};
+    for (const [key, entry] of Object.entries(record)) {
+        if (key === "propertyPermissions" || key === "subPropertyPermissions")
+            canonical[key] = sortPermissions(entry);
+        else
+            canonical[key] = canonicalizePermissions(entry);
+    }
+    return canonical;
+}
+function canonicalizeWorkflowTemplate(template) {
+    if (!template)
+        return undefined;
+    return canonicalizePermissions(template);
+}
+/**
+ * Canonical participant form for equivalence. The intent accepts several
+ * spellings — the keyword string `{Originator}`, a structured object
+ * `{type: "Originator", name: …}`, a role object array, or a FindUserByRole
+ * function string. The platform normalizes a bare originator to the keyword
+ * `{Originator}`, so an intent that declares the object form would otherwise
+ * report perpetual drift (bench57). Normalize both sides the same way: a lone
+ * originator (keyword, or object whose only meaningful key is type=Originator)
+ * becomes the keyword; everything else is compared as canonical key-sorted JSON.
+ */
+function canonicalParticipant(participant) {
+    if (typeof participant === "string") {
+        const trimmed = participant.trim();
+        if (/^originator$/i.test(trimmed))
+            return "{Originator}";
+        return trimmed;
+    }
+    if (participant && typeof participant === "object" && !Array.isArray(participant)) {
+        const record = participant;
+        const keys = Object.keys(record);
+        const typeValue = record.type ?? record.participantType;
+        if (keys.every((key) => key === "type" || key === "participantType" || key === "name" || key === "i18nMessage" || key === "label") && typeof typeValue === "string" && /^originator$/i.test(typeValue))
+            return "{Originator}";
+        const sorted = Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b)));
+        return JSON.stringify(sorted);
+    }
+    if (Array.isArray(participant))
+        return JSON.stringify(participant);
+    return participant;
+}
+function workflowProjection(template) {
+    if (!template)
+        return { activities: [], rules: [] };
+    const activities = Array.isArray(template.activities) ? template.activities.map((activity) => {
+        const row = activity;
+        return { code: String(row.activityCode ?? row.id ?? ""), type: String(row.activityType ?? row.type ?? ""), ...(row.participant !== undefined ? { participant: canonicalParticipant(row.participant) } : {}) };
+    }) : [];
+    const rawRules = Array.isArray(template.rules) ? template.rules : Array.isArray(template.routes) ? template.routes : [];
+    const rules = rawRules.map((rule) => {
+        const row = rule;
+        return {
+            pre: String(row.preActivityCode ?? row.preNode ?? row.pre ?? ""),
+            post: String(row.postActivityCode ?? row.postNode ?? row.post ?? ""),
+            ...(Array.isArray(row.points) ? { points: row.points } : {}),
+            // Branch condition (round7): keep it in the projection so readback
+            // equivalence can see a changed/absent ruleConditionGroup, not just the
+            // endpoints. An edge with the same pre->post but a different condition is
+            // a different route.
+            ...(row.ruleConditionGroup !== undefined ? { ruleConditionGroup: row.ruleConditionGroup } : {}),
+            ...(row.childMatchType !== undefined ? { childMatchType: row.childMatchType } : {}),
+            ...(row.formula !== undefined ? { formula: row.formula } : {}),
+            ...(row.utilizeElse !== undefined ? { utilizeElse: row.utilizeElse } : {}),
+            ...(row.alternativeFlag !== undefined ? { alternativeFlag: row.alternativeFlag } : {}),
+            ...(row.text !== undefined ? { text: row.text } : {}),
+        };
+    });
+    return { activities, rules };
+}
+/**
+ * The platform cannot rename an existing activity in place: `workflow.update`
+ * mints a fresh code (`<code>_2`, `<code>_3`, …) when a caller node's type/name
+ * differs from the stored draft (see reconcileCallerActivityCodes). An intent
+ * that declares `dept_approve` therefore converges to a live `dept_approve_2`
+ * after a re-update, and a strict code compare reports perpetual
+ * `workflow-template-mismatch` (bench57). Match on the base code so a
+ * platform-minted suffix does not read as drift; type/participant/condition
+ * checks still gate real differences.
+ */
+function stripRenamedSuffix(code) {
+    return String(code ?? "").replace(/_\d+$/, "");
+}
+function findActivity(byCode, byBase, code) {
+    return byCode.get(String(code)) ?? byBase.get(stripRenamedSuffix(code));
+}
+function workflowMatches(live, desired) {
+    if (!desired)
+        return true;
+    const actual = workflowProjection(live);
+    const expected = workflowProjection(desired);
+    const actualActivities = new Map(actual.activities.map((row) => [String(row.code), row]));
+    const actualByBase = new Map(actual.activities.map((row) => [stripRenamedSuffix(row.code), row]));
+    for (const row of expected.activities) {
+        const current = findActivity(actualActivities, actualByBase, row.code);
+        if (!current || current.type !== row.type || (row.participant !== undefined && current.participant !== row.participant))
+            return false;
+    }
+    const edgeKey = (pre, post) => `${stripRenamedSuffix(pre)}->${stripRenamedSuffix(post)}`;
+    const actualRules = new Map(actual.rules.map((row) => [edgeKey(row.pre, row.post), row]));
+    for (const row of expected.rules) {
+        const current = actualRules.get(edgeKey(row.pre, row.post));
+        if (!current)
+            return false;
+        if (row.points !== undefined && JSON.stringify(current.points) !== JSON.stringify(row.points))
+            return false;
+        // A declared branch condition must be present and equivalent. Only keys the
+        // desired template declares are compared, so the platform's own defaults on
+        // the live row (popupType/utilizeElse) do not read as drift.
+        for (const key of ["ruleConditionGroup", "childMatchType", "formula", "utilizeElse", "alternativeFlag", "text"])
+            if (row[key] !== undefined && JSON.stringify(current[key] ?? null) !== JSON.stringify(row[key]))
+                return false;
+    }
+    return true;
+}
+/**
+ * Actionable diff for a `workflow-template-mismatch`: which expected activities
+ * are missing / have a different type or participant, and which expected edges
+ * are missing. The platform adds its own nodes (e.g. the 填写申请单 originate
+ * activity), so ADDITIONS are not reported — only what the declared template
+ * expects and does not find. bench53 spent 3 diagnosis rounds on a bare
+ * "活动/连线不等价".
+ */
+function workflowMismatchDetail(live, desired) {
+    if (!desired)
+        return "";
+    const actual = workflowProjection(live);
+    const expected = workflowProjection(desired);
+    const actualActivities = new Map(actual.activities.map((row) => [String(row.code), row]));
+    const actualByBase = new Map(actual.activities.map((row) => [stripRenamedSuffix(row.code), row]));
+    const issues = [];
+    for (const row of expected.activities) {
+        const current = findActivity(actualActivities, actualByBase, row.code);
+        if (!current)
+            issues.push(`缺活动 ${row.code}(${row.type})`);
+        else if (current.type !== row.type)
+            issues.push(`活动 ${row.code} 类型 ${current.type}≠期望 ${row.type}`);
+        else if (row.participant !== undefined && current.participant !== row.participant)
+            issues.push(`活动 ${row.code} 参与者 ${JSON.stringify(current.participant)}≠期望 ${JSON.stringify(row.participant)}`);
+    }
+    const edgeKey = (pre, post) => `${stripRenamedSuffix(pre)}->${stripRenamedSuffix(post)}`;
+    const actualRules = new Map(actual.rules.map((row) => [edgeKey(row.pre, row.post), row]));
+    for (const row of expected.rules) {
+        const current = actualRules.get(edgeKey(row.pre, row.post));
+        if (!current)
+            issues.push(`缺连线 ${row.pre}→${row.post}`);
+        else {
+            if (row.points !== undefined && JSON.stringify(current.points) !== JSON.stringify(row.points))
+                issues.push(`连线 ${row.pre}→${row.post} 坐标不同`);
+            for (const key of ["ruleConditionGroup", "childMatchType", "formula", "utilizeElse", "alternativeFlag", "text"])
+                if (row[key] !== undefined && JSON.stringify(current[key] ?? null) !== JSON.stringify(row[key]))
+                    issues.push(`连线 ${row.pre}→${row.post} 的 ${key} 不同`);
+        }
+    }
+    return issues.length > 0 ? issues.slice(0, 8).join("；") : "平台已补全/规范化，无声明面差异";
+}
+/** Parse the optional `bindRules` list into normalized bindings. */
+function readBindings(seqNode, base, ctx) {
+    if (seqNode === undefined || (seqNode.kind === "scalar" && seqNode.value === null))
+        return [];
+    if (seqNode.kind !== "seq") {
+        pushError(ctx, "intent-workflow-bindrules-invalid", "workflow.bindRules 必须是列表", base, "value");
+        return [];
+    }
+    const bindings = [];
+    seqNode.items.forEach((item, index) => {
+        const itemBase = `${base}[${index}]`;
+        if (item.kind !== "map") {
+            pushError(ctx, "intent-workflow-binding-not-a-map", "bindRules 项必须是映射（只接受 handler / ruleCodes）", itemBase, "value");
+            return;
+        }
+        for (const entry of item.entries)
+            if (!BINDING_KEYS.has(entry.key))
+                pushError(ctx, "intent-key-unknown", `bindRules 项不支持键 "${entry.key}"（只接受 handler / ruleCodes）`, `${itemBase}.${entry.key}`);
+        const handlerNode = item.entries.find((entry) => entry.key === "handler")?.value;
+        const codesNode = item.entries.find((entry) => entry.key === "ruleCodes")?.value;
+        const handler = isScalarString(handlerNode) ? handlerNode.value.trim() : "";
+        if (!HANDLER_NAMES.includes(handler))
+            pushError(ctx, "intent-workflow-binding-handler-invalid", `bindRules[].handler 必须是 ${HANDLER_NAMES.join(" / ")}（得到 "${handler}"）`, `${itemBase}.handler`, "value");
+        const validCodes = codesNode?.kind === "seq" && codesNode.items.length > 0 && codesNode.items.every((entry) => isScalarString(entry) && entry.value.trim().length > 0);
+        if (!validCodes)
+            pushError(ctx, "intent-workflow-binding-codes-invalid", "bindRules[].ruleCodes 必须是非空字符串列表", `${itemBase}.ruleCodes`, "value");
+        if (HANDLER_NAMES.includes(handler) && validCodes)
+            bindings.push({ handler: handler, ruleCodes: codesNode.items.map((entry) => entry.value.trim()) });
+    });
+    return bindings;
+}
+export const workflowCapability = {
+    id: "workflow",
+    title: "流程模板",
+    requires: ["model"],
+    operations: ["create", "update", "publish"],
+    validate(node, draft, ctx) {
+        const workflowNode = node.entries.find((entry) => entry.key === "workflow")?.value;
+        if (workflowNode === undefined || (workflowNode.kind === "scalar" && workflowNode.value === null))
+            return;
+        if (workflowNode.kind !== "map") {
+            pushError(ctx, "intent-workflow-not-a-map", "workflow 必须是映射", `${ctx.base}.workflow`, "value");
+            return;
+        }
+        for (const entry of workflowNode.entries)
+            if (!WORKFLOW_KEYS.has(entry.key))
+                pushError(ctx, "intent-key-unknown", `workflow 不支持键 "${entry.key}"（只接受 code / name / publish / template / bindRules）`, `${ctx.base}.workflow.${entry.key}`);
+        const codeNode = workflowNode.entries.find((entry) => entry.key === "code")?.value;
+        const nameNode = workflowNode.entries.find((entry) => entry.key === "name")?.value;
+        const publishNode = workflowNode.entries.find((entry) => entry.key === "publish")?.value;
+        const templateNode = workflowNode.entries.find((entry) => entry.key === "template")?.value;
+        const bindRulesNode = workflowNode.entries.find((entry) => entry.key === "bindRules")?.value;
+        if (!isScalarString(codeNode) || codeNode.value.trim().length === 0)
+            pushError(ctx, "intent-workflow-code-invalid", "workflow.code 必须是非空字符串", `${ctx.base}.workflow.code`, "value");
+        if (!isScalarString(nameNode) || nameNode.value.trim().length === 0)
+            pushError(ctx, "intent-workflow-name-invalid", "workflow.name 必须是非空字符串", `${ctx.base}.workflow.name`, "value");
+        if (publishNode === undefined || publishNode.kind !== "scalar" || typeof publishNode.value !== "boolean")
+            pushError(ctx, "intent-workflow-publish-invalid", "workflow.publish 必须是布尔", `${ctx.base}.workflow.publish`, "value");
+        if (templateNode !== undefined && templateNode.kind !== "map")
+            pushError(ctx, "intent-workflow-template-invalid", "workflow.template 必须是映射", `${ctx.base}.workflow.template`, "value");
+        if (publishNode?.kind === "scalar" && publishNode.value === true && templateNode === undefined)
+            pushError(ctx, "intent-workflow-template-required", "workflow.publish:true 必须同时声明 template（流程发布需要完整模板）", `${ctx.base}.workflow.template`, "value");
+        const bindRules = readBindings(bindRulesNode, `${ctx.base}.workflow.bindRules`, ctx);
+        // Workflow event handlers can only bind CUSTOM rules — the platform's rule
+        // picker does not offer preset trigger rows (Create/Update/…, which already
+        // run on the data event). Catch it offline so apply never tries (bench59).
+        for (const binding of bindRules)
+            for (const boundCode of binding.ruleCodes)
+                if (PLATFORM_TRIGGER_RULE_CODES.has(boundCode))
+                    pushError(ctx, "intent-workflow-binding-preset-rule", `workflow.bindRules 绑定了平台预置触发规则 "${boundCode}"——流程事件规则选择器只提供自定义规则。要「流程事件触发某逻辑」，请新建自定义规则（自定义 code）承载动作节点再绑定；或把动作直接追加到预置 Create/Update 规则。`, `${ctx.base}.workflow.bindRules`, "value");
+        if (templateNode?.kind === "map")
+            validateWorkflowTemplate(toPlain(templateNode), `${ctx.base}.workflow.template`, ctx);
+        if (isScalarString(codeNode) && isScalarString(nameNode) && publishNode?.kind === "scalar" && typeof publishNode.value === "boolean") {
+            draft.workflow = {
+                code: codeNode.value.trim(),
+                name: nameNode.value.trim(),
+                publish: publishNode.value,
+                ...(templateNode?.kind === "map" ? { template: toPlain(templateNode) } : {}),
+                ...(bindRules.length > 0 ? { bindRules } : {}),
+            };
+        }
+    },
+    async read(session, intent, draft) {
+        const workflow = intent.workflow;
+        if (!workflow)
+            return;
+        const draftTemplate = await getOrNull(session, ENDPOINTS.workflowGetDraft, workflow.code);
+        const publishedTemplate = await getOrNull(session, ENDPOINTS.workflowGetPublished, workflow.code);
+        const published = publishedOf(publishedTemplate);
+        draft.workflow = {
+            present: draftTemplate !== null || publishedTemplate !== null,
+            published,
+            template: canonicalizeWorkflowTemplate((intent.workflow?.publish ? publishedTemplate ?? draftTemplate : draftTemplate ?? publishedTemplate) ?? undefined),
+            // Bindings are read from the DRAFT: workflow.bindRule merges into the draft
+            // then publishes, so the draft is the authoritative binding face.
+            bindings: bindingsOf(draftTemplate),
+        };
+    },
+    plan(intent, baseline, emit) {
+        const workflow = intent.workflow;
+        if (!workflow)
+            return;
+        const current = baseline.workflow;
+        const resource = `workflow:${intent.code}.${workflow.code}`;
+        const missing = current?.present !== true;
+        const templateChanged = workflow.template !== undefined && !workflowMatches(current?.template, workflow.template);
+        if (missing) {
+            emit.change("workflow.create", { schemaCode: intent.code, name: workflow.name, code: workflow.code }, resource, "workflow-absent");
+            if (workflow.template !== undefined)
+                emit.change("workflow.update", { schemaCode: intent.code, code: workflow.code, template: workflow.template }, resource, "workflow-template-declared");
+        }
+        else if (templateChanged) {
+            emit.change("workflow.update", { schemaCode: intent.code, code: workflow.code, template: workflow.template }, resource, "workflow-template-drift");
+        }
+        else {
+            emit.skip(resource, "workflow-present");
+        }
+        if (workflow.publish && (missing || templateChanged || current?.published !== true))
+            emit.change("workflow.publish", { schemaCode: intent.code, code: workflow.code, ...(workflow.template !== undefined ? { template: workflow.template } : {}) }, resource, current?.published === true ? "workflow-template-drift" : "workflow-not-published");
+        // Rule bindings: ensure-present. `workflow.bindRule` merges, so we add only
+        // the codes missing from the draft and never touch undeclared ones. Runs
+        // after create/update/publish because the workflow must exist first.
+        for (const binding of workflow.bindRules ?? []) {
+            const bindingResource = `workflow-binding:${intent.code}.${workflow.code}.${binding.handler}`;
+            const liveCodes = current?.bindings?.[binding.handler] ?? [];
+            const missingCodes = binding.ruleCodes.filter((code) => !liveCodes.includes(code));
+            if (missingCodes.length > 0)
+                emit.change("workflow.bindRule", { schemaCode: intent.code, workflowCode: workflow.code, ruleCodes: missingCodes, handler: binding.handler, publish: workflow.publish }, bindingResource, "workflow-rule-not-bound");
+            else
+                emit.skip(bindingResource, "workflow-rule-bound");
+        }
+    },
+    decode(baseline, draft) {
+        if (baseline.workflow)
+            draft.workflow = { present: baseline.workflow.present, published: baseline.workflow.published, template: baseline.workflow.template, bindings: baseline.workflow.bindings };
+    },
+    compare(intent, live, emit) {
+        const workflow = intent.workflow;
+        if (!workflow)
+            return;
+        const current = live.workflow;
+        const resource = `workflow:${intent.code}.${workflow.code}`;
+        if (!current?.present) {
+            emit.difference("workflow-missing", resource, `流程 ${intent.code}.${workflow.code} 不存在`);
+            return;
+        }
+        if (workflow.template !== undefined && !workflowMatches(current.template, workflow.template))
+            emit.difference("workflow-template-mismatch", resource, `流程 ${intent.code}.${workflow.code} 的活动/连线不等价：${workflowMismatchDetail(current.template, workflow.template)}`);
+        if (workflow.publish && !current.published)
+            emit.difference("workflow-not-published", resource, `流程 ${intent.code}.${workflow.code} 未发布`);
+        for (const binding of workflow.bindRules ?? []) {
+            const liveCodes = current.bindings?.[binding.handler] ?? [];
+            if (binding.ruleCodes.some((code) => !liveCodes.includes(code)))
+                emit.difference("workflow-rule-not-bound", `workflow-binding:${intent.code}.${workflow.code}.${binding.handler}`, `流程 ${intent.code}.${workflow.code} 的 ${binding.handler} 未绑定全部声明规则`);
+        }
+    },
+};
+//# sourceMappingURL=workflow.js.map

package/dist/intent/capability.js

@@ -0,0 +1,6 @@
+import { ToolRefusalError } from "../tool-types.js";
+/** The refusal every assembler and capability shares (exact historical shape). */
+export function refuse(blocker, message, extra = {}) {
+    throw new ToolRefusalError({ status: "refused", blocker, message, ...extra });
+}
+//# sourceMappingURL=capability.js.map

package/dist/intent/cli.js

@@ -0,0 +1,91 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { assertSafeInputPath } from "../artifacts.js";
+import { CLI_ARGS_MAX_BYTES } from "../call.js";
+import { INTENT_VERSION, parseIntent, YamlSyntaxError, IntentInvalidError } from "./dsl.js";
+/**
+ * Ticket 117 — the `omc intent` command family (Spec 107 usage face).
+ * validate is fully offline; plan/apply/readback land in tickets 118-120.
+ */
+export const INTENT_COMPILER_VERSION = "omc-intent-compiler/1";
+export function readIntentFile(root, path) {
+    const safePath = assertSafeInputPath(root, path, "intent file");
+    const content = readFileSync(safePath, "utf8");
+    if (Buffer.byteLength(content) > CLI_ARGS_MAX_BYTES)
+        throw new Error(`intent file exceeds ${CLI_ARGS_MAX_BYTES} bytes`);
+    return content;
+}
+/** Validate an intent file's text offline (zero environment contact). */
+export function validateIntentText(text) {
+    try {
+        const { intent } = parseIntent(text);
+        return { status: "ok", valid: true, errors: [], intent };
+    }
+    catch (error) {
+        if (error instanceof YamlSyntaxError)
+            return {
+                status: "error",
+                valid: false,
+                errors: [{ code: "yaml-syntax-error", message: error.message, path: "", line: error.line, column: error.column }],
+            };
+        if (error instanceof IntentInvalidError)
+            return { status: "error", valid: false, errors: error.errors };
+        throw error;
+    }
+}
+/** The intent-face capability block surfaced by `omc commands --json`. */
+export function intentCapabilityBlock() {
+    return {
+        intentVersion: INTENT_VERSION,
+        compiler: INTENT_COMPILER_VERSION,
+        commands: ["intent validate <file> [--show-intent]", "intent plan <file> --env <env> (大 plan 自动外置，回 planFile；用 intent apply <planFile>)", "intent apply <planFile|plan.json> [--no-verify]", "intent readback <file> --env <env>"],
+        lifecycle: "model -> field create (incl. CHILD_TABLE subFields) -> field publish -> form draft/publish -> listview -> businessrule (rule.save + rule.enable/disable); apply confirms the final readback by default",
+        declarativeCapabilities: { model: "partial", field: "partial", businessrule: "partial", datarule: "partial", workflow: "partial", onlinejs: "partial", bizservice: "partial", report: "partial" },
+        absence: "models[].absent:true deletes a whole model; fields[]/listview/datarules[] take absent:true too. Only declared-absent resources are deleted; riskClass becomes destructive and plan.cleanup lists them.",
+        workflowBindings: "models[].workflow.bindRules: [{handler: start|cancel|activate|end, ruleCodes:[...]}] ensures the rules are bound (workflow.bindRule MERGES; undeclared bindings are ignored).",
+        servicesNote: "top-level services[] registers a new service (optional one method) or patches an existing one; adding a method to an existing service has no declarative tool yet.",
+        reportsNote: "top-level reports[] creates/configures a report page + BI dashboard (global/attributes/charts); charts diff by uuid, removeUnlistedCharts:true deletes undeclared charts. Only declared reports are touched.",
+        applyVerification: {
+            default: "on",
+            semantics: "after a DELIVERED apply, decode the authoritative live state back into intent shape; equivalent=true -> verification.status=ok; otherwise status=refused + blocker intent-readback-mismatch (exit 12)",
+            optOut: "--no-verify",
+        },
+        fieldFamilies: [
+            "SHORT_TEXT",
+            "LONG_TEXT",
+            "NUMERICAL",
+            "DATE",
+            "LOGICAL",
+            "SELECTION",
+            "ATTACHMENT",
+            "CHILD_TABLE",
+            "WORK_SHEET",
+            "ADDRESS",
+            "MULT_WORK_SHEET",
+            "RADIO",
+            "CHECKBOX",
+            "DROPDOWN_BOX",
+            "DROPDOWN_MULTI_BOX",
+            "RELEVANCE_DATA",
+            "HYPER_LINK",
+            "TIME",
+            "STAFF_SELECTOR",
+            "STAFF_MULTI_SELECTOR",
+            "DEPARTMENT_SELECTOR",
+            "DEPARTMENT_MULTI_SELECTOR",
+            "FORMULA",
+        ],
+        constraints: [
+            "ensure-present semantics: resources outside the intent are never deleted or modified",
+            "type drift on an existing field is refused (use the omc call escape hatch)",
+            "CHILD_TABLE fields declare their child columns as subFields[{code,name,type[,choices]}]; child families are scalars only (no nested child table / relation / formula)",
+            "a rule declares actions (compact UPDATE) or nodeGraph, never both; non-UPDATE node types use nodeGraph",
+            "escape hatch: uncovered capabilities stay available through omc call or a raw nodeGraph",
+        ],
+        example: 'intentVersion: 1\nmodels:\n  - code: eval_m1\n    name: 评测建模\n    fields:\n      - code: f_title\n        name: 标题\n        type: SHORT_TEXT\n      - code: items\n        name: 明细\n        type: CHILD_TABLE\n        subFields:\n          - code: item_name\n            name: 项目\n            type: SHORT_TEXT\n    form:\n      publish: true\n',
+    };
+}
+export function intentConfigRoot() {
+    return resolve(process.env.OMC_CONFIG_HOME ?? process.cwd());
+}
+//# sourceMappingURL=cli.js.map

package/dist/intent/compare.js

@@ -0,0 +1,56 @@
+/**
+ * Canonical value serialization for intent equivalence checks. Two values that
+ * differ only by key order, or by whether a JSON column is still a string or
+ * already parsed, must compare equal — otherwise an already-converged
+ * environment would report perpetual drift.
+ *
+ * `undefined` and `null` deliberately share one canonical form so an omitted
+ * optional field equals a platform-supplied null/default.
+ */
+export function canonicalValue(value) {
+    if (value === undefined || value === null)
+        return "null";
+    if (Array.isArray(value))
+        return `[${value.map(canonicalValue).join(",")}]`;
+    if (typeof value === "string") {
+        try {
+            const parsed = JSON.parse(value);
+            if (parsed !== null && typeof parsed === "object")
+                return canonicalValue(parsed);
+        }
+        catch {
+            // A plain scalar string (URL, name, code) stays a scalar.
+        }
+        return JSON.stringify(value);
+    }
+    if (typeof value === "object") {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, entry]) => `${JSON.stringify(key)}:${canonicalValue(entry)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+/** True when two values are equivalent under `canonicalValue`. */
+export function sameValue(left, right) {
+    return canonicalValue(left) === canonicalValue(right);
+}
+/**
+ * Equivalence for an optional field: a missing value equals the platform's
+ * `false` default in EITHER direction. The real platform stores `childRule:false`
+ * on live rows while an intent omits the key, so `(false, undefined)` must equal
+ * as well as `(undefined, false)` — otherwise a converged environment reports
+ * perpetual drift (a real-platform-only case the fake hid by omitting the key).
+ */
+export function optionalSame(left, right) {
+    const leftAbsent = left === undefined || left === null;
+    const rightAbsent = right === undefined || right === null;
+    if (leftAbsent && rightAbsent)
+        return true;
+    if (leftAbsent && right === false)
+        return true;
+    if (rightAbsent && left === false)
+        return true;
+    return sameValue(left, right);
+}
+//# sourceMappingURL=compare.js.map