@stalfh233/omc-cli 0.0.0-stage → 0.4.0

package/dist/lanes/field.js

@@ -0,0 +1,374 @@
+import { z } from "zod";
+import { ENDPOINTS } from "../endpoints.js";
+import { fieldChangeWireBody, fieldUpdateWireBody, prepareFieldChange, prepareFieldUpdate } from "../field-change.js";
+import { choicesArg, fieldOptionsArg, fieldTypeLabel, numericalScaleWarning, propertyTypeArg, relativeCodeArg, subFieldArg, SYSTEM_FIELD_CODES, } from "../field-families.js";
+import { capabilityArg, environmentArg } from "../args.js";
+import { governedRead } from "../read.js";
+import { writeTool } from "../write.js";
+import { decodeJsonColumn, decodeJsonObjectColumn, JSON_COLUMN_PASSTHROUGH } from "../json-column.js";
+import { syncFormConditionDataRules } from "./datarule.js";
+import { FORM_CONDITION_OPTION_KEYS } from "./datarule-protocol.js";
+import { defineTool, ToolRefusalError } from "../tool-types.js";
+import { wireCall, wireRows, WireError } from "../wire.js";
+import { FIELD_LANE_CONTRACT } from "./field-contract.js";
+const FIELD_LANE = FIELD_LANE_CONTRACT.lane;
+const FIELD_TOOLS = FIELD_LANE_CONTRACT.tools;
+/** Parse a raw options JSON string for readback; policy: non-strings and unparseable strings pass through verbatim. */
+function parseFieldOptionsForReadback(options) {
+    return decodeJsonColumn(options, JSON_COLUMN_PASSTHROUGH);
+}
+/**
+ * `name_i18n` is a JSON locale map. When every locale value equals the display
+ * `name` there is no translation to convey, so echoing the map on every field of
+ * every `field.list` readback is pure noise (~45 B/field; a 16-field model ≈700 B,
+ * ~27% of that read). Omit it then; a real translation (a locale differing from
+ * `name`, or a locale-specific value) is preserved verbatim.
+ */
+function redundantNameI18n(nameI18n, name) {
+    if (typeof nameI18n !== "string" || typeof name !== "string")
+        return false;
+    let parsed;
+    try {
+        parsed = JSON.parse(nameI18n);
+    }
+    catch {
+        return false;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return false;
+    const values = Object.values(parsed);
+    return values.length > 0 && values.every((value) => value === name);
+}
+/**
+ * Ticket 60: a supplied `name_i18n` must be an object, or a string that parses
+ * to an object (never an array / bare display string). Runs before the approval
+ * gate so a malformed repair never burns a token or reaches the wire.
+ */
+function assertNameI18nArg(nameI18n) {
+    if (nameI18n === undefined)
+        return;
+    const refuse = (reason) => {
+        throw new ToolRefusalError({ status: "refused", blocker: "field-name-i18n-invalid", message: `field.update 的 name_i18n 必须是对象或可解析为对象的 JSON 串：${reason}` });
+    };
+    if (typeof nameI18n !== "string") {
+        if (typeof nameI18n !== "object" || nameI18n === null || Array.isArray(nameI18n))
+            refuse("收到非对象值");
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(nameI18n);
+    }
+    catch {
+        refuse("字符串不是合法 JSON");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        refuse("JSON 解析结果不是对象");
+}
+export function registerFieldLane(tools) {
+    tools.push(defineTool({
+        name: "field.list",
+        layer: "low",
+        kind: "read",
+        lane: FIELD_LANE,
+        scope: FIELD_TOOLS["field.list"].scope,
+        description: FIELD_TOOLS["field.list"].description,
+        inputSchema: { environment: environmentArg, schemaCode: z.string(), published: z.boolean().default(false), code: z.string().optional(), fields: z.array(z.string()).optional(), all: z.boolean().optional().describe("默认只返业务字段（过滤 SYSTEM_FIELD_CODES 的 13 个平台字段：id/name/sequenceNo/createdTime/creater/sequenceStatus/…）；true 连系统字段一起返"), capability: capabilityArg },
+        handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
+            const rows = wireRows((await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: args.published ? "true" : "false" } })).data);
+            const mapped = rows.map((row) => {
+                const type = Number(row.type ?? row.propertyType);
+                const typeLabel = fieldTypeLabel(row.type ?? row.propertyType);
+                const options = row.options !== undefined && row.options !== null ? parseFieldOptionsForReadback(row.options) : undefined;
+                // Round 4 (ADR 0005): read-side annotation for stored scale-less
+                // NUMERICAL landmines (the platform accepted them for years).
+                const scaleWarning = numericalScaleWarning(type, options);
+                return {
+                    code: row.code ?? row.propertyCode,
+                    name: row.name,
+                    ...(redundantNameI18n(row.name_i18n, row.name) ? {} : typeof row.name_i18n === "string" ? { name_i18n: row.name_i18n } : {}),
+                    type: row.type ?? row.propertyType,
+                    ...(typeLabel !== undefined ? { typeName: typeLabel } : {}),
+                    ...(row.subSchema !== undefined && row.subSchema !== null ? { subSchema: row.subSchema } : {}),
+                    ...(row.relativeCode ? { relativeCode: row.relativeCode } : {}),
+                    ...(typeof row.relativePropertyCode === "string" && row.relativePropertyCode ? { relativePropertyCode: row.relativePropertyCode } : {}),
+                    ...(options !== undefined ? { options } : {}),
+                    ...(scaleWarning !== undefined ? { shapeWarning: scaleWarning } : {}),
+                };
+            });
+            // Projection: ask for one field (`--code`) or a named set (`--fields`) so a
+            // caller can verify one field's `options` without pulling the whole list
+            // (which token-diets to {count,sha256} past 4 KB) through an artifact.
+            const selector = [args.code, ...(args.fields ?? [])].filter((entry) => typeof entry === "string" && entry.length > 0);
+            const selected = selector.length > 0 ? mapped.filter((field) => selector.includes(String(field.code))) : mapped;
+            // Round 10: the default face is BUSINESS fields only — 13 of 21 fields on a
+            // typical model are platform system fields, so a caller asking "what fields
+            // does this model have" paid for noise it then had to filter. `all:true`
+            // restores the previous full list (uses the SAME SYSTEM_FIELD_CODES set the
+            // list-view/form scaffolds already filter with).
+            const visible = args.all === true ? selected : selected.filter((field) => !SYSTEM_FIELD_CODES.has(String(field.code)));
+            return { schemaCode: args.schemaCode, published: args.published === true, ...(selector.length > 0 ? { selected: selector } : {}), ...(args.all !== true ? { businessOnly: true } : {}), fields: visible };
+        }, {
+            // Round 4: the default diet reduced the whole list to a count, so agents
+            // fetched the 28 KB artifact just to read field codes (benchmark: 4×28 KB).
+            // The useful compact form is the inventory: code/type/name (+ any shape
+            // warning). `options` stays out — use code/fields selector for that.
+            target: `field.list:${args.schemaCode}:${args.published === true ? "published" : "draft"}`,
+            compact: (result) => {
+                const fields = Array.isArray(result.fields) ? result.fields : [];
+                return {
+                    schemaCode: result.schemaCode,
+                    published: result.published,
+                    ...(result.businessOnly === true ? { businessOnly: true } : {}),
+                    ...(result.selected !== undefined ? { selected: result.selected } : {}),
+                    fields: fields.map((field) => {
+                        // Round 4 (live bench26): the diet dropped `options` entirely, so an
+                        // agent could not tell an authored form condition existed and either
+                        // re-added it or paid an `--full`/artifact read to check. Signal just
+                        // the non-empty condition KEY NAMES (a few bytes), values stay out.
+                        const options = (field.options ?? {});
+                        const conditions = Object.keys(FORM_CONDITION_OPTION_KEYS).filter((key) => {
+                            const value = options[key];
+                            return key === "readonlyFormula" ? value === true : typeof value === "string" && value.trim() !== "";
+                        });
+                        return {
+                            code: field.code,
+                            type: field.type,
+                            ...(field.typeName !== undefined ? { typeName: field.typeName } : {}),
+                            ...(field.name !== undefined ? { name: field.name } : {}),
+                            ...(conditions.length > 0 ? { conditions } : {}),
+                            ...(field.shapeWarning !== undefined ? { shapeWarning: field.shapeWarning } : {}),
+                        };
+                    }),
+                    hint: "字段详情（options/subSchema）用 omc call field.list --args '{\"schemaCode\":\"...\",\"published\":true,\"code\":\"<field>\"}'",
+                };
+            },
+        }),
+    }));
+    writeTool(tools, "field.create", FIELD_LANE, FIELD_TOOLS["field.create"].scope, FIELD_TOOLS["field.create"].description, {
+        schemaCode: z.string().min(1),
+        code: z.string().min(1),
+        name: z.string().min(1),
+        propertyType: propertyTypeArg,
+        options: fieldOptionsArg.optional(),
+        relativeCode: relativeCodeArg,
+        choices: choicesArg,
+        subFields: subFieldArg,
+        propertyEmpty: z.boolean().optional().describe("数据模型层是否声明该字段不可为空；默认 false（可为空）。必填/只读请在表单设计与流程节点权限配置，不要在模型层设置——平台会据此把流程各节点强制成可见+可编辑+必填"),
+    }, async (session, args) => {
+        const draft = wireRows((await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "false" } })).data);
+        const published = wireRows((await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "true" } })).data);
+        if ([...draft, ...published].some((row) => (row.code ?? row.propertyCode) === args.code))
+            throw new ToolRefusalError({ status: "refused", blocker: "duplicate-field", schemaCode: args.schemaCode, propertyCode: args.code, message: `字段 ${args.schemaCode}.${args.code} 已存在于草稿或发布面；拒绝重复 POST` });
+        // One seam owns field-change normalization, every reproduced gate, and the
+        // wire body (src/field-change.ts), so configure_model and intent share it.
+        const prepared = prepareFieldChange(args);
+        const performed = await wireCall(session, { path: ENDPOINTS.fieldCreate, method: "POST", body: fieldChangeWireBody(args, prepared) });
+        const readback = await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "false" } });
+        const rows = wireRows(readback.data);
+        return {
+            performed: { errcode: performed.errcode },
+            readback: { draftFieldPresent: rows.some((row) => (row.code ?? row.propertyCode) === args.code) },
+        };
+    });
+    writeTool(tools, "field.update", FIELD_LANE, FIELD_TOOLS["field.update"].scope, FIELD_TOOLS["field.update"].description, {
+        schemaCode: z.string().min(1),
+        code: z.string().min(1),
+        name: z.string().min(1).optional().describe("new display name; also rewrites name_i18n to a valid JSON object string"),
+        name_i18n: z.union([z.record(z.string(), z.unknown()), z.string()]).optional().describe("explicit i18n object (or JSON object string) to store verbatim; must parse to an object"),
+        options: fieldOptionsArg.optional(),
+        choices: choicesArg,
+        relativeCode: relativeCodeArg,
+        subFields: subFieldArg,
+        propertyEmpty: z.boolean().optional().describe("覆盖数据模型层的不可为空声明；传 false 可把历史误建的字段改回可为空（必填/只读应在表单与流程节点配置）"),
+    }, async (session, args) => {
+        const listed = await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "false" } });
+        let rows = wireRows(listed.data);
+        if (!rows.some((row) => (row.code ?? row.propertyCode) === args.code)) {
+            const published = await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "true" } });
+            rows = wireRows(published.data);
+        }
+        const record = rows.find((row) => (row.code ?? row.propertyCode) === args.code);
+        if (!record)
+            throw new WireError("business", `field ${args.code} not found on ${args.schemaCode}`, 301001);
+        const update = {
+            schemaCode: args.schemaCode,
+            code: args.code,
+            base: record,
+            ...(args.name !== undefined ? { name: args.name } : {}),
+            ...(args.name_i18n !== undefined ? { name_i18n: args.name_i18n } : {}),
+            ...(args.options !== undefined ? { options: args.options } : {}),
+            ...(args.choices !== undefined ? { choices: args.choices } : {}),
+            ...(args.relativeCode !== undefined ? { relativeCode: args.relativeCode } : {}),
+            ...(args.subFields !== undefined ? { subFields: args.subFields } : {}),
+            ...(args.propertyEmpty !== undefined ? { propertyEmpty: args.propertyEmpty } : {}),
+        };
+        const prepared = prepareFieldUpdate(update);
+        const performed = await wireCall(session, { path: ENDPOINTS.fieldUpdate, method: "POST", body: fieldUpdateWireBody(update, prepared) });
+        const readback = await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "false" } });
+        const after = wireRows(readback.data).find((row) => (row.code ?? row.propertyCode) === args.code);
+        // Round 4 (B): a form-interaction condition must exist on BOTH faces to be
+        // complete — field options (portal runtime) AND a bizdatarule type3/4/5
+        // row (designer design-time Set/Unset). field.update historically wrote
+        // only options, so CLI-authored conditions showed "Unset" in the designer.
+        // Pair the changed condition key(s) into the rule projection; a sync
+        // failure never hides the field write (it is surfaced as formConditionSync.error).
+        let formConditionSync;
+        let formConditionSyncError;
+        if (args.options !== undefined && !prepared.isChildTable) {
+            const previous = decodeJsonObjectColumn(record.options, { invalid: "throw", array: "accept", object: "accept" }) ?? {};
+            try {
+                const sync = await syncFormConditionDataRules(session, args.schemaCode, args.code, previous, prepared.options);
+                if (sync.created.length + sync.updated.length + sync.deleted.length + sync.skipped.length > 0)
+                    formConditionSync = sync;
+            }
+            catch (error) {
+                formConditionSyncError = error instanceof Error ? error.message : String(error);
+            }
+        }
+        // Round 4: echo the EFFECTIVE stored options (parsed), not just presence.
+        // An agent setting readonlyFormula/requiredFormula/scale had no way to
+        // confirm the write landed — the readback only named the field. Field
+        // options are the form-interaction contract (ADR 0005), so read them back.
+        const storedOptions = after !== undefined ? parseFieldOptionsForReadback(after.options) : undefined;
+        return {
+            performed: { errcode: performed.errcode },
+            readback: {
+                fieldPresent: after !== undefined,
+                ...(after?.name !== undefined ? { name: after.name } : {}),
+                ...(typeof after?.name_i18n === "string" ? { name_i18n: after.name_i18n } : {}),
+                ...(after?.type !== undefined || after?.propertyType !== undefined ? { type: after?.type ?? after?.propertyType } : {}),
+                ...(storedOptions !== undefined && storedOptions !== null ? { options: storedOptions } : {}),
+                ...(formConditionSync !== undefined ? { formConditionSync } : {}),
+                ...(formConditionSyncError !== undefined ? { formConditionSync: { error: formConditionSyncError } } : {}),
+            },
+        };
+    }, (args) => assertNameI18nArg(args.name_i18n));
+    writeTool(tools, "field.publish", FIELD_LANE, FIELD_TOOLS["field.publish"].scope, FIELD_TOOLS["field.publish"].description, {
+        schemaCode: z.string().min(1),
+        code: z.string().min(1).optional().describe("optional single field to verify on the published face"),
+        codes: z.array(z.string().min(1)).optional().describe("optional list of fields to verify; publishing is model-scoped, do NOT call once per field"),
+    }, async (session, args) => {
+        // bizproperty/publish is MODEL-SCOPED: one call publishes every draft
+        // field of the schema. `code`/`codes` only select which fields to verify
+        // on the published face after the single publish; omit them to publish
+        // and read back all codes (the batch path).
+        //
+        // Ticket 81 idempotent retry: with explicit code/codes, read the
+        // published face FIRST (a retry after a timeout hits the wire read
+        // cache — zero extra wires) and skip the publish POST entirely when
+        // every requested field is already published. A genuinely missing
+        // field still drives the publish.
+        const requestedCodes = [...(args.code ? [args.code] : []), ...(args.codes ?? [])];
+        const codeOf = (row) => String(row.code ?? row.propertyCode ?? "");
+        // cpdocs base3.0 parity (cp-bizproperty verifyPlan): presence on the
+        // published LIST face is proven later, against a map of each field's
+        // pre-publish DRAFT shape (name + type). The draft face must be
+        // snapshotted BEFORE the publish because a model-scoped publish can leave
+        // it empty; the draft row is the caller-visible expectation.
+        const draftSnapshot = new Map(wireRows((await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "false" } })).data)
+            .map((row) => [codeOf(row), { name: String(row.name ?? ""), propertyType: Number(row.type ?? row.propertyType) }]));
+        const verifyFieldDetails = async (targets) => {
+            const bounded = targets.slice(0, 25);
+            const mismatches = [];
+            for (const code of bounded) {
+                const expected = draftSnapshot.get(code);
+                if (!expected)
+                    continue;
+                let detail;
+                try {
+                    detail = (await wireCall(session, { path: ENDPOINTS.fieldGet, query: { schemaCode: args.schemaCode, propertyCode: code } })).data;
+                }
+                catch {
+                    // The detail endpoint is optional across builds: report the
+                    // verification as unavailable rather than failing the publish.
+                    return { mode: "unavailable", verified: false, note: "bizproperty/get 不可用，字段详情未核对（仅列表面存在性）" };
+                }
+                const actual = { name: String(detail.name ?? ""), propertyType: Number(detail.propertyType ?? detail.type) };
+                if (actual.name !== expected.name || actual.propertyType !== expected.propertyType)
+                    mismatches.push({ code, expected, actual });
+            }
+            return { mode: "detail", verified: true, checked: bounded.length, ok: mismatches.length === 0, ...(mismatches.length > 0 ? { mismatches } : {}) };
+        };
+        const preRead = await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "true" } });
+        const prePublished = wireRows(preRead.data).map(codeOf).filter((code) => code.length > 0);
+        if (requestedCodes.length > 0 && requestedCodes.every((code) => prePublished.includes(code))) {
+            return {
+                performed: { skipped: "already-published", scope: "model" },
+                readback: {
+                    publishedCodes: prePublished,
+                    ...(args.code ? { publishedFieldPresent: true } : {}),
+                    ...(args.codes ? { publishedFieldsPresent: Object.fromEntries(args.codes.map((code) => [code, true])) } : {}),
+                    allRequestedPresent: true,
+                    verification: await verifyFieldDetails(requestedCodes),
+                },
+            };
+        }
+        // Ticket 79 live-fidelity (docker log evidence, 2026-09-13 21:43-21:45,
+        // cloud8_launcher log_error.log + nginx access timings): under DB
+        // connection-pool contention a model publish can fail with a transient
+        // `表单:<t>_<schema>不存在列:<col>` 50000 — the addIndexes/updateColumns
+        // assert reads the serializer view while the failed attempt's DDL
+        // auto-commits, so the state SELF-HEALS across retries (live: three
+        // consecutive attempts each healed one column, the fourth succeeded).
+        // Retry that exact signature up to 3 attempts; anything else rethrows.
+        let performed;
+        // Backoff matches the observed healing cadence on the small env (live:
+        // attempts ~25s/73s apart each reconciled one column).
+        const backoffMs = [2000, 5000];
+        for (let attempt = 1; attempt <= 3; attempt++) {
+            try {
+                performed = await wireCall(session, {
+                    path: ENDPOINTS.fieldPublish,
+                    method: "POST",
+                    body: { bizSchemaCode: args.schemaCode, sendMessage: false },
+                });
+                break;
+            }
+            catch (error) {
+                const transientColumnSync = error instanceof WireError && error.kind === "business" && error.errcode === 50000 && error.message.includes("不存在列");
+                if (!(transientColumnSync && attempt < 3))
+                    throw error;
+                await new Promise((resolve) => setTimeout(resolve, backoffMs[attempt - 1] ?? 5000));
+            }
+        }
+        const publishOutcome = performed;
+        const readback = await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "true" } });
+        const publishedCodes = wireRows(readback.data).map(codeOf).filter((code) => code.length > 0);
+        const requested = [...(args.code ? [args.code] : []), ...(args.codes ?? [])];
+        const present = requested.filter((code) => publishedCodes.includes(code));
+        const targets = (requested.length > 0 ? requested : [...draftSnapshot.keys()]).filter((code) => publishedCodes.includes(code));
+        const verification = await verifyFieldDetails(targets);
+        const mismatches = verification.mismatches;
+        if (mismatches !== undefined)
+            throw new ToolRefusalError({
+                status: "refused",
+                blocker: "field-publish-readback-mismatch",
+                performed: { errcode: publishOutcome.errcode, scope: "model" },
+                mismatches,
+                message: `字段已发布，但发布后详情回读与草稿面不一致（${mismatches.map((item) => String(item.code)).join("、")}）：这是元数据与预期形状相异的信号，先核对再决定后续；不要当作成功`,
+            });
+        return {
+            performed: { errcode: publishOutcome.errcode, scope: "model" },
+            readback: {
+                publishedCodes,
+                ...(args.code ? { publishedFieldPresent: publishedCodes.includes(args.code) } : {}),
+                ...(args.codes ? { publishedFieldsPresent: Object.fromEntries(args.codes.map((code) => [code, publishedCodes.includes(code)])) } : {}),
+                ...(requested.length > 0 ? { allRequestedPresent: present.length === requested.length } : {}),
+                verification,
+            },
+        };
+    });
+    writeTool(tools, "field.delete", FIELD_LANE, FIELD_TOOLS["field.delete"].scope, FIELD_TOOLS["field.delete"].description, { schemaCode: z.string().min(1), code: z.string().min(1) }, async (session, args) => {
+        const performed = await wireCall(session, {
+            path: ENDPOINTS.fieldForceDelete,
+            method: "POST",
+            query: { bizSchemaCode: args.schemaCode, bizPropertyCode: args.code },
+        });
+        const draft = await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "false" } });
+        const published = await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "true" } });
+        const gone = (value) => !wireRows(value).some((row) => (row.code ?? row.propertyCode) === args.code);
+        return { performed: { errcode: performed.errcode }, readback: { absentDraft: gone(draft.data), absentPublished: gone(published.data) } };
+    });
+}
+//# sourceMappingURL=field.js.map

