@stalfh233/omc-cli 0.0.0-stage → 0.4.0

package/dist/field-families.js

@@ -0,0 +1,896 @@
+import { z } from "zod";
+import { ToolRefusalError } from "./tool-types.js";
+import { decodeJsonObjectColumn } from "./json-column.js";
+import { FIELD_CONTROL_CODES, FIELD_DATE_DEFAULT_OPTIONS, FIELD_DATE_FORMATS, FIELD_FAMILY_LIST } from "./lanes/field-contract.js";
+import { formConditionOptionsError } from "./lanes/datarule-protocol.js";
+import { CAPABILITY_CONTROL_TYPES, capabilityShapeError, deriveControlOptions, deriveFieldOptions } from "./capability-shape.js";
+export { FIELD_FAMILY_LIST, FIELD_CONTROL_CODES };
+export const propertyTypeArg = z
+    .string()
+    .min(1)
+    .describe(`field family. Accepted: ${FIELD_FAMILY_LIST}, CHILD_TABLE (子表, requires \`subFields\`). Out of coverage (refused with a citation): OCR, ELECTRONIC_SIGN, and nested CHILD_TABLE. Selection families take \`choices\`; relation families take \`relativeCode\` + \`options\`.`);
+export const relativeCodeArg = z.string().optional().describe("relation target model code (required for WORK_SHEET / MULT_WORK_SHEET)");
+/**
+ * Ticket 59 (P0): the wire `name_i18n` column must be a *parseable JSON object
+ * string*, never a bare display string. The admin designer runs an unguarded
+ * `JSON.parse(name_i18n)` (frontend `compatibleOldData`); a bare "报修主题"
+ * throws and the whole Display Fields panel fails to render. Every
+ * model/field/sheet create path writes through this one helper so the shape
+ * can never drift again.
+ */
+export function nameI18nJson(name) {
+    return JSON.stringify({ "zh-CN": name, en: name });
+}
+/**
+ * Ticket 61 — the platform ignores a relation field's `options.displayField`
+ * unless `displayFieldType` is also present (it then falls back to the target
+ * model's data title). Live evidence (2026-09-13 repair-module incident): the
+ * designer wrote `displayFieldType:12` for a RADIO(12) display field and the
+ * verified repair wrote `displayFieldType:0` for a SHORT_TEXT(0) one — the
+ * value is the display field's BizPropertyType int. Default 0 (SHORT_TEXT,
+ * the live-verified pairing); pass an explicit int for a non-text display
+ * field. `displayFieldFormat` was "" on both observed faces.
+ */
+export function ensureRelationDisplayFieldOptions(type, options) {
+    if (type !== FIELD_PROPERTY_TYPES.WORK_SHEET && type !== FIELD_PROPERTY_TYPES.MULT_WORK_SHEET)
+        return options;
+    if (typeof options.displayField !== "string" || options.displayField.trim() === "")
+        return options;
+    return {
+        ...options,
+        ...(options.displayFieldType === undefined ? { displayFieldType: 0 } : {}),
+        ...(options.displayFieldFormat === undefined ? { displayFieldFormat: "" } : {}),
+    };
+}
+/**
+ * Ticket 61 root cause (source evidence): the runtime list face resolves a
+ * relation's displayed value from the field ROW's top-level
+ * `relativePropertyCode`, NOT from `options.displayField` —
+ * `QueryRuntimeController.java:1214-1226` reads
+ * `bizPropertyModel3.getRelativePropertyCode()` and falls back to `"name"`
+ * (the target's data title) when it is empty. The designer writes the
+ * top-level key explicitly; `BizPropertyController` create/update (:851/:987)
+ * never auto-fills it. Every relation create/update must therefore carry it.
+ */
+export function relationDisplayFieldCode(type, options) {
+    if (type !== FIELD_PROPERTY_TYPES.WORK_SHEET && type !== FIELD_PROPERTY_TYPES.MULT_WORK_SHEET)
+        return undefined;
+    const displayField = options.displayField;
+    return typeof displayField === "string" && displayField.trim() ? displayField.trim() : undefined;
+}
+export const choicesArg = z.array(z.string()).optional().describe('allowed values for text-choice families (RADIO / CHECKBOX / DROPDOWN_BOX / DROPDOWN_MULTI_BOX), e.g. ["正常","异常","待复检"]。注意：SELECTION(5) 是人员/部门混合选择器，不接受 choices，文本单选请用 DROPDOWN_BOX/RADIO');
+function jsonString() {
+    return z.string().refine((value) => {
+        if (value === "")
+            return true;
+        try {
+            JSON.parse(value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, "must be valid JSON");
+}
+export const dictionaryOptionsArg = z.object({
+    // Live 2026-09-24 (bench34): the platform resolves this as the `dicId` of
+    // `data_dictionary/getEnableRecordsByDictionaryId`, and the designer's
+    // a-select option value is the dictionary **id** — NOT its name. Writing the
+    // name makes the runtime answer "该字典已被禁用，无数据返回" and the dropdown
+    // renders EMPTY (while storage readback looks fine).
+    checkedDictionary: z.string().min(1).describe("字典 **id**（不是 name；取 dictionary.names 的 id）。填 name 会让运行时下拉空白"),
+    checkedDictionaryCode: z.string().min(1).describe("字典 code（dictionary.names 的 code）"),
+    valueText: z.string().optional(),
+    dictionariesType: z.number().int().optional(),
+    useDictionariesData: z.array(z.object({ code: z.string().min(1), name: z.string().optional(), id: z.string().optional() }).passthrough()).optional(),
+}).passthrough();
+export const businessModelOptionsArg = z.object({
+    schemaCode: z.string().min(1),
+    sheetDataItem: z.string().min(1),
+    modelName: z.string().optional(),
+    dataItemType: z.number().int().optional(),
+    orderByFields: z.union([z.string(), z.array(z.string())]).optional().describe("下拉项排序字段，只支持**一个字段名**。传数组会触发运行时 10009（平台把它包成单元素数组 → 嵌套数组）；CLI 会把 1 元素数组规范化为字符串"),
+    orderType: z.number().int().optional(),
+    conditions: z.array(z.record(z.string(), z.unknown())).optional(),
+}).passthrough();
+export const optionsSetArg = z.object({
+    optionsType: z.enum(["custom", "dictionary", "businessModel"]),
+    dictionary: dictionaryOptionsArg.optional(),
+    businessModel: businessModelOptionsArg.optional(),
+    custom: z.array(z.record(z.string(), z.unknown())).optional(),
+}).passthrough().superRefine((value, ctx) => {
+    if (value.optionsType === "dictionary" && !value.dictionary)
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "dictionary source requires optionsSet.dictionary" });
+    if (value.optionsType === "businessModel" && !value.businessModel)
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "businessModel source requires optionsSet.businessModel" });
+    if (value.optionsType === "custom" && !value.custom)
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "custom source requires optionsSet.custom" });
+});
+export const relationFilterArg = z.object({
+    searchFormula: jsonString().optional().describe("JSON string for data restriction range"),
+    conditions: jsonString().optional().describe("JSON string for relation query conditions"),
+}).passthrough();
+/**
+ * CHILD_TABLE(8) child columns. A child table is one field on the main model
+ * whose definition is `subSchema.properties`; each child column is a scalar
+ * field (the child's own `schemaCode` is the parent field code, sortKey is the
+ * array order). Nested CHILD_TABLE and relation/formula/relevance families are
+ * excluded (omc-core `childtable-field-contract.ts` exclusions).
+ */
+export const subFieldArg = z
+    .array(z.object({
+    code: z.string().min(1),
+    name: z.string().min(1),
+    propertyType: z.string().min(1).describe("child family (CHILD_TABLE, OCR, ELECTRONIC_SIGN, MULT_WORK_SHEET, RELEVANCE_DATA and FORMULA are refused; WORK_SHEET is allowed with relativeCode+options)"),
+    choices: z.array(z.string()).optional().describe("child text-choice families (RADIO / CHECKBOX / DROPDOWN_BOX / DROPDOWN_MULTI_BOX) allowed values"),
+    relativeCode: z.string().min(1).optional().describe("WORK_SHEET child column: the target model schemaCode (e.g. customer)"),
+    options: z.record(z.string(), z.unknown()).optional().describe("WORK_SHEET child column: relation display options { schemaCode, queryCode, displayField, mappings, ... }"),
+    propertyEmpty: z.boolean().optional().describe("child column 是否不可为空；默认 false（可为空）"),
+}))
+    .optional()
+    .describe("CHILD_TABLE(8) required: the child columns, in display order; each becomes a subSchema property (schemaCode=父字段 code, sortKey=数组位+1)");
+/**
+ * Field options. The shape depends on `propertyType`:
+ * - relation families WORK_SHEET(9) / MULT_WORK_SHEET(11):
+ *   { schemaCode:<target model>, queryCode:<target model>, displayField:"name",
+ *     mappings:'[{"source":<target field code>,"target":<this-model field code>}]' }
+ * - RELEVANCE_DATA(16) — a *reference to another field*, NOT a model relation
+ *   (8.6.26 `RelevanceDataOptions`, admin field serializer):
+ *   { relevanceField:<local WORK_SHEET field code>,
+ *     referenceField:<target field code on the related model>,
+ *     referenceFieldPropertyType:<int BizPropertyType>,
+ *     referenceFieldControlType?:<int BizFormPropertyType> }
+ * - FORMULA: the standalone 「计算公式」 field family (platform type 89). **NOT the
+ *   default for calculation requirements** — the platform convention is a NORMAL
+ *   business field (数值 / 单行文本 …) with a separate 「计算规则」 (field-level
+ *   data rule, `datarule.create` dataRuleType 2). Prefer that; use FORMULA(计算
+ *   公式) only when the requirement explicitly wants a dedicated formula column.
+ *   The old text labelled this family "FORMULA(100)": 100 is actually 单据号
+ *   (serial number); the OMC-family name maps to the platform's 计算公式 face.
+ *   { formulaConfig:"<nested JSON string>", persistent:true }
+ *   where formulaConfig = { resultType:0|2, resultFormat:""|"percentile", formulaType:"EXPRESSION",
+ *   expression:"<JSON string {formula,editorText,editorMark}>" }. resultFormat "percentile"
+ *   is evidenced on fwb readback together with an outer readback-only `format` mirror key
+ *   (field-families-fwb-20260914.md §100); unknown resultFormat values are refused
+ *   fail-closed. AGGREGATION is structurally valid but blocked (condition-group
+ *   semantics not contract-grade).
+ *   The old top-level { resultType, expression } keys are NOT read by the platform and are refused.
+ * - selection families: omit options and pass `choices` instead.
+ * Any other keys pass through. `nested:true` / `relationLinkage:true` are refused
+ * (coverage boundary).
+ */
+export const fieldOptionsArg = z
+    .object({
+    schemaCode: z.string().optional().describe("relation target model code (WORK_SHEET / MULT_WORK_SHEET)"),
+    queryCode: z.string().optional().describe("relation query code (usually the target model code)"),
+    displayField: z.string().optional().describe("relation display field (usually 'name')"),
+    mappings: z.string().optional().describe('relation carry mappings, e.g. [{"source":"<target field code>","target":"<this-model field code>"}]'),
+    searchFormula: jsonString().optional().describe("WORK_SHEET / MULT_WORK_SHEET data restriction range JSON"),
+    conditions: jsonString().optional().describe("WORK_SHEET / MULT_WORK_SHEET query conditions JSON"),
+    optionsSet: optionsSetArg.optional().describe("selection source: custom, dictionary, or businessModel"),
+    formulaConfig: z.string().optional().describe('FORMULA(计算公式)字段 required: nested JSON string. **计算类需求默认不要建本字段类型**，改用普通字段(数值/单行文本)+计算规则(datarule.create dataRuleType 2, 裸 {字段} 引用)。本字段类型用于明确的「计算公式」列。形状 {"resultType":0|2,"resultFormat":""|"percentile","formulaType":"EXPRESSION","expression":"<JSON string {formula,editorText,editorMark}>"}；计算由门户前端执行、API 不回填。'),
+    persistent: z.boolean().optional().describe("FORMULA(100): must be true; persistent=false is outside the evidenced contract"),
+    relevanceField: z.string().optional().describe("RELEVANCE_DATA(16) required: local WORK_SHEET field code the reference resolves through"),
+    referenceField: z.string().optional().describe("RELEVANCE_DATA(16) required: referenced field code on the related model"),
+    referenceFieldPropertyType: z.number().int().optional().describe("RELEVANCE_DATA(16) required: referenced field propertyType (BizPropertyType int)"),
+    referenceFieldControlType: z.number().int().optional().describe("RELEVANCE_DATA(16): referenced field control type (BizFormPropertyType int)"),
+    nested: z.boolean().optional().describe("nested child-table metadata — refused (coverage boundary)"),
+    relationLinkage: z.boolean().optional().describe("advanced relation linkage — refused (coverage boundary)"),
+})
+    .passthrough();
+/** Live-accepted field families: wire propertyType is an int enum. */
+export const FIELD_PROPERTY_TYPES = {
+    SHORT_TEXT: 0,
+    LONG_TEXT: 1,
+    NUMERICAL: 2,
+    DATE: 3,
+    LOGICAL: 4,
+    SELECTION: 5,
+    ATTACHMENT: 6,
+    CHILD_TABLE: 8,
+    WORK_SHEET: 9,
+    ADDRESS: 10,
+    MULT_WORK_SHEET: 11,
+    RADIO: 12,
+    CHECKBOX: 13,
+    DROPDOWN_BOX: 14,
+    DROPDOWN_MULTI_BOX: 15,
+    RELEVANCE_DATA: 16,
+    HYPER_LINK: 17,
+    TIME: 28,
+    STAFF_SELECTOR: 50,
+    STAFF_MULTI_SELECTOR: 51,
+    DEPARTMENT_SELECTOR: 60,
+    DEPARTMENT_MULTI_SELECTOR: 61,
+    FORMULA: 100,
+};
+export const OUT_OF_COVERAGE_FIELD_TYPES = {
+    OCR: "boundary-unsupported (OCR and ELECTRONIC_SIGN field families)",
+    ELECTRONIC_SIGN: "boundary-unsupported (OCR and ELECTRONIC_SIGN field families)",
+};
+/** Reverse lookup: wire propertyType int -> family name (for messages). */
+export function familyName(type) {
+    return Object.entries(FIELD_PROPERTY_TYPES).find(([, value]) => value === type)?.[0] ?? `wire:${type}`;
+}
+/**
+ * Read-face type label (round 13): the wire carries `propertyType` as an int
+ * (0=SHORT_TEXT, 2=NUMERICAL, 50=STAFF_SELECTOR, …). A bare int forces the
+ * caller to decode it or pay a ~19 KB `describe field.create --full` to learn
+ * the enum. This returns the family name for a numeric wire value (or passes a
+ * string through), so a field read is self-describing at ~11 B/field.
+ */
+export function fieldTypeLabel(raw) {
+    if (typeof raw === "number" && Number.isFinite(raw))
+        return familyName(raw);
+    if (typeof raw === "string" && raw.length > 0)
+        return raw in FIELD_PROPERTY_TYPES ? raw : (Number.isFinite(Number(raw)) ? familyName(Number(raw)) : raw);
+    return undefined;
+}
+/**
+ * Chinese concept synonym → family, so a caller who names the concept instead of
+ * the enum ("关联引用" for a model relation, "明细" for a child table) gets a
+ * "did you mean" hint instead of a bare out-of-coverage refusal. Bench18: an
+ * agent picking RELEVANCE_DATA for a model relation cost a wasted write.
+ */
+export const FIELD_TYPE_SYNONYMS = Object.freeze({
+    关联: "WORK_SHEET(9)（单条；多条用 MULT_WORK_SHEET(11)）",
+    关联引用: "WORK_SHEET(9)（引用另一模型的一条记录）——注意 RELEVANCE_DATA(16) 是引用本模型已有关联字段里的某个字段，不是模型关联",
+    引用: "WORK_SHEET(9) / MULT_WORK_SHEET(11)",
+    明细: "CHILD_TABLE(8)（子表）",
+    子表: "CHILD_TABLE(8)",
+    金额: "NUMERICAL(2)（+ options.scale 小数位数）",
+    数值: "NUMERICAL(2)",
+    编号: "SHORT_TEXT(0)",
+    文本: "SHORT_TEXT(0) / LONG_TEXT(1)",
+    单选: "RADIO(12) / DROPDOWN_BOX(14)（字典来源）",
+    多选: "CHECKBOX(13) / DROPDOWN_MULTI_BOX(15)",
+    下拉: "DROPDOWN_BOX(14)（字典）",
+    日期: "DATE(3)",
+    时间: "TIME(28)",
+    附件: "ATTACHMENT(6)",
+    人员: "STAFF_SELECTOR(50) / STAFF_MULTI_SELECTOR(51)",
+    部门: "DEPARTMENT_SELECTOR(60) / DEPARTMENT_MULTI_SELECTOR(61)",
+    是或否: "LOGICAL(4)",
+    布尔: "LOGICAL(4)",
+});
+/** A "did you mean" hint for a family name that is actually a Chinese concept. */
+export function fieldTypeHint(type) {
+    for (const [concept, family] of Object.entries(FIELD_TYPE_SYNONYMS))
+        if (type.includes(concept) || concept.includes(type))
+            return `「${type}」看起来是概念名而非族名；最接近的是 ${family}`;
+    return undefined;
+}
+/** wire propertyType (int) -> form controlType (type-matrix.md §3.1). */
+export const FIELD_CONTROL_TYPES = { ...CAPABILITY_CONTROL_TYPES };
+export const SYSTEM_FIELD_CODES = new Set([
+    "owner",
+    "creater",
+    "createdTime",
+    "modifiedTime",
+    "modifier",
+    "sequenceNo",
+    "sequenceStatus",
+    "id",
+    "name",
+    "ownerDeptId",
+    "ownerDeptQueryCode",
+    "createdDeptId",
+    "workflowInstanceId",
+]);
+const RELEVANCE_CONTROL_KEYS = ["relevanceField", "referenceField", "referenceFieldPropertyType", "referenceFieldControlType", "originalOptions", "format1"];
+function pickRelevanceControlOptions(fieldOptions) {
+    const picked = {};
+    for (const key of RELEVANCE_CONTROL_KEYS)
+        if (fieldOptions?.[key] !== undefined)
+            picked[key] = fieldOptions[key];
+    return picked;
+}
+/**
+ * Ticket 69 — designer-default options for the org-selection controls
+ * (50/51/60/61/62). `deptVisible` + `multi` are the platform's person /
+ * department / mixed discriminator; the rest mirror the designer's
+ * `buildControlOptions` defaults observed in the admin bundle.
+ */
+function orgSelectorControlOptions(base, deptVisible, multi) {
+    return {
+        ...base,
+        dataItemName: "",
+        widgetType: "",
+        dataItemType: "",
+        multi,
+        deptVisible,
+        defaultValue: [],
+        defaultValueType: "",
+        orgRoot: [],
+        orgRootValueType: "",
+        recursive: true,
+        isDisplayRoot: true,
+        roles: "",
+        mappings: "",
+        displayType: "tag",
+        dataLinkage: "",
+        readonlyCondition: "",
+        selectMode: "popup",
+        verifyFormula: "",
+        noRepeat: "",
+        ...(deptVisible === "user" ? {} : { departmentLevels: {}, limitDeptSelectionRanges: [] }),
+    };
+}
+/**
+ * The numeric FORM CONTROL's `format`/`format1` display string.
+ *
+ * Live correction 2026-09-23 (admin designer bundle `Number.format` options):
+ * the numeric control does NOT accept `"decimal"` — the field-level word — it
+ * takes a display-format constant: none / integer / tenths / percentile /
+ * Millimeter / tenThousand / hundredThousand / millionDecimals /
+ * tenMillionDecimals / billionDecimals, optionally prefixed `ratio.` (percent),
+ * `RMB.` / `dollar.` / `euro.` / `HK.` (currency). Writing `"decimal"` (the
+ * previous behaviour) left the control with an unrecognised format, so the
+ * portal rendered the raw decimal. Derive the constant from the field's
+ * `scale` (0-based decimal places) and `format` family.
+ */
+const NUMERICAL_DECIMALS_FORMAT = Object.freeze({
+    0: "integer",
+    1: "tenths",
+    2: "percentile",
+    3: "Millimeter",
+    4: "tenThousand",
+    5: "hundredThousand",
+    6: "millionDecimals",
+    7: "tenMillionDecimals",
+    8: "billionDecimals",
+});
+function numericalFormatPrefix(format) {
+    const value = String(format ?? "").toLowerCase();
+    if (value === "currency" || value === "rmb" || value === "¥")
+        return "RMB.";
+    if (value === "dollar" || value === "$")
+        return "dollar.";
+    if (value === "euro" || value === "€")
+        return "euro.";
+    if (value === "hk" || value === "hkd" || value === "hk$")
+        return "HK.";
+    if (value === "percent" || value === "percentage" || value === "ratio")
+        return "ratio.";
+    return "";
+}
+export function numericalControlFormat(fieldOptions) {
+    const scale = fieldOptions?.scale;
+    const decimals = isNumericalScale(scale) ? scale : 2;
+    return `${numericalFormatPrefix(fieldOptions?.format)}${NUMERICAL_DECIMALS_FORMAT[decimals]}`;
+}
+export function fieldControlOptions(type, name, relativeCode, relationMappings, relationDisplayField = "name", fieldOptions) {
+    const base = { name, name_i18n: { "zh-CN": name, en: name }, visible: true, labelVisible: true, span: 24 };
+    const declared = deriveControlOptions(type, fieldOptions);
+    const merged = { ...base, ...declared };
+    switch (type) {
+        // The numeric control carries a display-format constant (not the field
+        // word "decimal"); derive it from scale + family. See numericalControlFormat.
+        case 2: return { ...merged, format: numericalControlFormat(fieldOptions), format1: numericalControlFormat(fieldOptions) };
+        // No mapping -> the designer's BLANK sentinel "" (its "选择业务模型" handler
+        // writes mappings:""). A stringified "[]" is non-empty, so the control
+        // editor's `setted` badge (isNotEmpty) renders 已设置/Set while the modal it
+        // opens is empty — the 2026-09-18 report. Only a real mapping is non-blank.
+        case 9:
+        case 11: return { ...merged, schemaCode: relativeCode ?? "", displayField: relationDisplayField, relativePropertyMatchCode: relationDisplayField, queryCode: relativeCode ?? "", mappings: relationMappings ?? "", ...(typeof fieldOptions?.searchFormula === "string" ? { searchFormula: fieldOptions.searchFormula } : {}), ...(typeof fieldOptions?.conditions === "string" ? { conditions: fieldOptions.conditions } : {}) };
+        case 50: return orgSelectorControlOptions({ ...base, ...deriveControlOptions(type) }, "user", "false");
+        case 51: return orgSelectorControlOptions({ ...base, ...deriveControlOptions(type) }, "user", "true");
+        case 60: return orgSelectorControlOptions({ ...base, ...deriveControlOptions(type) }, "org", "false");
+        case 61: return orgSelectorControlOptions({ ...base, ...deriveControlOptions(type) }, "org", "true");
+        case 5: return { ...merged, ...(fieldOptions?.optionsSet ? { optionsSet: fieldOptions.optionsSet } : {}), ...orgSelectorControlOptions({ ...base, ...deriveControlOptions(type) }, "all", "true") };
+        case 12:
+        case 13:
+        case 14:
+        case 15: return { ...merged, ...(fieldOptions?.optionsSet ? { optionsSet: fieldOptions.optionsSet } : {}) };
+        case 16: return { ...merged, ...pickRelevanceControlOptions(fieldOptions) };
+        case 100: return { ...merged, ...(typeof fieldOptions?.formulaConfig === "string" ? { formulaConfig: fieldOptions.formulaConfig, persistent: fieldOptions.persistent === true } : {}) };
+        default: return merged;
+    }
+}
+/** relation options face decode; policy: string-or-object accepted, garbage → undefined. */
+function relationOptions(options) {
+    return decodeJsonObjectColumn(options, { invalid: "undefined", array: "accept", object: "accept" });
+}
+/**
+ * The relation target model of a bizproperty row. Relation families
+ * (WORK_SHEET / MULT_WORK_SHEET) carry the target model code both as the
+ * row-level `relativeCode` and as the `schemaCode` key inside the options JSON
+ * (field.create writes both). RELEVANCE_DATA(16) is deliberately excluded: it
+ * references another *field* (relevanceField/referenceField), not a model, so
+ * it adds no inbound model reference of its own — the local WORK_SHEET field it
+ * resolves through already carries that reference. Either face counts as an
+ * inbound reference for the model.delete precheck (ticket 23: the server's
+ * deleteFunctions dispatcher refuses asynchronously with
+ * "xxx被模型 yyy 引用,不能删除" — the tool surfaces that check at call time).
+ */
+export function relationTargetOf(row) {
+    if (typeof row.relativeCode === "string" && row.relativeCode.trim())
+        return row.relativeCode.trim();
+    const schemaCode = relationOptions(row.options)?.schemaCode;
+    return typeof schemaCode === "string" && schemaCode.trim() ? schemaCode.trim() : undefined;
+}
+export function relationDisplayField(options) {
+    const displayField = relationOptions(options)?.displayField;
+    return typeof displayField === "string" && displayField.trim() ? displayField.trim() : undefined;
+}
+/** Extract a non-empty relation `mappings` JSON string from a field's options. */
+export function relationMappings(options) {
+    const mappings = relationOptions(options)?.mappings;
+    if (typeof mappings !== "string")
+        return undefined;
+    const trimmed = mappings.trim();
+    if (trimmed === "" || trimmed === "[]")
+        return undefined;
+    return trimmed;
+}
+/**
+ * Designer-standard default field options by family. Only families with
+ * live evidence get a shape beyond the bare `{dictionaryData:""}` — DATE(3)
+ * requires `format` or the first runtime save 50000s
+ * (BizObjectFacadeImpl.java:2949 reads options.format). TIME(28) has no
+ * evidence yet and stays on the bare default.
+ */
+export function familyDefaultFieldOptions(raw) {
+    const type = typeof raw === "number" && Number.isInteger(raw)
+        ? raw
+        : typeof raw === "string" && raw in FIELD_PROPERTY_TYPES
+            ? FIELD_PROPERTY_TYPES[raw]
+            : undefined;
+    if (type === FIELD_PROPERTY_TYPES.DATE)
+        return { ...FIELD_DATE_DEFAULT_OPTIONS };
+    return undefined;
+}
+/**
+ * Live 2026-09-24 (bench34): the businessModel dropdown's runtime builds its
+ * sort as `[optionsSet.businessModel.orderByFields]` (frontend 19497), i.e. it
+ * wraps a SINGLE value. A stored ARRAY therefore becomes a nested array and
+ * `runtime/query/listSkipQueryListV2` answers `10009 Type conversion error`,
+ * leaving the dropdown empty. Only one sort field is supported, so normalize a
+ * 1-element array to its string element; refuse anything else.
+ */
+function normalizeBusinessModelOrderBy(options) {
+    const optionsSet = options.optionsSet;
+    const businessModel = optionsSet?.businessModel;
+    if (!businessModel)
+        return;
+    normalizeBusinessModelCondition(businessModel);
+    if (businessModel.orderByFields === undefined)
+        return;
+    const value = businessModel.orderByFields;
+    if (typeof value === "string")
+        return;
+    if (Array.isArray(value) && value.length === 1 && typeof value[0] === "string" && value[0].trim() !== "") {
+        businessModel.orderByFields = value[0];
+        return;
+    }
+    refuseFieldOptions("optionsSet.businessModel.orderByFields 必须是单个字段名字符串", `rejected: orderByFields=${JSON.stringify(value)}；平台运行时把它包成单元素数组，数组会变成嵌套数组并触发 10009，下拉为空；只支持一个排序字段`);
+}
+/**
+ * Live 2026-09-24 (bench34): the businessModel dropdown's runtime reads a
+ * SINGULAR `condition` STRING (frontend 19497 parseHistoryConditions), not the
+ * `conditions` array this CLI used to document — with only `conditions` the
+ * dropdown query ships `queryCondition: []` (no filtering at all, silently).
+ * The runtime string grammar, verified live:
+ *   - `field === literal`  → FIXED (compare to the literal value)
+ *   - `field == otherField` → DYNAMIC (compare to another control's value)
+ *   conditions joined by ` && `.
+ * Translate the caller's `{field, operator, value|valueFrom}` array into it and
+ * expose it as `condition` (keeping `conditions` as the human-readable source).
+ */
+function normalizeBusinessModelCondition(businessModel) {
+    if (typeof businessModel.condition === "string" && businessModel.condition.trim() !== "")
+        return;
+    const conditions = businessModel.conditions;
+    if (!Array.isArray(conditions) || conditions.length === 0)
+        return;
+    const parts = [];
+    for (const entry of conditions) {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            continue;
+        const record = entry;
+        const field = typeof record.field === "string" ? record.field.trim() : "";
+        if (!field)
+            continue;
+        if (typeof record.valueFrom === "string" && record.valueFrom.trim() !== "")
+            parts.push(`${field} == ${record.valueFrom.trim()}`);
+        else if (record.value !== undefined && record.value !== null)
+            parts.push(`${field} === ${String(record.value)}`);
+    }
+    // Join WITHOUT spaces: the form renderer's subscription parser
+    // (portal 30079) does `condition.split("&&").map(e => e.split(" ")[2])`
+    // WITHOUT trimming, so a leading space on a non-first segment shifts the
+    // indices and it reads `undefined.split` → a load-time console error. The
+    // query parser trims, so the spacer-free join is safe for both.
+    if (parts.length > 0)
+        businessModel.condition = parts.join("&&");
+}
+export function buildFieldOptions(args) {
+    const explicit = args.options;
+    const raw = args.propertyType;
+    const type = typeof raw === "number" && Number.isInteger(raw)
+        ? raw
+        : typeof raw === "string" && raw in FIELD_PROPERTY_TYPES
+            ? FIELD_PROPERTY_TYPES[raw]
+            : undefined;
+    if (explicit) {
+        if (type !== undefined) {
+            const shapeError = capabilityShapeError(type, "field", explicit);
+            if (shapeError)
+                refuseFieldOptions(shapeError, `rejected: ${shapeError}`);
+            const choiceError = choiceOptionsError(type, explicit);
+            if (choiceError)
+                refuseFieldOptions("selection field options carry no optionsSet source", `rejected: ${choiceError}`);
+        }
+        normalizeBusinessModelOrderBy(explicit);
+        return explicit;
+    }
+    const choices = args.choices;
+    if (Array.isArray(choices) && choices.length > 0) {
+        // CHOICE_PROPERTY_TYPES is the text-choice set (RADIO/CHECKBOX/DROPDOWN_BOX/
+        // DROPDOWN_MULTI_BOX). SELECTION(5) is the MIXED people/department selector
+        // (control type 62) and requires an org-unit array at runtime; writing
+        // `choices` to it persisted an optionsSet the runtime ignored, then
+        // data.save threw IllegalStateException @ OrgUnitArrayBizField.contentFromClient
+        // (live 8.6.26, 2026-09-27). Refuse instead of producing an unstorable field.
+        if (type !== undefined && !CHOICE_PROPERTY_TYPES.has(type))
+            refuseFieldOptions(`propertyType ${familyName(type)}(${type}) does not accept choices`, `propertyType ${familyName(type)}(${type}) 不接受 choices：它是人员/组织/混合选择器或非选项族，运行时按组织对象存取。文本单选用 RADIO(12)/DROPDOWN_BOX(14)，多选用 CHECKBOX(13)/DROPDOWN_MULTI_BOX(15)；人员/部门/混合选择器用 STAFF_SELECTOR/DEPARTMENT_SELECTOR/SELECTION 且不要带 choices`);
+        // Ticket 108: no dictionaryData on selection rows — designer-produced
+        // rows carry none (fwb §12-15) and the platform only accepts the extra
+        // key, never requires it (live 8.6.26 write+read 2026-09-15).
+        const selection = {
+            optionsSet: {
+                optionsType: "custom",
+                custom: choices.map((value) => ({
+                    code: value,
+                    value,
+                    name_i18n: { "zh-CN": value, en: value },
+                    published: false,
+                })),
+                dictionary: {},
+                businessModel: { orderType: 1 },
+            },
+        };
+        return type !== undefined ? deriveFieldOptions(type, selection) : selection;
+    }
+    return type !== undefined ? deriveFieldOptions(type) : { dictionaryData: "" };
+}
+export function normalizeFieldPropertyType(args) {
+    const raw = args.propertyType;
+    if (typeof raw === "number" && Number.isInteger(raw)) {
+        if (!Object.values(FIELD_PROPERTY_TYPES).includes(raw))
+            throw new ToolRefusalError({ status: "refused", blocker: "capability-out-of-coverage", citation: { code: "capability-out-of-coverage", lane: "field-families", capability: "field family full chain", status: "partial", reason: `propertyType ${raw} is not a live-accepted family`, message: `rejected: propertyType ${raw} is outside the live-accepted field families; citing lane field-families` } });
+        return raw;
+    }
+    const type = String(raw ?? "");
+    if (!(type in FIELD_PROPERTY_TYPES)) {
+        const hint = fieldTypeHint(type);
+        throw new ToolRefusalError({
+            status: "refused",
+            blocker: "capability-out-of-coverage",
+            citation: { code: "capability-out-of-coverage", lane: "field-families", capability: "field family full chain", status: "partial", reason: `${type || "missing"} is not a live-accepted family`, message: `rejected: field family ${type || "(missing)"} is outside the live-accepted set; citing lane field-families` },
+            ...(hint ? { hint } : {}),
+            message: `propertyType「${type || "(missing)"}」不是可用的字段族名。${hint ?? ""} 可用族名：${Object.keys(FIELD_PROPERTY_TYPES).join("、")}`,
+        });
+    }
+    return FIELD_PROPERTY_TYPES[type];
+}
+/**
+ * Families a CHILD_TABLE(8) column may carry (omc-core
+ * `childtable-field-contract.ts` CONTROL_TYPES allow-list). PRODUCTIVE
+ * `WORK_SHEET(9)` is included: live 2026-09-20, a `WORK_SHEET` child column with
+ * `relativeCode` + relation options is accepted by create/publish AND resolves
+ * the relation on runtime readback. Excluded (each with live evidence in the
+ * core contract): nested CHILD_TABLE, MULT_WORK_SHEET, RELEVANCE_DATA, FORMULA,
+ * and the OCR/ELECTRONIC_SIGN boundary families.
+ */
+export const CHILD_TABLE_SCALAR_PROPERTY_TYPES = new Set([0, 1, 2, 3, 4, 5, 6, 9, 10, 12, 13, 14, 15, 17, 28, 50, 51, 60, 61]);
+/**
+ * Build the `subSchema` that defines a CHILD_TABLE(8) field from `subFields`.
+ * Live shape (2026-09-08 `childtable-execute-20260908070635135.md`):
+ * `{ code:<parent field code>, properties:[{code,name,schemaCode:<parent field
+ * code>,propertyType,propertyEmpty,sortKey}] }`. The child's `schemaCode` is
+ * the parent field code, not the main model.
+ */
+export function buildChildTableSubSchema(args) {
+    const subs = args.subFields;
+    if (!Array.isArray(subs) || subs.length === 0)
+        refuseFieldOptions("CHILD_TABLE subFields is missing or empty", "rejected: CHILD_TABLE(8) requires subFields（至少 1 个子字段），每项 { code, name, propertyType[, propertyEmpty] }");
+    const parentCode = String(args.code ?? "");
+    const properties = subs.map((sub, index) => buildChildTableProperty(parentCode, sub, index));
+    return { code: parentCode, properties };
+}
+/** One CHILD_TABLE(8) column row (compact create shape). */
+export function buildChildTableProperty(parentCode, sub, index) {
+    const type = normalizeFieldPropertyType(sub);
+    if (!CHILD_TABLE_SCALAR_PROPERTY_TYPES.has(type))
+        refuseFieldOptions(`CHILD_TABLE child ${String(sub.code)} has out-of-coverage propertyType ${type}`, `rejected: 子表列只接受 ${[...CHILD_TABLE_SCALAR_PROPERTY_TYPES].join("/")}；CHILD_TABLE/MULT_WORK_SHEET/RELEVANCE_DATA/FORMULA/OCR/ELECTRONIC_SIGN 不在子表覆盖内（omc-core childtable-field-contract.ts）`);
+    const name = String(sub.name ?? "");
+    const relation = type === FIELD_PROPERTY_TYPES.WORK_SHEET;
+    if (relation && !String(sub.relativeCode ?? "").trim())
+        refuseFieldOptions(`CHILD_TABLE WORK_SHEET column ${String(sub.code)} requires relativeCode`, "rejected: 子表关联列必须给 relativeCode（目标模型 schemaCode，如 customer）");
+    const options = buildFieldOptions(sub);
+    assertNumericalScale(type, options);
+    if (relation) {
+        const shapeError = capabilityShapeError(type, "field", options);
+        if (shapeError)
+            refuseFieldOptions(shapeError, `rejected: ${shapeError}`);
+    }
+    const derived = deriveFieldOptions(type, relation ? ensureRelationDisplayFieldOptions(type, options) : options);
+    const displayCode = relation ? relationDisplayFieldCode(type, derived) : undefined;
+    return {
+        code: String(sub.code ?? ""),
+        name,
+        name_i18n: nameI18nJson(name),
+        schemaCode: parentCode,
+        propertyType: type,
+        propertyEmpty: sub.propertyEmpty === true,
+        ...(relation ? { relativeCode: String(sub.relativeCode).trim() } : {}),
+        ...(displayCode ? { relativePropertyCode: displayCode } : {}),
+        sortKey: index + 1,
+        options: JSON.stringify(derived),
+        defaultProperty: false,
+        published: false,
+    };
+}
+export function assertFieldFamilyAllowed(args) {
+    const type = String(args.propertyType ?? "");
+    if (OUT_OF_COVERAGE_FIELD_TYPES[type]) {
+        const citation = {
+            code: "capability-out-of-coverage",
+            lane: "boundary-unsupported",
+            capability: OUT_OF_COVERAGE_FIELD_TYPES[type],
+            status: "unsupported",
+            reason: `${type} field family is explicitly unsupported in the M1 coverage manifest`,
+            message: `rejected: ${type} fields are unsupported (coverage manifest boundary-unsupported); citing lane boundary-unsupported`,
+        };
+        throw new ToolRefusalError({ status: "refused", blocker: "capability-out-of-coverage", citation });
+    }
+    // Validate the family against the allow-list BEFORE the write permission gate so an
+    // unsupported type is refused up front instead of after a token is issued
+    // (previously the allow-list check lived in execute(), i.e. post-approval).
+    const normalized = normalizeFieldPropertyType(args);
+    const options = args.options;
+    if (options && (options.nested === true || options.relationLinkage === true)) {
+        const citation = {
+            code: "capability-out-of-coverage",
+            lane: "W6-S27-advanced-childtable",
+            capability: "W6 S27 nested child-table metadata",
+            status: "blocked",
+            reason: "design face refused nested CHILD_TABLE with 50000; no recursive payload contract exists",
+            message: "rejected: nested child-table configuration is blocked (W6-S27-advanced-childtable); citing coverage manifest entry",
+        };
+        throw new ToolRefusalError({ status: "refused", blocker: "capability-out-of-coverage", citation });
+    }
+    // CHILD_TABLE(8): the field row carries no `options`; its definition is the
+    // subSchema built from subFields. Validate that shape here (pre-write)
+    // instead of running the options-face gate.
+    if (normalized === FIELD_PROPERTY_TYPES.CHILD_TABLE) {
+        buildChildTableSubSchema(args);
+        return;
+    }
+    assertFieldOptionsAllowed(normalized, options);
+}
+function refuseFieldOptions(reason, message) {
+    const citation = {
+        code: "capability-out-of-coverage",
+        lane: "field-families",
+        capability: "field family full chain",
+        status: "blocked",
+        reason,
+        message,
+    };
+    throw new ToolRefusalError({ status: "refused", blocker: "capability-out-of-coverage", citation });
+}
+/** FORMULA formulaConfig decode; policy: string-only face, must parse to a non-array object. */
+function parseOptionsObject(value) {
+    return decodeJsonObjectColumn(value, { invalid: "undefined", array: "reject", object: "reject" });
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/**
+ * The formula expression body inside a FORMULA formulaConfig.expression value.
+ * `expression` is itself a JSON string `{formula,editorText,editorMark}`; fall
+ * back to the raw string when it does not parse, so the lint still sees a
+ * malformed-but-present body.
+ */
+function expressionBody(expression) {
+    const parsed = parseOptionsObject(expression);
+    const formula = parsed?.formula;
+    return typeof formula === "string" ? formula : expression;
+}
+/**
+ * Fail-closed options validation for families whose keys the platform reads
+ * strictly. FORMULA(100) and RELEVANCE_DATA(16) were previously written with
+ * keys the platform does not read (resultType/expression, relation schemaCode/
+ * mappings); this refuses such payloads before the write permission gate instead of
+ * persisting an ineffective field. Called for field.create pre-write and for
+ * field.update after the target family is read from the existing record.
+ */
+/**
+ * Round 4 (ADR 0005): NUMERICAL fields require an explicit `options.scale`.
+ * Live correction 2026-09-23 (designer bundle + live round-trip): the field
+ * `scale` is a 0-based DECIMAL-PLACES index — scale 0 = integer, 1 = 1dp,
+ * 2 = 2dp, … 8 = 8dp. `listview.configure` then maps it through the platform's
+ * `QueryRuntimeController.parseNumber` table ({0:1,1:2,2:3,3:11,4:12,23:…}),
+ * verified live: scale 2 -> displayFormat 3 (2dp), scale 3 -> displayFormat 11
+ * (3dp). The earlier enum reading (1=整数,2=1位,3=2位) was the displayFormat
+ * enum misread as scale and produced 3-decimal "two-decimal" amounts. The gate
+ * accepts 0..8 and tells the caller to count decimal places.
+ */
+const NUMERICAL_MAX_DECIMALS = 8;
+/** True when `scale` is a valid 0-based decimal-places index. */
+export function isNumericalScale(scale) {
+    return typeof scale === "number" && Number.isInteger(scale) && scale >= 0 && scale <= NUMERICAL_MAX_DECIMALS;
+}
+export function numericalScaleWarning(type, options) {
+    if (type !== FIELD_PROPERTY_TYPES.NUMERICAL)
+        return undefined;
+    if (options !== null && typeof options === "object" && !Array.isArray(options)) {
+        if (isNumericalScale(options.scale))
+            return undefined;
+    }
+    return "NUMERICAL 字段缺合法 options.scale：门户设计器会显示为裸 decimal（BigDecimal 样式）。scale 是小数位数（0=整数, 1=1位, 2=2位, 3=3位 … 8=8位）——「金额两位小数」用 scale:2，不要照搬列格式枚举";
+}
+export function assertNumericalScale(type, options) {
+    const warning = numericalScaleWarning(type, options);
+    if (warning !== undefined)
+        refuseFieldOptions("NUMERICAL requires an explicit options.scale (verified: absent scale renders as raw decimal in the portal designer)", `rejected: ${warning}`);
+}
+/**
+ * Round 4 (ADR 0005): form-interaction conditions (required/readonly/display)
+ * are FIELD options, reproduced live against the portal form. Validate them
+ * here so a malformed condition is refused at write time instead of breaking
+ * (or silently not enforcing in) the portal form.
+ */
+export function assertFormConditions(options) {
+    if (!options)
+        return;
+    const error = formConditionOptionsError(options);
+    if (error !== null)
+        refuseFieldOptions("field form-condition options fail the reproduced protocol", `rejected: ${error}`);
+}
+/**
+ * Selection families (RADIO/CHECKBOX/DROPDOWN/DROPDOWN_MULTI) render their
+ * choices from `optionsSet` (custom/dictionary/businessModel). The control
+ * derives options from `optionsSet[optionsType]` (frontend 19497), so a field
+ * written with a bare `{items:[{value,label}]}` — or `custom`/`labels`/`options`
+ * without the `optionsSet` wrapper — is silently accepted by the platform but
+ * renders an EMPTY control in the portal (dogfood bench35, 2026-09-24: a radio
+ * with `options.items` showed no choices). Refuse the misleading shape at write
+ * time with a pointer to `choices`/`optionsSet`.
+ */
+const CHOICE_PROPERTY_TYPES = new Set([
+    FIELD_PROPERTY_TYPES.RADIO,
+    FIELD_PROPERTY_TYPES.CHECKBOX,
+    FIELD_PROPERTY_TYPES.DROPDOWN_BOX,
+    FIELD_PROPERTY_TYPES.DROPDOWN_MULTI_BOX,
+]);
+function choiceOptionsError(type, options) {
+    if (!CHOICE_PROPERTY_TYPES.has(type))
+        return null;
+    const optionsSet = options.optionsSet;
+    if (optionsSet !== undefined) {
+        if (optionsSet === null || typeof optionsSet !== "object" || Array.isArray(optionsSet))
+            return "optionsSet 必须是对象（{optionsType:'custom'|'dictionary'|'businessModel', ...}）";
+        const optionsType = optionsSet.optionsType;
+        if (!["custom", "dictionary", "businessModel"].includes(String(optionsType)))
+            return `optionsSet.optionsType「${String(optionsType)}」无效（custom/dictionary/businessModel）`;
+        return null;
+    }
+    // No optionsSet: refuse the shapes that LOOK like choices but the platform ignores.
+    for (const key of ["items", "labels", "custom", "dictionary", "businessModel", "options", "dictionaryData"]) {
+        if (options[key] !== undefined)
+            return `选中控件（单选/复选/下拉）的选项必须放进 optionsSet（{optionsType:'custom',custom:[{code,value,name_i18n}]} 或 dictionary/businessModel）；裸的 options.${key} 平台不消费，门户会渲染成空控件。用 field.create 的 choices 参数，或 options.optionsSet`;
+    }
+    return null;
+}
+export function assertFieldOptionsAllowed(type, options, schemaCode) {
+    if (options) {
+        const shapeError = capabilityShapeError(type, "field", options);
+        if (shapeError)
+            refuseFieldOptions(shapeError, `rejected: ${shapeError}`);
+    }
+    // DATE(3): the runtime compares options.format LITERALLY against a fixed
+    // UPPERCASE enum (DateBizField.contentFromClient → `不支持的format:<v>`).
+    // The shape check above only requires the key to be present, so a Java-style
+    // `yyyy-MM-dd` passes create and then 50000s on the FIRST runtime save
+    // (2026-09-30 R5 live). Refuse any value outside the enum.
+    if (type === FIELD_PROPERTY_TYPES.DATE && options && options.format !== undefined) {
+        if (!FIELD_DATE_FORMATS.includes(String(options.format)))
+            refuseFieldOptions(`DATE options.format ${JSON.stringify(options.format)} 不是平台支持的格式`, `rejected: DATE(3) options.format 必须是平台枚举（区分大小写的大写写法）：${FIELD_DATE_FORMATS.join("、")}。Java 写法 yyyy-MM-dd 不在其中——平台 DateBizField 会判为 不支持的format，字段能创建但**首次运行时 save 报 50000**（2026-09-30 R5 实测）`);
+    }
+    if (type === FIELD_PROPERTY_TYPES.FORMULA) {
+        if (options && (options.resultType !== undefined || options.expression !== undefined))
+            refuseFieldOptions("FORMULA options carried the legacy top-level resultType/expression keys, which the platform does not read", "rejected: FORMULA(100) options must use formulaConfig (nested JSON string) + persistent:true; top-level resultType/expression are not platform keys");
+        const formulaConfig = options?.formulaConfig;
+        if (!isNonEmptyString(formulaConfig))
+            refuseFieldOptions("FORMULA options are missing the required formulaConfig JSON string", "rejected: FORMULA(100) requires options.formulaConfig (a nested JSON string: resultType/formulaType/expression) — see field-contract");
+        const config = parseOptionsObject(formulaConfig);
+        if (!config)
+            refuseFieldOptions("FORMULA formulaConfig is not a parseable JSON object string", "rejected: FORMULA(100) options.formulaConfig must be a JSON object string");
+        if (config.formulaType !== undefined && config.formulaType !== "EXPRESSION" && config.formulaType !== "AGGREGATION")
+            refuseFieldOptions(`FORMULA formulaType ${String(config.formulaType)} is not EXPRESSION or AGGREGATION`, "rejected: FORMULA(100) formulaType must be EXPRESSION or AGGREGATION (8.6.26 FormulaPropertyOptions.FormulaType)");
+        if (config.resultType !== 0 && config.resultType !== 2)
+            refuseFieldOptions(`FORMULA resultType ${String(config.resultType)} is not an evidenced result type`, "rejected: FORMULA(100) resultType must be SHORT_TEXT(0) or NUMERICAL(2) (omc-core formula-field-contract v1 boundary)");
+        if (config.resultFormat !== undefined && config.resultFormat !== "" && config.resultFormat !== "percentile")
+            refuseFieldOptions(`FORMULA resultFormat ${String(config.resultFormat)} is not an evidenced value`, 'rejected: FORMULA(100) resultFormat must be "" or "percentile" (field-families-fwb-20260914.md §100); unknown values are refused fail-closed');
+        // Ticket 114: the outer `format` key is a readback MIRROR of the inner
+        // resultFormat (fwb §100). Each face being individually valid is not
+        // enough — a disagreement would silently persist two contradicting
+        // values while which face the runtime reads stays unevidenced. Refuse
+        // the mismatch instead of guessing.
+        const outerFormat = options?.format;
+        if (outerFormat !== undefined && outerFormat !== "" && outerFormat !== "percentile")
+            refuseFieldOptions(`FORMULA outer format ${String(outerFormat)} is not an evidenced value`, 'rejected: FORMULA(100) outer options.format must be "" or "percentile" — it mirrors formulaConfig.resultFormat (field-families-fwb-20260914.md §100)');
+        if (outerFormat !== undefined && outerFormat !== (config.resultFormat ?? ""))
+            refuseFieldOptions(`FORMULA outer format ${String(outerFormat)} disagrees with inner resultFormat ${String(config.resultFormat ?? "")}`, "rejected: formula-format-mismatch — outer options.format must equal formulaConfig.resultFormat (they are two faces of one setting; fwb §100)");
+        if (options?.persistent !== true)
+            refuseFieldOptions("FORMULA persistent was not true", "rejected: FORMULA(100) requires persistent:true (persistent=false is outside the evidenced contract)");
+        // AGGREGATION formulaType IS the platform's supported roll-up (form 控制
+        // 「计算」控件 → 公式配置 → 配置方式「聚合计算 Aggregation Calculation」；
+        // UI 实测 2026-10-07：文案「跨模型数据聚合计算，如求和/最大值/最小值」，
+        // 步骤=选业务模型→选计算方式→定义参与计算的数据范围). FormulaProcessor
+        // .executeMainAggregation (cloudpivot-bizobject 8.6.26) JSON-parses
+        // `formulaConfig.aggregation` into AggregationFormula {schemaCode,dataItemCode,
+        // formula,calculateType,queryConditions}, queries that schema with the rule's
+        // queryConditions, and evaluates `formula` over the matched rows' dataItemCode
+        // values. Previously this tool BLOCKED the type outright (ticket 24 saw an
+        // empty-queryConditions probe evaluate to 0) — a FALSE NEGATIVE (the same
+        // 二开-vs-配置 call an agent wrongly made: 表单字段「计算」公式可直接做聚合).
+        // Validate the evidenced shape and allow it.
+        // NOTE (open): the exact aggregation for a SAME-model child table (子表求和回
+        // 主表) still needs a live sample — a guessed child-schemaCode shape hit
+        // 305003 at publish (checkCycleOfAggregation in BizPropertyManagerImpl treats
+        // the child's parent == the field's own schema as a cycle). The UI save
+        // payload is the authoritative shape; do not hand-fabricate it.
+        // The EXPRESSION-as-aggregate trap below still applies only to EXPRESSION.
+        const isAggregation = config.formulaType === "AGGREGATION";
+        if (isAggregation) {
+            if (!isNonEmptyString(config.aggregation))
+                refuseFieldOptions("AGGREGATION formulaConfig is missing a non-empty aggregation JSON string", "rejected: AGGREGATION requires formulaConfig.aggregation (a nested JSON *string*, not an object)");
+            else {
+                const agg = parseOptionsObject(config.aggregation);
+                if (!agg || !isNonEmptyString(agg.schemaCode) || !isNonEmptyString(agg.dataItemCode) || !isNonEmptyString(agg.formula))
+                    refuseFieldOptions("AGGREGATION aggregation is missing schemaCode/dataItemCode/formula", 'rejected: aggregation 形状 {schemaCode:"<子表schemaCode>", dataItemCode:"<子表字段code>", formula:"SUM({<子表schemaCode>.<子表字段code>})", calculateType?:.., queryConditions?:[]}（FormulaProcessor.executeMainAggregation + AggregationFormula）');
+            }
+        }
+        else if (!isNonEmptyString(config.expression)) {
+            refuseFieldOptions("EXPRESSION formulaConfig is missing a non-empty expression", "rejected: EXPRESSION requires formulaConfig.expression");
+        }
+        // Aggregation-as-EXPRESSION (e.g. `SUM({child.field})` on a MAIN formula field
+        // over its own CHILD table) is the platform's FORM-designer shape for
+        // subtable→main roll-up — NOT a trap. UI-verified 2026-10-07: the form
+        // Formula control's Expression Calculation mode offers `SUM(v)` ("v is a
+        // numeric subform control") and the Data Item tree lists child columns; a
+        // configured `SUM(报名明细.金额)` published errcode:0 and computed 350 at
+        // runtime via the portal form. The earlier block here was a FALSE NEGATIVE
+        // (a round9 probe conflated a NPE from a SEPARATE broken child formula rule
+        // with this shape). ALLOWED. NOTE: OMC's `data.save`/`data.update` (API path)
+        // can 50000 on models that carry a CHILD formula rule, because the server
+        // re-runs CalculateHandler→FormulaProcessor; the portal form path does not.
+        // Verify such models via the portal form, not the API.
+        void expressionBody(typeof config.expression === "string" ? config.expression : "");
+        // Field-reference semantics (live 2026-09-24, bench38/bench40) — documented,
+        // NOT gated (the own-schema prefix is right or wrong depending on whether the
+        // formula field itself sits on a main or a child schema, which this check
+        // cannot see):
+        //  - BARE `{field}` = the MAIN record's field;
+        //  - DOTTED `{childSchema.field}` = a CHILD table's field.
+        // So a MAIN-table formula references its own fields bare (a dotted own-schema
+        // ref is read as a child table and silently computes null — bench38), while a
+        // CHILD-table formula MUST reference sibling child fields dotted with the
+        // child schema (a bare ref there reads the main record and 50000s — bench40).
+        // Both shapes are accepted here; the runtime split is authoritative.
+        return;
+    }
+    if (type === FIELD_PROPERTY_TYPES.RELEVANCE_DATA) {
+        if (options && (options.schemaCode !== undefined || options.mappings !== undefined || options.displayField !== undefined))
+            refuseFieldOptions("RELEVANCE_DATA options carried relation keys (schemaCode/mappings/displayField)", "rejected: RELEVANCE_DATA(16) references another field, not a model; use relevanceField/referenceField/referenceFieldPropertyType");
+        if (!isNonEmptyString(options?.relevanceField) || !isNonEmptyString(options?.referenceField) || !Number.isInteger(options?.referenceFieldPropertyType))
+            refuseFieldOptions("RELEVANCE_DATA options are missing relevanceField/referenceField/referenceFieldPropertyType", "rejected: RELEVANCE_DATA(16) requires options {relevanceField, referenceField, referenceFieldPropertyType} (RelevanceDataOptions / validateRelevanceDataPropertyConfig)");
+        if (options?.referenceFieldControlType !== undefined && !Number.isInteger(options.referenceFieldControlType))
+            refuseFieldOptions("RELEVANCE_DATA referenceFieldControlType is not an integer control code", "rejected: RELEVANCE_DATA(16) referenceFieldControlType must be an integer BizFormPropertyType code");
+    }
+}
+//# sourceMappingURL=field-families.js.map