@stalfh233/omc-cli 0.0.0-stage → 0.4.10

package/dist/intent/capabilities/field.js

@@ -0,0 +1,545 @@
+import { validateBusinessCode } from "../../code-rules.js";
+import { fieldSemanticDescriptor, prepareFieldChange } from "../../field-change.js";
+import { CHILD_TABLE_SCALAR_PROPERTY_TYPES, FIELD_PROPERTY_TYPES, OUT_OF_COVERAGE_FIELD_TYPES, isNumericalScale } from "../../field-families.js";
+import { ENDPOINTS } from "../../endpoints.js";
+import { wireCall, wireRows } from "../../wire.js";
+import { canonicalJson } from "../dsl.js";
+import { refuse } from "../capability.js";
+import { describe, isScalarString, pushError } from "../validation.js";
+import { toPlain } from "../yaml.js";
+/** Keys a field item accepts. Relation fields may carry `relativeCode` /
+ *  `displayField` at the top level too — that is the `field.create` row shape,
+ *  and accepting it here means a caller can copy a working `field.create` args
+ *  block straight into the intent instead of translating it (bench41: an agent
+ *  wrote `relativeCode:` at the field level, got `intent-key-unknown`, and fell
+ *  back to `field.update`). They are lifted into `options` at parse time. */
+const FIELD_KEYS = new Set(["code", "name", "type", "choices", "subFields", "options", "relativeCode", "displayField", "absent"]);
+/** Field options that callers habitually write at the top level instead of under
+ *  `options` (2026-09-28 bench65: an agent declared `requiredFormula` beside
+ *  `type`, got `intent-key-unknown`, and only then moved it into `options`). The
+ *  message names `options` so the recovery is one edit, not a round. */
+const FIELD_OPTION_KEYS = new Set(["requiredFormula", "readonlyCondition", "displayFormula", "shortTextStitch", "scale", "format"]);
+/** Keys that describe a live field and are meaningless on a declared-absent one. */
+const FIELD_PRESENT_ONLY_KEYS = ["name", "type", "choices", "subFields", "options", "relativeCode", "displayField"];
+/** Keys a child-table column accepts. */
+const SUB_FIELD_KEYS = new Set(["code", "name", "type", "choices", "relativeCode", "options"]);
+/** Field families whose TEXT-CHOICE semantics accept `choices`. SELECTION(5) is a
+ *  people/department mixed selector (control type 62), not a text choice, and is
+ *  deliberately excluded (choices on it produced an unstorable field; 2026-09-27). */
+const CHOICE_FAMILIES = new Set(["RADIO", "CHECKBOX", "DROPDOWN_BOX", "DROPDOWN_MULTI_BOX"]);
+/** Relation families whose target model rides the row-level `relativeCode`. */
+const RELATION_FAMILIES = new Set(["WORK_SHEET", "MULT_WORK_SHEET"]);
+/**
+ * The row-level `relativeCode` for a TOP-LEVEL relation field. `field.create`
+ * wants the target on the row (and also `options.schemaCode`); the intent DSL
+ * carries it inside `options` (the field node has no top-level `relativeCode`
+ * key), so without this lift a declared WORK_SHEET created a field with NO
+ * relation target (dry-run summary "关联单选，挂在 X" instead of "…，关联 Y").
+ * Mirrors the child-column path (subFieldArgs already lifts `sub.relativeCode`).
+ */
+function relationCodeOf(field) {
+    if (!RELATION_FAMILIES.has(String(field.type)))
+        return undefined;
+    const raw = field.options?.relativeCode ?? field.options?.schemaCode;
+    return typeof raw === "string" && raw.trim() ? raw.trim() : undefined;
+}
+const familyOf = (wireType) => Object.entries(FIELD_PROPERTY_TYPES).find(([, value]) => value === wireType)?.[0];
+/** Explicit option keys the intent declares (relations lift `relativeCode` to the row). */
+function declaredOptionKeys(field) {
+    const keys = Object.keys(field.options ?? {}).filter((key) => key !== "relativeCode" && key !== "schemaCode");
+    if ((field.choices?.length ?? 0) > 0)
+        keys.push("optionsSet");
+    return [...new Set(keys)];
+}
+/** The options the write seam would send for a declared field (its own normalizer). */
+function expectedFieldOptions(schemaCode, field) {
+    try {
+        return prepareFieldChange({
+            schemaCode,
+            code: field.code,
+            name: field.name ?? "",
+            propertyType: field.type,
+            ...(field.choices ? { choices: field.choices } : {}),
+            ...(field.options ? { options: field.options } : {}),
+        }).options;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Compare only the option keys the intent explicitly declared against the live
+ * row (a projection, not deep equality: the platform stores many derived keys we
+ * never declared). Without this, a field whose options silently failed to land
+ * (observed 2026-09-27: `field.list` briefly reported options:null for a row
+ * that had them, and the final readback called the intent equivalent) is
+ * reported as converged — the agent then discovers it at runtime instead.
+ */
+function compareFieldOptions(schemaCode, field, live, emit) {
+    const keys = declaredOptionKeys(field);
+    if (keys.length === 0)
+        return;
+    const resource = `field:${schemaCode}.${field.code}`;
+    const expected = expectedFieldOptions(schemaCode, field);
+    const liveOptions = (live.options ?? {});
+    for (const key of keys) {
+        if (key === "optionsSet") {
+            const customCodes = (value) => {
+                const custom = value?.custom;
+                return Array.isArray(custom) ? custom.map((entry) => String(entry?.code ?? "")) : [];
+            };
+            const want = customCodes(expected?.optionsSet).sort();
+            const got = customCodes(liveOptions.optionsSet).sort();
+            if (canonicalJson(want) !== canonicalJson(got))
+                emit.difference("field-options-mismatch", resource, `字段 ${resource} 的 choices 与 live 不一致（live=${canonicalJson(got)} intent=${canonicalJson(want)}）`);
+            continue;
+        }
+        if (canonicalJson(expected?.[key] ?? null) !== canonicalJson(liveOptions[key] ?? null))
+            emit.difference("field-options-mismatch", resource, `字段 ${resource} 的 options.${key} 与 live 不一致（live=${canonicalJson(liveOptions[key] ?? null)} intent=${canonicalJson(expected?.[key] ?? null)}）`);
+    }
+}
+/** Map declared child columns to the exact `field.create` args. */
+function subFieldArgs(subs) {
+    return subs.map((sub) => ({
+        code: sub.code,
+        name: sub.name,
+        propertyType: sub.type,
+        ...(sub.choices ? { choices: sub.choices } : {}),
+        ...(sub.relativeCode ? { relativeCode: sub.relativeCode } : {}),
+        ...(sub.options ? { options: sub.options } : {}),
+    }));
+}
+/**
+ * CHILD_TABLE(8) child columns: the parent row's `subSchema.properties`
+ * (code/name/propertyType). System/default columns the platform injects are
+ * kept too — the compiler only diffs declared codes and treats the rest as
+ * ownership-ignored, so nothing is deleted or reported.
+ */
+function subFieldsOf(row) {
+    const subSchema = row.subSchema;
+    if (!subSchema || typeof subSchema !== "object")
+        return [];
+    const properties = subSchema.properties;
+    if (!Array.isArray(properties))
+        return [];
+    return properties
+        .filter((child) => child !== null && typeof child === "object")
+        .map((child) => ({ code: String(child.code ?? ""), name: String(child.name ?? child.code ?? ""), type: Number(child.propertyType ?? child.type) }))
+        .filter((child) => child.code.length > 0 && Number.isFinite(child.type));
+}
+async function readFields(session, schemaCode) {
+    const draftRows = wireRows((await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode, isPublish: "false" } })).data);
+    const publishedRows = wireRows((await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode, isPublish: "true" } })).data);
+    const codeOf = (row) => String(row.code ?? row.propertyCode ?? "");
+    const fields = new Map();
+    for (const row of draftRows) {
+        const code = codeOf(row);
+        if (!code || fields.has(code))
+            continue;
+        const options = fieldSemanticDescriptor(row).options;
+        fields.set(code, { code, name: String(row.name ?? code), type: Number(row.type ?? row.propertyType), published: false, ...(options !== undefined ? { options } : {}), subFields: subFieldsOf(row) });
+    }
+    for (const row of publishedRows) {
+        const code = codeOf(row);
+        if (!code)
+            continue;
+        const options = fieldSemanticDescriptor(row).options;
+        fields.set(code, { code, name: String(row.name ?? code), type: Number(row.type ?? row.propertyType), published: true, ...(options !== undefined ? { options } : {}), subFields: subFieldsOf(row) });
+    }
+    return [...fields.values()];
+}
+/**
+ * The field capability (field families + CHILD_TABLE columns). It owns the
+ * whole field lifecycle on the intent face: declaration validation, the
+ * authoritative draft/published field read, the idempotent create/update/publish
+ * diff, and the wire->family decode. Child-column knowledge lives only here.
+ */
+export const fieldCapability = {
+    id: "field",
+    title: "字段（含子表）",
+    requires: ["model"],
+    operations: ["create", "update", "publish"],
+    validate(node, draft, ctx) {
+        const fieldsNode = node.entries.find((entry) => entry.key === "fields")?.value;
+        let fields = [];
+        if (fieldsNode !== undefined && !(fieldsNode.kind === "scalar" && fieldsNode.value === null)) {
+            if (fieldsNode.kind !== "seq") {
+                pushError(ctx, "intent-fields-not-a-list", `fields 必须是列表（得到 ${describe(fieldsNode)}）`, `${ctx.base}.fields`, "value");
+            }
+            else {
+                const seenFieldCodes = new Set();
+                fields = fieldsNode.items
+                    .map((fieldNode, fieldIndex) => {
+                    const fieldBase = `${ctx.base}.fields[${fieldIndex}]`;
+                    if (fieldNode.kind !== "map") {
+                        pushError(ctx, "intent-field-not-a-map", `字段项必须是映射（得到 ${describe(fieldNode)}）`, fieldBase, "value");
+                        return null;
+                    }
+                    for (const entry of fieldNode.entries) {
+                        if (!FIELD_KEYS.has(entry.key))
+                            pushError(ctx, "intent-key-unknown", FIELD_OPTION_KEYS.has(entry.key)
+                                ? `字段不支持键 "${entry.key}"；"${entry.key}" 是字段选项，必须写在 options 下（如 options.${entry.key}）。顶层只接受 code / name / type / choices / subFields / options / relativeCode / displayField / absent`
+                                : `字段不支持键 "${entry.key}"（只接受 code / name / type / choices / subFields / options / relativeCode / displayField / absent）`, `${fieldBase}.${entry.key}`);
+                    }
+                    const fieldCodeNode = fieldNode.entries.find((entry) => entry.key === "code")?.value;
+                    const fieldNameNode = fieldNode.entries.find((entry) => entry.key === "name")?.value;
+                    const typeNode = fieldNode.entries.find((entry) => entry.key === "type")?.value;
+                    const choicesNode = fieldNode.entries.find((entry) => entry.key === "choices")?.value;
+                    const absentNode = fieldNode.entries.find((entry) => entry.key === "absent")?.value;
+                    const optionsNode = fieldNode.entries.find((entry) => entry.key === "options")?.value;
+                    const relativeNode = fieldNode.entries.find((entry) => entry.key === "relativeCode")?.value;
+                    const displayNode = fieldNode.entries.find((entry) => entry.key === "displayField")?.value;
+                    if (optionsNode !== undefined && optionsNode.kind !== "map")
+                        pushError(ctx, "intent-field-options-invalid", "字段 options 必须是映射（如 NUMERICAL: { scale: 2 }）", `${fieldBase}.options`, "value");
+                    if (relativeNode !== undefined && !isScalarString(relativeNode))
+                        pushError(ctx, "intent-field-relativecode-invalid", "字段 relativeCode 必须是非空字符串（目标模型 code）", `${fieldBase}.relativeCode`, "value");
+                    if (displayNode !== undefined && !isScalarString(displayNode))
+                        pushError(ctx, "intent-field-displayfield-invalid", "字段 displayField 必须是非空字符串（目标模型展示字段 code）", `${fieldBase}.displayField`, "value");
+                    let fieldCode = "";
+                    let fieldType = "";
+                    if (!isScalarString(fieldCodeNode))
+                        pushError(ctx, "intent-field-code-invalid", "字段 code 必须是非空字符串", `${fieldBase}.code`, "value");
+                    else {
+                        fieldCode = fieldCodeNode.value.trim();
+                        const violations = validateBusinessCode(fieldCode, { kind: "field" });
+                        if (violations.length > 0)
+                            pushError(ctx, "intent-field-code-invalid", `字段 code 未过出门前校验：${violations.map((violation) => violation.message).join("；")}`, `${fieldBase}.code`, "value", { validation: violations });
+                        if (seenFieldCodes.has(fieldCode))
+                            pushError(ctx, "intent-field-code-duplicate", `字段 code 在模型内重复：${fieldCode}`, `${fieldBase}.code`, "value");
+                        seenFieldCodes.add(fieldCode);
+                    }
+                    if (absentNode !== undefined && (absentNode.kind !== "scalar" || typeof absentNode.value !== "boolean"))
+                        pushError(ctx, "intent-field-absent-invalid", "字段 absent 必须是布尔", `${fieldBase}.absent`, "value");
+                    if (absentNode?.kind === "scalar" && absentNode.value === true) {
+                        // Declared-absent field: only its code is meaningful. Refuse shape
+                        // keys rather than silently ignoring them.
+                        for (const key of FIELD_PRESENT_ONLY_KEYS) {
+                            if (fieldNode.entries.some((entry) => entry.key === key))
+                                pushError(ctx, "intent-field-absent-with-shape", `字段声明 absent:true 表示删除该字段，不能再声明 ${key}`, `${fieldBase}.${key}`);
+                        }
+                        if (fieldCode.length === 0)
+                            return null;
+                        return { code: fieldCode, absent: true };
+                    }
+                    if (!isScalarString(fieldNameNode))
+                        pushError(ctx, "intent-field-name-invalid", "字段 name 必须是非空字符串", `${fieldBase}.name`, "value");
+                    if (!isScalarString(typeNode)) {
+                        pushError(ctx, "intent-field-type-unknown", `字段 type 必须是字段族名字符串（得到 ${describe(typeNode)}）`, `${fieldBase}.type`, "value");
+                    }
+                    else {
+                        fieldType = typeNode.value.trim();
+                        if (fieldType in OUT_OF_COVERAGE_FIELD_TYPES) {
+                            pushError(ctx, "intent-field-type-out-of-coverage", `字段族 ${fieldType} 在覆盖面之外（${OUT_OF_COVERAGE_FIELD_TYPES[fieldType]}）——请换用受支持族或走 escape hatch（omc call）`, `${fieldBase}.type`, "value");
+                        }
+                        else if (!(fieldType in FIELD_PROPERTY_TYPES)) {
+                            pushError(ctx, "intent-field-type-unknown", `未知字段族 "${fieldType}"——可用族见 omc commands --json 的 intent.fieldFamilies`, `${fieldBase}.type`, "value");
+                        }
+                    }
+                    let choices;
+                    if (choicesNode !== undefined && !(choicesNode.kind === "scalar" && choicesNode.value === null)) {
+                        const validChoices = choicesNode.kind === "seq" && choicesNode.items.every((item) => isScalarString(item) && item.value.trim().length > 0);
+                        if (!validChoices) {
+                            pushError(ctx, "intent-field-choices-invalid", "choices 必须是非空字符串列表", `${fieldBase}.choices`, "value");
+                        }
+                        else {
+                            choices = choicesNode.items.map((item) => item.value.trim());
+                            if (!(fieldType in FIELD_PROPERTY_TYPES) || !CHOICE_FAMILIES.has(fieldType))
+                                pushError(ctx, "intent-field-choices-unexpected", `choices 只用于选择族（${[...CHOICE_FAMILIES].join(" / ")}）；字段族 ${fieldType || "(未知)"}不接受`, `${fieldBase}.choices`, "value");
+                        }
+                    }
+                    const subFieldsNode = fieldNode.entries.find((entry) => entry.key === "subFields")?.value;
+                    let subFields;
+                    if (subFieldsNode !== undefined && !(subFieldsNode.kind === "scalar" && subFieldsNode.value === null)) {
+                        if (subFieldsNode.kind !== "seq") {
+                            pushError(ctx, "intent-subfields-not-a-list", "subFields 必须是列表（仅 CHILD_TABLE 字段接受）", `${fieldBase}.subFields`, "value");
+                        }
+                        else {
+                            const seenSubCodes = new Set();
+                            subFields = subFieldsNode.items
+                                .map((subNode, subIndex) => {
+                                const subBase = `${fieldBase}.subFields[${subIndex}]`;
+                                if (subNode.kind !== "map") {
+                                    pushError(ctx, "intent-subfield-not-a-map", `子列项必须是映射（得到 ${describe(subNode)}）`, subBase, "value");
+                                    return null;
+                                }
+                                for (const entry of subNode.entries) {
+                                    if (!SUB_FIELD_KEYS.has(entry.key))
+                                        pushError(ctx, "intent-key-unknown", `子列不支持键 "${entry.key}"（只接受 code / name / type / choices / relativeCode / options）`, `${subBase}.${entry.key}`);
+                                }
+                                const subCodeNode = subNode.entries.find((entry) => entry.key === "code")?.value;
+                                const subNameNode = subNode.entries.find((entry) => entry.key === "name")?.value;
+                                const subTypeNode = subNode.entries.find((entry) => entry.key === "type")?.value;
+                                const subChoicesNode = subNode.entries.find((entry) => entry.key === "choices")?.value;
+                                const subRelativeNode = subNode.entries.find((entry) => entry.key === "relativeCode")?.value;
+                                const subOptionsNode = subNode.entries.find((entry) => entry.key === "options")?.value;
+                                let subCode = "";
+                                let subType = "";
+                                if (!isScalarString(subCodeNode))
+                                    pushError(ctx, "intent-subfield-code-invalid", "子列 code 必须是非空字符串", `${subBase}.code`, "value");
+                                else {
+                                    subCode = subCodeNode.value.trim();
+                                    const violations = validateBusinessCode(subCode, { kind: "field" });
+                                    if (violations.length > 0)
+                                        pushError(ctx, "intent-subfield-code-invalid", `子列 code 未过出门前校验：${violations.map((violation) => violation.message).join("；")}`, `${subBase}.code`, "value", { validation: violations });
+                                    if (seenSubCodes.has(subCode))
+                                        pushError(ctx, "intent-subfield-code-duplicate", `子列 code 在子表内重复：${subCode}`, `${subBase}.code`, "value");
+                                    seenSubCodes.add(subCode);
+                                }
+                                if (!isScalarString(subNameNode))
+                                    pushError(ctx, "intent-subfield-name-invalid", "子列 name 必须是非空字符串", `${subBase}.name`, "value");
+                                if (!isScalarString(subTypeNode)) {
+                                    pushError(ctx, "intent-subfield-type-unknown", `子列 type 必须是字段族名字符串（得到 ${describe(subTypeNode)}）`, `${subBase}.type`, "value");
+                                }
+                                else {
+                                    subType = subTypeNode.value.trim();
+                                    if (subType === "CHILD_TABLE")
+                                        pushError(ctx, "intent-subfield-type-nested", "子表不能嵌套子表（CHILD_TABLE 不能作为子列）", `${subBase}.type`, "value");
+                                    else if (subType in OUT_OF_COVERAGE_FIELD_TYPES)
+                                        pushError(ctx, "intent-subfield-type-out-of-coverage", `子列族 ${subType} 在覆盖面之外（${OUT_OF_COVERAGE_FIELD_TYPES[subType]}）`, `${subBase}.type`, "value");
+                                    else if (!(subType in FIELD_PROPERTY_TYPES))
+                                        pushError(ctx, "intent-subfield-type-unknown", `未知子列族 "${subType}"——可用族见 omc commands --json 的 intent.fieldFamilies`, `${subBase}.type`, "value");
+                                    else if (!CHILD_TABLE_SCALAR_PROPERTY_TYPES.has(FIELD_PROPERTY_TYPES[subType]))
+                                        pushError(ctx, "intent-subfield-type-unsupported", `子列族 ${subType} 不在子表覆盖内（MULT_WORK_SHEET/RELEVANCE_DATA/FORMULA 等见 omc capability field 的说明）`, `${subBase}.type`, "value");
+                                }
+                                // Relation child column (WORK_SHEET): relativeCode required.
+                                // `options` is open to every family since round 4 — the
+                                // write gate refuses family-invalid shapes (e.g. a
+                                // NUMERICAL column without options.scale).
+                                const isRelationChild = subType === "WORK_SHEET";
+                                if (subRelativeNode !== undefined && !isScalarString(subRelativeNode))
+                                    pushError(ctx, "intent-subfield-relativecode-invalid", "子列 relativeCode 必须是非空字符串（目标模型 code）", `${subBase}.relativeCode`, "value");
+                                if (subOptionsNode !== undefined && subOptionsNode.kind !== "map")
+                                    pushError(ctx, "intent-subfield-options-invalid", "子列 options 必须是映射", `${subBase}.options`, "value");
+                                if (isRelationChild && !isScalarString(subRelativeNode))
+                                    pushError(ctx, "intent-subfield-relativecode-required", "子表关联列（WORK_SHEET）必须给 relativeCode（目标模型 code，如 customer）", `${subBase}.relativeCode`, "value");
+                                if (!isRelationChild && subRelativeNode !== undefined)
+                                    pushError(ctx, "intent-subfield-relation-only", `relativeCode 只用于子表关联列（WORK_SHEET）；子列族 ${subType || "(未知)"} 不接受`, subBase, "value");
+                                let subChoices;
+                                if (subChoicesNode !== undefined && !(subChoicesNode.kind === "scalar" && subChoicesNode.value === null)) {
+                                    const validSubChoices = subChoicesNode.kind === "seq" && subChoicesNode.items.every((item) => isScalarString(item) && item.value.trim().length > 0);
+                                    if (!validSubChoices)
+                                        pushError(ctx, "intent-subfield-choices-invalid", "choices 必须是非空字符串列表", `${subBase}.choices`, "value");
+                                    else {
+                                        subChoices = subChoicesNode.items.map((item) => item.value.trim());
+                                        if (!(subType in FIELD_PROPERTY_TYPES) || !CHOICE_FAMILIES.has(subType))
+                                            pushError(ctx, "intent-subfield-choices-unexpected", `choices 只用于选择族（${[...CHOICE_FAMILIES].join(" / ")}）；子列族 ${subType || "(未知)"}不接受`, `${subBase}.choices`, "value");
+                                    }
+                                }
+                                if (subCode.length === 0 || subType.length === 0)
+                                    return null;
+                                const subOptions = subOptionsNode?.kind === "map" ? toPlain(subOptionsNode) : {};
+                                if (CHOICE_FAMILIES.has(subType)) {
+                                    for (const misplaced of ["items", "choices"]) {
+                                        if (subOptions[misplaced] !== undefined)
+                                            pushError(ctx, "intent-field-choices-misplaced", `选择族子列（${subType}）的可选值写在子列顶层 choices: [A, B, C]；options.${misplaced} 不是声明入口（原始形状用 options.optionsSet）`, `${subBase}.options.${misplaced}`, "value");
+                                    }
+                                }
+                                if (subType === "NUMERICAL" && !isNumericalScale(subOptions.scale))
+                                    pushError(ctx, "intent-field-scale-required", "子列 NUMERICAL 必须给 options.scale（小数位数：0=整数,1=1位,2=2位…）", `${subBase}.options.scale`, "value");
+                                const subName = isScalarString(subNameNode) ? subNameNode.value : "";
+                                return {
+                                    code: subCode,
+                                    name: subName,
+                                    type: subType,
+                                    ...(subChoices ? { choices: subChoices } : {}),
+                                    ...(isRelationChild && isScalarString(subRelativeNode) ? { relativeCode: subRelativeNode.value.trim() } : {}),
+                                    ...(subOptionsNode?.kind === "map" ? { options: subOptions } : {}),
+                                };
+                            })
+                                .filter((sub) => sub !== null);
+                        }
+                    }
+                    if (fieldType === "CHILD_TABLE" && (subFields === undefined || subFields.length === 0))
+                        pushError(ctx, "intent-subfield-required", "CHILD_TABLE 字段必须声明非空 subFields（子列）", `${fieldBase}.subFields`, "value");
+                    if (fieldType !== "CHILD_TABLE" && subFields !== undefined)
+                        pushError(ctx, "intent-subfields-unexpected", `subFields 只用于 CHILD_TABLE 字段；字段族 ${fieldType || "(未知)"}不接受`, `${fieldBase}.subFields`, "value");
+                    // Top-level relation keys are relation-only; refuse them on other
+                    // families rather than silently ignoring (matches the child column).
+                    const relationField = RELATION_FAMILIES.has(fieldType);
+                    const relativeValue = isScalarString(relativeNode) ? relativeNode.value.trim() : undefined;
+                    const displayValue = isScalarString(displayNode) ? displayNode.value.trim() : undefined;
+                    if (!relationField && relativeValue !== undefined)
+                        pushError(ctx, "intent-field-relation-only", `relativeCode 只用于关联族（${[...RELATION_FAMILIES].join(" / ")}）；字段族 ${fieldType || "(未知)"}不接受`, `${fieldBase}.relativeCode`, "value");
+                    if (!relationField && displayValue !== undefined)
+                        pushError(ctx, "intent-field-relation-only", `displayField 只用于关联族（${[...RELATION_FAMILIES].join(" / ")}）；字段族 ${fieldType || "(未知)"}不接受`, `${fieldBase}.displayField`, "value");
+                    if (relationField && relativeValue === undefined && !(optionsNode?.kind === "map" && toPlain(optionsNode).relativeCode !== undefined))
+                        pushError(ctx, "intent-field-relativecode-required", `关联字段（${fieldType}）必须给 relativeCode（目标模型 code）；可写在字段顶层或 options.relativeCode`, `${fieldBase}.relativeCode`, "value");
+                    const explicitOptions = optionsNode?.kind === "map" ? toPlain(optionsNode) : {};
+                    // A choice family's allowed values live in TOP-LEVEL `choices` (the
+                    // compiler synthesizes the platform's optionsSet). Callers habitually
+                    // try `options.items` / `options.choices`, which the option passthrough
+                    // carries along — so it passed validate/plan and only the live
+                    // field.create refused it (bench40: a RADIO with `options.items` did a
+                    // partial apply then failed on step 5). Refuse offline and name the
+                    // real keys: top-level `choices` (compact) or `options.optionsSet`
+                    // (raw platform shape), not `options.items`.
+                    if (CHOICE_FAMILIES.has(fieldType)) {
+                        for (const misplaced of ["items", "choices"]) {
+                            if (explicitOptions[misplaced] !== undefined)
+                                pushError(ctx, "intent-field-choices-misplaced", `选择族（${fieldType}）的可选值写在字段顶层 choices: [A, B, C]（编译器合成平台的 optionsSet）；options.${misplaced} 不是声明入口（可选项也可直接用原始形状 options.optionsSet）`, `${fieldBase}.options.${misplaced}`, "value");
+                        }
+                    }
+                    const mergedOptions = {
+                        ...explicitOptions,
+                        ...(relativeValue !== undefined ? { relativeCode: relativeValue } : {}),
+                        ...(displayValue !== undefined ? { displayField: displayValue } : {}),
+                    };
+                    // Offline parity with `field.create`'s write gate (assertNumericalScale):
+                    // a NUMERICAL without a valid options.scale passes plan but is refused at
+                    // apply, costing a wasted apply + replan (dogfood bench51). Catch it in
+                    // plan instead.
+                    if (fieldType === "NUMERICAL" && !isNumericalScale(mergedOptions.scale))
+                        pushError(ctx, "intent-field-scale-required", "NUMERICAL 字段必须给 options.scale（小数位数：0=整数,1=1位,2=2位…）；缺失时门户设计器显示为裸 decimal，且 apply 的 field.create 会拒绝", `${fieldBase}.options.scale`, "value");
+                    if (fieldCode.length === 0 || fieldType.length === 0)
+                        return null;
+                    const fieldName = isScalarString(fieldNameNode) ? fieldNameNode.value : "";
+                    return { code: fieldCode, name: fieldName, type: fieldType, ...(choices ? { choices } : {}), ...(Object.keys(mergedOptions).length > 0 ? { options: mergedOptions } : {}), ...(subFields ? { subFields } : {}) };
+                })
+                    .filter((field) => field !== null);
+            }
+        }
+        draft.fields = fields;
+    },
+    async read(session, _intent, draft) {
+        if (!draft.present)
+            return;
+        draft.fields = await readFields(session, draft.code);
+    },
+    plan(intent, baseline, emit) {
+        const existing = new Map(baseline.fields.map((field) => [field.code, field]));
+        let childChanged = false;
+        for (const field of intent.fields) {
+            const current = existing.get(field.code);
+            // Declared-absent field: delete it when present (draft OR published), and
+            // no-op when already gone — so a converged retry is zero-change.
+            if (field.absent === true) {
+                if (current !== undefined) {
+                    emit.change("field.delete", { schemaCode: intent.code, code: field.code }, `field:${intent.code}.${field.code}`, "field-declared-absent");
+                }
+                else {
+                    emit.skip(`field:${intent.code}.${field.code}`, "field-already-absent");
+                }
+                continue;
+            }
+            if (current === undefined) {
+                const relativeCode = relationCodeOf(field);
+                // `relativeCode` is lifted to the row (see relationCodeOf) — drop it from
+                // the options payload so only the platform keys ride the wire.
+                const { relativeCode: _relativeCode, ...relationOptions } = (field.options ?? {});
+                const options = Object.keys(relationOptions).length > 0 ? relationOptions : undefined;
+                emit.change("field.create", { schemaCode: intent.code, code: field.code, name: field.name, propertyType: field.type, ...(field.choices ? { choices: field.choices } : {}), ...(relativeCode ? { relativeCode } : {}), ...(options ? { options } : {}), ...(field.subFields ? { subFields: subFieldArgs(field.subFields) } : {}) }, `field:${intent.code}.${field.code}`, "field-absent");
+                continue;
+            }
+            const currentFamily = familyOf(current.type) ?? `wire:${current.type}`;
+            if (currentFamily !== field.type) {
+                refuse("intent-field-type-drift", `字段 ${intent.code}.${field.code} 已存在且类型为 ${currentFamily}（wire ${current.type}），意图声明 ${field.type}——字段族创建后不可迁移。修正意图类型，或走 escape hatch（omc call field.update 的受支持面）处理特殊场景`, { resource: `field:${intent.code}.${field.code}`, existingType: currentFamily, intentType: field.type });
+            }
+            // CHILD_TABLE(8) child columns are ordinary fields on the child schema
+            // (schemaCode = the parent field code). Diff them against the parent's
+            // authoritative subSchema; extra live columns are ownership-ignored.
+            if (field.type === "CHILD_TABLE") {
+                const liveChildren = new Map(current.subFields.map((child) => [child.code, child]));
+                for (const sub of field.subFields ?? []) {
+                    const live = liveChildren.get(sub.code);
+                    const resource = `subfield:${intent.code}.${field.code}.${sub.code}`;
+                    if (live === undefined) {
+                        emit.change("field.create", { schemaCode: field.code, code: sub.code, name: sub.name, propertyType: sub.type, ...(sub.choices ? { choices: sub.choices } : {}), ...(sub.options ? { options: sub.options } : {}) }, resource, "child-field-absent");
+                        childChanged = true;
+                        continue;
+                    }
+                    const liveFamily = familyOf(live.type) ?? `wire:${live.type}`;
+                    if (liveFamily !== sub.type)
+                        refuse("intent-child-field-type-drift", `子列 ${intent.code}.${field.code}.${sub.code} 已存在且类型为 ${liveFamily}（wire ${live.type}），意图声明 ${sub.type}——子列族创建后不可迁移；修正意图类型或走 escape hatch`, { resource, existingType: liveFamily, intentType: sub.type });
+                    if (live.name !== sub.name) {
+                        emit.change("field.update", { schemaCode: field.code, code: sub.code, name: sub.name }, resource, "child-field-name-drift");
+                        childChanged = true;
+                    }
+                }
+            }
+            if (current.name !== field.name) {
+                emit.change("field.update", { schemaCode: intent.code, code: field.code, name: field.name }, `field:${intent.code}.${field.code}`, "field-name-drift");
+            }
+            else if (current.published) {
+                emit.skip(`field:${intent.code}.${field.code}`, "field-present-published");
+            }
+            else {
+                emit.skip(`field:${intent.code}.${field.code}`, "field-present-draft");
+            }
+        }
+        // Model-scoped publish: only when a requested code is missing from the
+        // published face, or a child-table column changed (child schemas publish
+        // with the model); the tool's own already-published short-circuit plus the
+        // codes list keeps retries idempotent. Declared-absent fields are excluded —
+        // they are being deleted, not published.
+        const requestedCodes = intent.fields.filter((field) => field.absent !== true).map((field) => field.code);
+        const publishedNow = new Set(baseline.fields.filter((field) => field.published).map((field) => field.code));
+        if (requestedCodes.length > 0 && (childChanged || requestedCodes.some((code) => !publishedNow.has(code)))) {
+            emit.change("field.publish", { schemaCode: intent.code, codes: requestedCodes }, `model:${intent.code}`, childChanged ? "child-columns-changed" : "fields-not-published");
+        }
+    },
+    decode(baseline, draft) {
+        draft.fields = baseline.fields.map((field) => ({
+            code: field.code,
+            name: field.name ?? null,
+            type: familyOf(field.type) ?? null,
+            published: field.published,
+            ...(field.options !== undefined ? { options: field.options } : {}),
+            subFields: field.subFields.map((sub) => ({ code: sub.code, name: sub.name ?? null, type: familyOf(sub.type) ?? null, published: field.published })),
+        }));
+    },
+    compare(intent, live, emit) {
+        if (!live.present) {
+            // Whole model gone: declared-absent fields are satisfied (already gone);
+            // declared-present fields are missing with the model.
+            for (const field of intent.fields)
+                if (field.absent !== true)
+                    emit.difference("field-missing", `field:${intent.code}.${field.code}`, `字段 ${intent.code}.${field.code} 随模型缺失`);
+            return;
+        }
+        const liveFields = new Map(live.fields.map((field) => [field.code, field]));
+        for (const field of intent.fields) {
+            const current = liveFields.get(field.code);
+            // Declared-absent field: equivalent only when it is really gone.
+            if (field.absent === true) {
+                if (current !== undefined)
+                    emit.difference("field-present-unexpected", `field:${intent.code}.${field.code}`, `字段 ${intent.code}.${field.code} 声明 absent:true 但仍存在`);
+                continue;
+            }
+            if (current === undefined) {
+                emit.difference("field-missing", `field:${intent.code}.${field.code}`, `字段 ${intent.code}.${field.code} 不存在`);
+                continue;
+            }
+            if (current.type !== null && current.type !== field.type)
+                emit.difference("field-type-mismatch", `field:${intent.code}.${field.code}`, `字段类型 live=${current.type} intent=${field.type}`);
+            if (current.name !== null && current.name !== field.name)
+                emit.difference("field-name-mismatch", `field:${intent.code}.${field.code}`, `字段名 live=${current.name} intent=${field.name}`);
+            compareFieldOptions(intent.code, field, current, emit);
+            if (!current.published)
+                emit.difference("field-not-published", `field:${intent.code}.${field.code}`, `字段 ${intent.code}.${field.code} 未发布`);
+            if (field.type === "CHILD_TABLE" && (field.subFields?.length ?? 0) > 0) {
+                const liveChildren = new Map(current.subFields.map((sub) => [sub.code, sub]));
+                const declaredChildren = new Set(field.subFields.map((sub) => sub.code));
+                for (const sub of field.subFields) {
+                    const liveChild = liveChildren.get(sub.code);
+                    const resource = `subfield:${intent.code}.${field.code}.${sub.code}`;
+                    if (liveChild === undefined) {
+                        emit.difference("child-field-missing", resource, `子列 ${intent.code}.${field.code}.${sub.code} 不存在`);
+                        continue;
+                    }
+                    if (liveChild.type !== null && liveChild.type !== sub.type)
+                        emit.difference("child-field-type-mismatch", resource, `子列类型 live=${liveChild.type} intent=${sub.type}`);
+                    if (liveChild.name !== null && liveChild.name !== sub.name)
+                        emit.difference("child-field-name-mismatch", resource, `子列名 live=${liveChild.name} intent=${sub.name}`);
+                }
+                for (const liveChild of current.subFields)
+                    if (!declaredChildren.has(liveChild.code))
+                        emit.ignored(`subfield:${intent.code}.${field.code}.${liveChild.code}`);
+            }
+        }
+        const intentFieldCodes = new Set(intent.fields.map((field) => field.code));
+        for (const current of live.fields)
+            if (!intentFieldCodes.has(current.code))
+                emit.ignored(`field:${intent.code}.${current.code}`);
+    },
+};
+//# sourceMappingURL=field.js.map