package/dist/lanes/form-contract.js

@@ -0,0 +1,97 @@
+import { assertDescriptionCarries, assertLaneContract, behaviorBinding, CONTRACT_FAMILY, CONTRACT_REFERENCE_VERSION } from "./contract-support.js";
+import { LANES } from "./lane-ids.js";
+/**
+ * form-publish-chain wire facts (live-proven). The draft→publish promotion,
+ * the empty-form scaffold, and the relation-mapping carry are the single
+ * source for the handler descriptions and the coverage declarations.
+ */
+export const FORM_WIRE = Object.freeze({
+    draftBody: "bizsheet/update: reads the current sheet, merges explicit draftViewJson/draftAttributesJson or preserves the existing draft; an empty fresh default form is scaffolded from the model's published fields",
+    scaffold: "designer-standard default-form scaffold: Title(203, useDataTitle) + system row creater(101)/createdTime(104)/sequenceNo(100) + group(200) + one mapped control per published business field",
+    relationMappings: "a relation field's options.mappings is the source of truth and is propagated into the matching form control's options.mappings",
+    redundantFieldVisibility: "ticket 66: a redundant field is a relation-mapping carry-through target (options.mappings[{source,target}]) — it stays BOUND on the form; when the model has no workflow (GET workflow/isworkflow?schemaCode false, WorkflowTemplateController.java:1348) the scaffold sets its control options.visible=false (form-design hidden, option 1); with a workflow it stays visible and per-node visibility is configured via each activity's propertyPermissions (ParticipantActivity.java:52, PropertyPermission.visible/editable/required — option 2, preferred), carried through the workflow template",
+    missingFieldsErrcode: 302020,
+    publishBody: "bizsheet/publish promotes draft*Json → published*Json verbatim (including draftHtmlJson → publishedHtmlJson); a saved draft (draftViewJson/draftAttributesJson) is required",
+    publishAlreadyPublished: "published:true with force!==true skips as already-published",
+    forceRepublish: "onlinejs.compose passes force:true so it can re-promote after a prior publish",
+    emptyLayoutGuard: "ticket 74: the platform designer's Save is NOT lossless — it clears draftViewJson to \"[]\" and draftAttributesJson to \"{}\"; form.draft refuses CALLER-PROVIDED empty layouts (blocker form-empty-layout, zero wire, escape allowEmptyLayout:true) and form.publish refuses to promote a draft with fewer controls than the published face (blocker form-publish-degrade, escape allowDegrade:true); the recovery path is the form version history (/api/api/app/bizsheet/history/list) — fetch the intact version's view/attributes originals and rewrite the draft before publishing",
+    actionsColumns: "ticket 100: draftActionsJson/publishedActionsJson are REAL bizsheet columns (BizForm.java:95-100 @SerializableField; BizFormModel.java:59-62 serialized by bizsheet/get) — the designer writes draftActionsJson on save and both faces on publish (frontend-dist/admin/js/4280.cfa75764.js offsets 193538/185347); form.get full:true surfaces them; publish promotes draftActionsJson → publishedActionsJson",
+});
+const FORM_GET_DESCRIPTION = '读取默认表单（bizsheet/get）的发布状态与控件清单（紧凑默认）。**发布态以返回的 `published` / `existDraft` 布尔为准**（`published:true`=已发布；`published:false,existDraft:true`=只有草稿，**未发布**）——不要用 `publishedControlCodes` 是否非空来推断（草稿字段会让它非空，误判为已发布）。**每个模型交付前其默认表单必须 `published:true`**：用 `configure_form` 或 `form.draft(rebuild:true)`+`form.publish` 发布，并逐模型 `form.get` 核对。传 `controls:["code",…]` 只取指定控件的 options（如关联控件的 mappings）；传 `full:true` 才返回 draft/published 的完整 view/attributes/html/actions JSON（actions 列为设计器保存/发布的表单级按钮动作）。体积大，仅在需要整体布局时用。';
+const FORM_DRAFT_DESCRIPTION = "Save the default-form DRAFT (bizsheet/update). Reads the current sheet, merges the caller's explicit draftViewJson/draftAttributesJson (or preserves the existing draft); when both are absent on a fresh default form, composes the designer-standard scaffold from the model's published fields. A redundant field (relation-mapping carry-through target) always stays bound; with no workflow it is hidden in the design (options.visible=false), with a workflow it stays visible for per-node propertyPermissions. Pass `draftHtmlJson` to thread custom online-script HTML through. Empty-layout guard: explicitly passing \"[]\"/\"{}\" view/attributes is refused (form-empty-layout) — the platform designer's Save is NOT lossless and clears drafts to exactly that shape; escape with allowEmptyLayout:true, and recover cleared drafts from the form version history (/api/api/app/bizsheet/history/list).";
+const FORM_PUBLISH_DESCRIPTION = "Publish the default form (bizsheet/publish, proven shape: draft*Json promoted to published*Json verbatim) with published-face readback. Degrade guard: refuses to promote a draft carrying FEWER controls than the published face (form-publish-degrade) — the designer's Save clears drafts non-losslessly; recover via the form version history (/api/api/app/bizsheet/history/list) and rewrite the draft first, or pass allowDegrade:true to force the reduction.";
+const CONFIGURE_FORM_DESCRIPTION = "High-level: bind fields into the default form and publish it (form.draft → form.publish), subject to the write permission gate. Delegates to the proven form.draft scaffold + form.publish paths so the real empty-form layout (and any caller-supplied draftHtmlJson) is persisted and promoted — never bypasses with a shortcut body. `sheetCode` is optional: omitted means the model's default sheet (sheetCode = schemaCode).";
+export const FORM_LANE_CONTRACT = Object.freeze({
+    lane: LANES.form,
+    family: CONTRACT_FAMILY,
+    referenceVersion: CONTRACT_REFERENCE_VERSION,
+    endpoints: Object.freeze({
+        sheetGet: "sheetGet",
+        sheetUpdate: "sheetUpdate",
+        sheetPublish: "sheetPublish",
+        fieldList: "fieldList",
+    }),
+    wire: Object.freeze({
+        draftBody: FORM_WIRE.draftBody,
+        scaffold: FORM_WIRE.scaffold,
+        relationMappings: FORM_WIRE.relationMappings,
+        redundantFieldVisibility: FORM_WIRE.redundantFieldVisibility,
+        missingFieldsErrcode: FORM_WIRE.missingFieldsErrcode,
+        publishBody: FORM_WIRE.publishBody,
+        publishAlreadyPublished: FORM_WIRE.publishAlreadyPublished,
+        forceRepublish: FORM_WIRE.forceRepublish,
+        emptyLayoutGuard: FORM_WIRE.emptyLayoutGuard,
+        actionsColumns: FORM_WIRE.actionsColumns,
+    }),
+    wireBindings: Object.freeze({
+        draftBody: Object.freeze([behaviorBinding("test/form-scaffold.test.ts#form.draft scaffolds an empty default form from published fields", assertFormContract)]),
+        scaffold: Object.freeze([behaviorBinding("test/form-scaffold.test.ts#form.draft scaffolds an empty default form from published fields", assertFormContract)]),
+        relationMappings: Object.freeze([behaviorBinding("test/form-scaffold.test.ts#form.draft propagates a relation field's mappings into its form control", assertFormContract)]),
+        redundantFieldVisibility: Object.freeze([behaviorBinding("test/redundant-field-form.test.ts#form.draft binds a redundant field but hides it when the model has no workflow", assertFormContract)]),
+        missingFieldsErrcode: Object.freeze([behaviorBinding("test/form-lifecycle.test.ts#ticket 42: a fresh model has no form", assertFormContract)]),
+        publishBody: Object.freeze([behaviorBinding("test/form-lifecycle.test.ts#ticket 42: form.publish alone creates + scaffolds + publishes a formless model", assertFormContract)]),
+        publishAlreadyPublished: Object.freeze([behaviorBinding("test/human-summaries.test.ts#configure_model and apply_changes carry whole-package summaries", assertFormContract)]),
+        forceRepublish: Object.freeze([behaviorBinding("test/issue-11-online-js.test.ts#onlinejs.compose merges customScript into the existing draftHtmlJson layout", assertFormContract)]),
+        emptyLayoutGuard: Object.freeze([behaviorBinding("test/ticket-74-form-empty-layout.test.ts#ticket 74: form.draft refuses an explicitly empty draftViewJson", assertFormContract)]),
+        actionsColumns: Object.freeze([behaviorBinding("test/ticket-100-form-actions-columns.test.ts#form.get full:true surfaces draftActionsJson/publishedActionsJson", assertFormContract)]),
+    }),
+    evidence: Object.freeze([
+        ".scratch/omc-route-wayfinder/leg2-closeout.md",
+        "packages/omc-cli/src/form-support.ts (shared draft/publish write bodies)",
+        "packages/omc-cli/test/form-scaffold.test.ts",
+    ]),
+    tools: Object.freeze({
+        "form.get": Object.freeze({ scope: "publishedHtmlJson authoritative readback", description: FORM_GET_DESCRIPTION }),
+        "form.draft": Object.freeze({ scope: "draft publish publishedHtmlJson readback", description: FORM_DRAFT_DESCRIPTION }),
+        "form.publish": Object.freeze({ scope: "draft publish publishedHtmlJson readback", description: FORM_PUBLISH_DESCRIPTION }),
+        configure_form: Object.freeze({ scope: "draft publish publishedHtmlJson readback", description: CONFIGURE_FORM_DESCRIPTION }),
+    }),
+});
+export function assertFormContract() {
+    assertLaneContract(FORM_LANE_CONTRACT);
+    if (FORM_WIRE.missingFieldsErrcode !== 302020)
+        throw new Error("form contract pins the empty-form scaffold errcode to 302020");
+    assertDescriptionCarries(FORM_LANE_CONTRACT, "form.get", ["bizsheet/get", "draft/published", "mappings", "`full:true`", "actions"]);
+    if (!FORM_WIRE.actionsColumns.includes("BizForm.java:95-100"))
+        throw new Error("form contract must pin the actions-columns evidence (ticket 100)");
+    assertDescriptionCarries(FORM_LANE_CONTRACT, "form.draft", ["bizsheet/update", "draftViewJson", "draftAttributesJson", "scaffold", "draftHtmlJson", "form-empty-layout"]);
+    if (!FORM_WIRE.redundantFieldVisibility.includes("propertyPermissions"))
+        throw new Error("form contract must carry the redundant-field visibility (propertyPermissions) fact");
+    assertDescriptionCarries(FORM_LANE_CONTRACT, "form.publish", ["bizsheet/publish", "draft*Json", "published*Json", "verbatim", "form-publish-degrade", "history/list"]);
+    assertDescriptionCarries(FORM_LANE_CONTRACT, "configure_form", ["form.draft", "form.publish", "scaffold", "draftHtmlJson"]);
+    if (!FORM_WIRE.draftBody.includes("bizsheet/update"))
+        throw new Error("form contract must pin the draft update endpoint");
+    if (!FORM_WIRE.scaffold.includes("Title(203") || !FORM_WIRE.scaffold.includes("sequenceNo(100)"))
+        throw new Error("form contract must pin the designer scaffold shape");
+    if (!FORM_WIRE.relationMappings.includes("options.mappings"))
+        throw new Error("form contract must pin the relation-mapping carry");
+    if (!FORM_WIRE.publishBody.includes("bizsheet/publish") || !FORM_WIRE.publishBody.includes("draftHtmlJson"))
+        throw new Error("form contract must pin the publish promotion");
+    if (!FORM_WIRE.publishAlreadyPublished.includes("already-published"))
+        throw new Error("form contract must pin the already-published skip");
+    if (!FORM_WIRE.forceRepublish.includes("force:true"))
+        throw new Error("form contract must pin the force-republish override");
+    if (!FORM_WIRE.emptyLayoutGuard.includes("form-empty-layout") || !FORM_WIRE.emptyLayoutGuard.includes("form-publish-degrade"))
+        throw new Error("form contract must pin the empty-layout/degrade guards");
+}
+//# sourceMappingURL=form-contract.js.map

package/dist/lanes/form-coverage.js

@@ -0,0 +1,16 @@
+import { claim, declareLaneCoverage } from "./coverage-declaration.js";
+import { FORM_LANE_CONTRACT } from "./form-contract.js";
+const T = FORM_LANE_CONTRACT.tools;
+export const FORM_COVERAGE = declareLaneCoverage(FORM_LANE_CONTRACT.lane, [
+    {
+        capability: "Form publish chain (draft-first → publish → publishedHtmlJson readback)",
+        evidence: [".scratch/omc-route-wayfinder/leg2-closeout.md", "packages/omc-cli/src/lanes/form.ts"],
+        tools: [
+            claim("form.get", T["form.get"].scope),
+            claim("form.draft", T["form.draft"].scope),
+            claim("form.publish", T["form.publish"].scope),
+            claim("configure_form", T["configure_form"].scope),
+        ],
+    },
+]);
+//# sourceMappingURL=form-coverage.js.map