@stalfh233/omc-cli 0.6.16 → 0.6.18

package/dist/graph.js

@@ -46,10 +46,25 @@ function nodeSqlite() {
  *   staleness is handled by reporting pulledAt + identity, refreshed by an
  *   explicit re-pull (no incremental watermarks, no write-back hooks).
  */
-const GRAPH_SCHEMA_VERSION = "4";
+const GRAPH_SCHEMA_VERSION = "5";
 const STALE_LOCK_MS = 15 * 60 * 1000;
 export const DEFAULT_PULL_CONCURRENCY = 16;
 export const MAX_PULL_CONCURRENCY = 32;
+/** 索引超过这个天数就提示刷新（配置类查询，1 天足够新）。 */
+export const STALE_INDEX_DAYS = 1;
+export const STALE_AFTER_MINUTES = STALE_INDEX_DAYS * 24 * 60;
+export function indexAgeDays(pulledAtIso, now = Date.now()) {
+    const pulled = Date.parse(pulledAtIso);
+    if (Number.isNaN(pulled))
+        return 0;
+    return Math.max(0, Math.floor((now - pulled) / 86_400_000));
+}
+export function indexAgeMinutes(pulledAtIso, now = Date.now()) {
+    const pulled = Date.parse(pulledAtIso);
+    if (Number.isNaN(pulled))
+        return 0;
+    return Math.max(0, Math.floor((now - pulled) / 60_000));
+}
 export class GraphIndexAbsentError extends Error {
     constructor(message) {
         super(message);
@@ -179,13 +194,39 @@ export async function pullRuleGraph(session, concurrency = DEFAULT_PULL_CONCURRE
     // zero-guard) wedge the scheduler.
     const scope = await resolveApplicationScope(session, undefined).catch(() => undefined);
     const applicationCode = scope?.code ?? "";
-    const schemaCodes = flattenTreeRows(wireRows((await wireCall(session, { path: ENDPOINTS.applicationTree, query: { appCode: applicationCode } })).data))
-        .filter((row) => row.type === "BizModel" && typeof row.code === "string" && row.code !== "")
-        .map((row) => String(row.code))
-        .sort();
+    const gaps = [];
+    const treeRows = flattenTreeRows(wireRows((await wireCall(session, { path: ENDPOINTS.applicationTree, query: { appCode: applicationCode } })).data));
+    const modelEntities = treeRows.filter((row) => row.type === "BizModel" && typeof row.code === "string" && row.code !== "").map((row) => ({ schemaCode: String(row.code), name: String(row.name ?? row.code) })).sort((a, b) => a.schemaCode.localeCompare(b.schemaCode));
+    const schemaCodes = modelEntities.map((row) => row.schemaCode);
+    const fields = [];
+    const services = [];
+    await Promise.all(schemaCodes.map(async (schemaCode) => {
+        try {
+            const rows = wireRows((await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode, isPublish: "true" } })).data);
+            for (const row of rows) {
+                const code = String(row.code ?? row.propertyCode ?? "");
+                if (code)
+                    fields.push({ schemaCode, code, name: String(row.name ?? row.propertyName ?? code) });
+            }
+        }
+        catch (error) {
+            gaps.push({ kind: "field-list", ref: schemaCode, note: error instanceof Error ? error.message : String(error) });
+        }
+    }));
+    try {
+        await wireCall(session, { path: ENDPOINTS.bizServiceCategoryList });
+        const rows = wireRows((await wireCall(session, { path: ENDPOINTS.bizServiceListByCategoryId, query: { categoryId: "" } })).data);
+        for (const row of rows) {
+            const code = String(row.code ?? "");
+            if (code)
+                services.push({ code, name: String(row.name ?? code) });
+        }
+    }
+    catch (error) {
+        gaps.push({ kind: "service-list", ref: "all", note: error instanceof Error ? error.message : String(error) });
+    }
     const rules = [];
     const edges = [];
-    const gaps = [];
     let parseFailures = 0;
     let dataruleCount = 0;
     let viewCount = 0;
@@ -370,11 +411,15 @@ export async function pullRuleGraph(session, concurrency = DEFAULT_PULL_CONCURRE
             identityFingerprint: identity,
             environmentName: session.environmentName,
             applicationCode,
+            coverage: { applicationCodes: [applicationCode] },
             ...(scope !== undefined ? { applicationResolution: applicationResolutionOf(scope) } : {}),
             pulledAtIso,
         },
         rules,
         edges,
+        models: modelEntities,
+        fields: fields.sort((a, b) => `${a.schemaCode}/${a.code}`.localeCompare(`${b.schemaCode}/${b.code}`)),
+        services: services.sort((a, b) => a.code.localeCompare(b.code)),
         gaps,
         scanned: { models: schemaCodes.length, rules: rules.length, datarules: dataruleCount, views: viewCount, parseFailures },
         timings: { listMs, readMs, totalMs: Date.now() - totalStart },
@@ -489,7 +534,10 @@ export async function publishGraphPull(session, concurrency = DEFAULT_PULL_CONCU
           via TEXT NOT NULL
         );
         CREATE INDEX edges_lookup ON edges(kind, code);
-        CREATE TABLE gaps (kind TEXT NOT NULL, ref TEXT NOT NULL, note TEXT);
+         CREATE TABLE gaps (kind TEXT NOT NULL, ref TEXT NOT NULL, note TEXT);
+         CREATE TABLE models (schema_code TEXT PRIMARY KEY, name TEXT NOT NULL);
+         CREATE TABLE fields (schema_code TEXT NOT NULL, code TEXT NOT NULL, name TEXT NOT NULL);
+         CREATE TABLE services (code TEXT PRIMARY KEY, name TEXT NOT NULL);
       `);
                 const insertMeta = db.prepare("INSERT INTO meta (key, value) VALUES (?, ?)");
                 // `applicationResolution` is an object; String(value) would persist
@@ -506,12 +554,21 @@ export async function publishGraphPull(session, concurrency = DEFAULT_PULL_CONCU
                 const insertGap = db.prepare("INSERT INTO gaps (kind, ref, note) VALUES (?, ?, ?)");
                 for (const gap of data.gaps)
                     insertGap.run(gap.kind, gap.ref, gap.note ?? null);
+                const insertModel = db.prepare("INSERT INTO models (schema_code, name) VALUES (?, ?)");
+                for (const row of data.models)
+                    insertModel.run(row.schemaCode, row.name);
+                const insertField = db.prepare("INSERT INTO fields (schema_code, code, name) VALUES (?, ?, ?)");
+                for (const row of data.fields)
+                    insertField.run(row.schemaCode, row.code, row.name);
+                const insertService = db.prepare("INSERT INTO services (code, name) VALUES (?, ?)");
+                for (const row of data.services)
+                    insertService.run(row.code, row.name);
                 // FTS5 mirrors rules (code+name) for `graph search`; one rebuild after
                 // the bulk insert is cheaper than per-row triggers on a wholesale rebuild.
                 db.exec(`
-        CREATE VIRTUAL TABLE rules_fts USING fts5(rule_code, name, content='rules', content_rowid='rowid');
-        INSERT INTO rules_fts(rules_fts) VALUES('rebuild');
-      `);
+         CREATE VIRTUAL TABLE rules_fts USING fts5(rule_code, name, content='rules', content_rowid='rowid');
+          INSERT INTO rules_fts(rules_fts) VALUES('rebuild');
+        `);
                 db.exec("COMMIT;");
             }
             finally {
@@ -544,6 +601,11 @@ function openGraphIndex() {
             throw new GraphIndexAbsentError(`索引 schema 版本不匹配（${meta.schemaVersion} ≠ ${GRAPH_SCHEMA_VERSION}）；重跑 omc graph pull`);
         const ruleCount = db.prepare("SELECT COUNT(*) AS n FROM rules").get().n;
         const modelCount = db.prepare("SELECT COUNT(DISTINCT schema_code) AS n FROM rules").get().n;
+        const entityCounts = {
+            models: db.prepare("SELECT COUNT(*) AS n FROM models").get().n,
+            fields: db.prepare("SELECT COUNT(*) AS n FROM fields").get().n,
+            services: db.prepare("SELECT COUNT(*) AS n FROM services").get().n,
+        };
         const edgeRows = db.prepare("SELECT kind, COUNT(*) AS n FROM edges GROUP BY kind").all();
         const edges = {};
         for (const row of edgeRows)
@@ -555,19 +617,33 @@ function openGraphIndex() {
             byKind[row.kind] = row.n;
             gapCount += row.n;
         }
+        const pulledAtIso = meta.pulledAtIso ?? "";
+        const ageDays = indexAgeDays(pulledAtIso);
+        const ageMinutes = indexAgeMinutes(pulledAtIso);
+        const coverage = { applicationCodes: meta.applicationCode ? [meta.applicationCode] : [] };
         return {
             db,
             summary: {
                 environmentName: meta.environmentName ?? "",
                 applicationCode: meta.applicationCode ?? "",
+                coverage,
                 // Persisted as JSON by the writer; a legacy index (pre-0.5.4) has no
                 // such key, so this stays optional rather than failing the read.
                 ...(meta.applicationResolution ? { applicationResolution: parseApplicationResolution(meta.applicationResolution) } : {}),
                 identityFingerprint: meta.identityFingerprint ?? "",
-                pulledAtIso: meta.pulledAtIso ?? "",
+                pulledAtIso,
                 freshness: gapCount === 0 ? "complete" : "partial",
+                ageDays,
+                ageMinutes,
+                staleAfterMinutes: STALE_AFTER_MINUTES,
+                // r31a-F16：旧索引 + complete 标签 = 静默错答。给可直接照抄的刷新命令，
+                // 并明确「complete 只指扫描无缺口」。
+                ...(ageDays >= STALE_INDEX_DAYS
+                    ? { staleWarning: `索引是 ${ageDays} 天前的快照（pulledAt ${pulledAtIso}）；freshness:"complete" 只表示扫描无缺口、不表示最新。先 \`omc graph pull --env ${meta.environmentName ?? "<env>"}\` 再查，或给结论加时效限定` }
+                    : {}),
                 models: modelCount,
                 rules: ruleCount,
+                entities: entityCounts,
                 edges,
                 gaps: { count: gapCount, byKind },
             },
@@ -578,6 +654,17 @@ function openGraphIndex() {
         throw error instanceof GraphIndexAbsentError ? error : new GraphIndexAbsentError(`索引不可读（schema 不匹配或文件损坏）：${error instanceof Error ? error.message : String(error)}；重跑 omc graph pull`);
     }
 }
+/**
+ * r35a-F4 / r35a-F4b（真机 2026-11-06）：探针拿 `matches:[]` 差点把一个**被表单引用**
+ * 的字段判成「可安全删除」，紧接着发现 `graph impact` 的 `totals` 全 0 也有同样误读风险。
+ * 三个面（CLI references / CLI impact / MCP explore）必须共用同一份声明——
+ * 分散定义就会被漏掉一处（MCP 面第一版就漏了）。
+ */
+export const GRAPH_COVERAGE = Object.freeze({
+    scanned: Object.freeze(["businessrule", "datarule", "listview"]),
+    notScanned: Object.freeze(["form", "workflow.permissions", "workflow.bindings", "onlinejs", "rule.conditions"]),
+    note: "零命中/全零 totals 只代表 scanned 面没有命中；notScanned 面（尤其 form 与 workflow.permissions）未扫描，不可据此判定可安全删除或无影响",
+});
 /**
  * Zero-hit disambiguation (2026-10-31 capability-test friction, hit twice in
  * one session): querying `impact field mcc_supplier` returns an empty result
@@ -611,11 +698,7 @@ export function queryGraphReferences(kind, code) {
         // 字段判成「可安全删除」——note 只说了「不含规则条件叶子/流程绑定」，从没
         // 明说表单与流程权限表不在扫描范围。散文字段不承担安全契约：这里给结构化
         // coverage，让「没人引用」与「这一面没扫」在机器可读层面可分。
-        const coverage = {
-            scanned: ["businessrule", "datarule", "listview"],
-            notScanned: ["form", "workflow.permissions", "workflow.bindings", "onlinejs", "rule.conditions"],
-            note: "matches:[] 只代表 scanned 面零命中；notScanned 面（尤其 form 与 workflow.permissions）未扫描，不可据此判定可安全删除",
-        };
+        const coverage = GRAPH_COVERAGE;
         return {
             kind,
             code,
@@ -626,7 +709,7 @@ export function queryGraphReferences(kind, code) {
                 ? {
                     note: (gapped
                         ? "零命中，但索引存在扫描缺口——不可作为「无引用」证明；先 omc graph pull 重建再查"
-                        : "零命中=仅 scanned 面（规则/数据规则/视图）没有引用它；form（表单控件）与 workflow.permissions 未扫描，见 coverage.notScanned——不可据此判定可安全删除") +
+                        : `零命中=仅 scanned 面（规则/数据规则/视图）没有引用它；本索引覆盖应用：${summary.coverage.applicationCodes.join("、") || "（未知）"}，不代表其他应用没有引用；form（表单控件）与 workflow.permissions 未扫描，见 coverage.notScanned——不可据此判定可安全删除`) +
                         (zeroHitKindHint(db, kind, code, "references") ?? ""),
                 }
                 : {}),
@@ -643,7 +726,18 @@ export function readGraphStatus() {
     const { db, summary } = openGraphIndex();
     try {
         const gaps = db.prepare("SELECT kind, ref, note FROM gaps ORDER BY kind, ref LIMIT 50").all();
-        return { index: summary, dbBytes: statSync(graphDbPath()).size, gaps };
+        const dbPath = graphDbPath();
+        return {
+            index: summary,
+            dbBytes: statSync(dbPath).size,
+            dbPath,
+            dbId: sha256(dbPath).slice(0, 12),
+            ageMinutes: summary.ageMinutes,
+            staleAfterMinutes: summary.staleAfterMinutes,
+            ...(summary.staleWarning ? { warning: summary.staleWarning } : {}),
+            coverage: summary.coverage,
+            gaps,
+        };
     }
     finally {
         db.close();
@@ -656,18 +750,23 @@ export function readGraphStatus() {
  * a prefix match (`引用*`), which is also what makes CJK usable: unicode61
  * stores a CJK run as one token, so a full-run query hits only by prefix.
  */
-export function searchGraphRules(term, limit = 20) {
+export function searchGraphRules(term, limit = 20, offset = 0) {
     const { db, summary } = openGraphIndex();
     try {
         const tokens = term.trim().split(/\s+/).filter((token) => token !== "");
         let matches = [];
+        const entityMatches = {
+            model: { count: 0, total: 0, items: [] },
+            field: { count: 0, total: 0, items: [] },
+            service: { count: 0, total: 0, items: [] },
+        };
         if (tokens.length > 0) {
             const quoted = tokens.map((token, index) => `"${token.replaceAll('"', '""')}"${index === tokens.length - 1 ? "*" : ""}`).join(" ");
             const rows = db
                 .prepare(`SELECT r.schema_code, r.rule_code, r.name, r.enabled, r.status
            FROM rules_fts JOIN rules r ON r.rowid = rules_fts.rowid
-           WHERE rules_fts MATCH ? ORDER BY bm25(rules_fts), r.schema_code, r.rule_code LIMIT ?`)
-                .all(quoted, limit);
+           WHERE rules_fts MATCH ? ORDER BY bm25(rules_fts), r.schema_code, r.rule_code LIMIT ? OFFSET ?`)
+                .all(quoted, limit, offset);
             const refsFor = db.prepare("SELECT kind, code FROM edges WHERE schema_code = ? AND rule_code = ? ORDER BY kind, code");
             matches = rows.map((row) => {
                 const refs = { service: [], model: [], field: [] };
@@ -683,20 +782,38 @@ export function searchGraphRules(term, limit = 20) {
                     refs,
                 };
             });
+            const searchEntity = (countSql, rowsSql, params, map) => {
+                const total = Number(db.prepare(countSql).get(...params).n);
+                const rows = db.prepare(rowsSql.replace("LIMIT ?", "LIMIT ? OFFSET ?")).all(...params, limit, offset);
+                return {
+                    count: rows.length,
+                    total,
+                    items: rows.map(map),
+                    offset,
+                    limit,
+                    ...(offset + rows.length < total ? { truncated: true, nextOffset: offset + rows.length } : {}),
+                };
+            };
+            entityMatches.model = searchEntity("SELECT COUNT(*) AS n FROM models WHERE instr(name, ?) > 0 OR instr(schema_code, ?) > 0", "SELECT schema_code, name FROM models WHERE instr(name, ?) > 0 OR instr(schema_code, ?) > 0 ORDER BY schema_code LIMIT ?", [term.trim(), term.trim()], (row) => ({ schemaCode: row.schema_code, name: row.name }));
+            entityMatches.field = searchEntity("SELECT COUNT(*) AS n FROM fields WHERE instr(name, ?) > 0 OR instr(code, ?) > 0", "SELECT schema_code, code, name FROM fields WHERE instr(name, ?) > 0 OR instr(code, ?) > 0 ORDER BY schema_code, code LIMIT ?", [term.trim(), term.trim()], (row) => ({ schemaCode: row.schema_code, code: row.code, name: row.name }));
+            entityMatches.service = searchEntity("SELECT COUNT(*) AS n FROM services WHERE instr(name, ?) > 0 OR instr(code, ?) > 0", "SELECT code, name FROM services WHERE instr(name, ?) > 0 OR instr(code, ?) > 0 ORDER BY code LIMIT ?", [term.trim(), term.trim()], (row) => ({ code: row.code, name: row.name }));
         }
         const gapped = summary.gaps.count > 0;
         return {
             term,
             rules: matches,
+            matches: entityMatches,
             index: summary,
-            ...(matches.length === 0
+            coverage: { scanned: ["rule.code", "rule.name", "model.code", "model.name", "field.code", "field.name", "service.code", "service.name"], notScanned: ["rule.body", "form", "workflow.permissions"], note: "检索覆盖规则与实体的 code/name；规则体、表单与流程权限未扫描" },
+            ...(term.trim() !== "" && !/^[A-Za-z][A-Za-z0-9_.-]*$/.test(term.trim()) ? { note: "疑似业务词；本工具同时检索实体 name/code 与规则 code/name，引用明细请使用匹配到的 code 再查 references/impact" } : {}),
+            ...(matches.length === 0 && entityMatches.model.total === 0 && entityMatches.field.total === 0 && entityMatches.service.total === 0
                 ? {
                     note: tokens.length === 0
                         ? "检索词为空"
                         // 实测摩擦（2026-10-30，zlt测试）：中文子串 0 命中后没有下一步提示，
                         // 调用方在「换个词再试」里打转。把两个出口都写进 note：CJK 词首
                         // 通配 + 找引用走 references/impact。
-                        : "没有命中规则。索引只覆盖规则的 code+name（不含规则体）；且只匹配**词首**——FTS5 把「增加预算」当一个词，「预算」匹配不到它。请给全词（增加预算）、词首（增加 或 增加*），或英文 code 前缀。找\"谁引用了 X\"请走 references/impact <kind> <code>。",
+                        : `实体检索：没有命中模型/字段/服务的 name 或 code；本索引覆盖应用：${summary.coverage.applicationCodes.join("、") || "（未知）"}，不代表其他应用没有该实体。\n规则检索：没有命中规则 code/name；规则搜索只匹配词首（例如「增加预算」是一个词，「预算」匹配不到），请给全词、词首或英文 code 前缀。找"谁引用了 X"请走 references/impact <kind> <code>。`,
                 }
                 : {}),
             ...(gapped ? { gapWarning: `索引有 ${summary.gaps.count} 个扫描缺口；命中列表可能不完整` } : {}),
@@ -767,11 +884,12 @@ export function impactGraph(kind, code) {
             listviews: listViewHits.slice(0, 20).map((hit) => ({ schemaCode: hit.schema_code, viewCode: hit.view_code ?? "", via: hit.via })),
             totals: { rules: hop1.length, datarules: dataruleHits.length, listviews: listViewHits.length, touchedServices: services.size, touchedModels: models.size, touchedFields: fields.size },
             index: summary,
+            coverage: GRAPH_COVERAGE,
             ...(hop1.length === 0 && dataruleHits.length === 0 && listViewHits.length === 0
                 ? {
                     note: (gapped
                         ? "零命中，但索引存在扫描缺口——不可作为「无影响」证明；先 omc graph pull 重建再查"
-                        : "零命中=索引覆盖范围内没有引用它（规则面+数据规则面+视图列/排序/条件面；流程绑定暂不在索引内）") +
+                        : "零命中=仅 scanned 面（规则/数据规则/视图）没有影响；form（表单控件）与 workflow.permissions 未扫描，见 coverage.notScanned——不可据此判定「删除无影响」") +
                         (zeroHitKindHint(db, kind, code, "impact") ?? ""),
                 }
                 : {}),

package/dist/lanes/app.js

@@ -5,10 +5,22 @@ import { governedRead } from "../read.js";
 import { writeTool } from "../write.js";
 import { defineTool, ToolRefusalError } from "../tool-types.js";
 import { wireCall, wireRows, WireError } from "../wire.js";
+import { resolveApplicationScope } from "../support.js";
 import { APP_LANE_CONTRACT } from "./app-contract.js";
 import { readAppTree } from "./folder.js";
 const APP_LANE = APP_LANE_CONTRACT.lane;
 const APP_TOOLS = APP_LANE_CONTRACT.tools;
+export async function resolveValidatedApplicationScope(session, requested) {
+    const scope = await resolveApplicationScope(session, requested);
+    const availableApps = wireRows((await wireCall(session, { path: ENDPOINTS.applicationList, query: {} })).data)
+        .map((row) => String(row.appCode ?? row.code ?? "")).filter((code) => code !== "");
+    if (availableApps.length > 0 && !availableApps.includes(scope.code)) {
+        throw new ToolRefusalError({ status: "refused", blocker: "app-not-found", applicationCode: scope.code,
+            applicationResolution: { status: "unresolved", source: scope.source, requested: scope.requested ?? scope.code, available: availableApps.slice(0, 40) },
+            message: `应用「${scope.code}」不在租户 app.list 里（不是「该应用没有模型」）。可用：${availableApps.slice(0, 12).join("、")}${availableApps.length > 12 ? " 等" : ""}；先 app.list 取正确 applicationCode。` });
+    }
+    return scope;
+}
 function appRollbackSpec(toolName) {
     return {
         target: (args) => `app:${String(args.code ?? "")}`,
@@ -48,10 +60,11 @@ export function registerAppLane(tools) {
         description: APP_TOOLS["app.list"].description,
         inputSchema: { environment: environmentArg, capability: capabilityArg },
         handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
-            const applications = wireRows((await wireCall(session, { path: ENDPOINTS.applicationList, query: {} })).data).map((row) => ({
-                code: String(row.appCode ?? row.code),
-                name: row.appName ?? row.name,
-                groupId: row.groupId,
+            const applications = await Promise.all(wireRows((await wireCall(session, { path: ENDPOINTS.applicationList, query: {} })).data).map(async (row) => {
+                const code = String(row.appCode ?? row.code);
+                const tree = await readAppTree(session, code);
+                const modelCount = tree.reduce((count, node) => count + (node.type === "BizModel" ? 1 : 0), 0);
+                return { code, name: row.appName ?? row.name, groupId: row.groupId, modelCount };
             }));
             // r29f F2：与 discover_environment 同构——一眼判断「内联是否全集」。
             // 应用通常个位数，默认内联 + omitted:false；大租户由 governedRead 外置时

package/dist/lanes/field.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { ENDPOINTS } from "../endpoints.js";
 import { fieldChangeWireBody, fieldUpdateWireBody, prepareFieldChange, prepareFieldUpdate } from "../field-change.js";
-import { aggregationSelfSchemaMessage, aggregationTargetsOwnSchema, choicesArg, childColumnsOf, FIELD_PROPERTY_TYPES, fieldOptionsArg, fieldTypeLabel, numericalScaleWarning, propertyTypeArg, relativeCodeArg, stripAggregationPrefix, subFieldArg, SYSTEM_FIELD_CODES, } from "../field-families.js";
+import { aggregationSelfSchemaMessage, aggregationTargetsOwnSchema, choicesArg, childColumnsOf, FIELD_PROPERTY_TYPES, fieldOptionsArg, fieldTypeLabel, numericalScaleWarning, propertyTypeArg, relativeCodeArg, stripAggregationPrefix, subFieldArg, SYSTEM_FIELD_CODES, assertFieldFamilyAllowed, assertSelectionChoicesAllowed, assertRelationTargetExists, relationPublishFailureMessage, } from "../field-families.js";
 import { capabilityArg, environmentArg } from "../args.js";
 import { governedRead } from "../read.js";
 import { writeTool } from "../write.js";
@@ -12,10 +12,29 @@ import { defineTool, ToolRefusalError } from "../tool-types.js";
 import { wireCall, wireRows, WireError } from "../wire.js";
 import { executeFormDraftWrite, executeFormPublishWrite, readFormOrNull } from "../form-support.js";
 import { FIELD_LANE_CONTRACT } from "./field-contract.js";
-import { mapBounded } from "../support.js";
+import { flattenTreeRows, mapBounded, resolveApplicationScope } from "../support.js";
 import { extractBizObjectPage } from "./runtime-data.js";
 const FIELD_LANE = FIELD_LANE_CONTRACT.lane;
 const FIELD_TOOLS = FIELD_LANE_CONTRACT.tools;
+/** Read actual model schema codes; bare modelList may expose internal node ids. */
+export async function modelSchemaCodes(session) {
+    try {
+        const scope = await resolveApplicationScope(session);
+        const tree = flattenTreeRows(wireRows((await wireCall(session, { path: ENDPOINTS.applicationTree, query: { appCode: scope.code } })).data));
+        const codes = tree
+            .filter((row) => row.type === "BizModel")
+            .map((row) => String(row.code ?? row.schemaCode ?? row.bizSchemaCode ?? ""))
+            .filter((code) => code.length > 0);
+        if (codes.length > 0)
+            return codes;
+    }
+    catch {
+        // Fall through to the compatibility endpoint below.
+    }
+    return wireRows((await wireCall(session, { path: ENDPOINTS.modelList, query: {} })).data)
+        .map((row) => String(row.schemaCode ?? row.bizSchemaCode ?? row.code ?? ""))
+        .filter((code) => code.length > 0);
+}
 async function readFieldRollback(session, args) {
     for (const published of [false, true]) {
         const row = wireRows((await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: String(args.schemaCode), isPublish: String(published) } })).data).find((entry) => String(entry.code ?? entry.propertyCode) === String(args.code));
@@ -377,6 +396,8 @@ export function registerFieldLane(tools) {
             // wire body (src/field-change.ts), so configure_model and intent share it.
             assertNoSelfSchemaAggregation(args, published);
             await assertNoChildSchemaAggregation(session, args.schemaCode, args.propertyType, args.options ?? {});
+            const models = await modelSchemaCodes(session);
+            assertRelationTargetExists({ ...args }, models);
             // 目标版本决定 optionsSet 形状：8.2 以下要补 optionStructure/treeSelect
             // （cpdocs issue #8：缺键让设计器选项弹窗硬崩）。
             const targetVersion = session.detectedVersion();
@@ -434,6 +455,7 @@ export function registerFieldLane(tools) {
                 readback: {
                     face: "draft",
                     draftFieldPresent: rows.some((row) => (row.code ?? row.propertyCode) === args.code),
+                    ...(prepared.normalized ? { normalized: prepared.normalized } : {}),
                     ...(textLike
                         ? {
                             sideEffectsNote: "平台可能为文本/下拉字段自动生成一条 datarule type1 checkType=4（maxLength≈200）；本调用未显式创建。清理/对账请用 datarule.list 核对，不要把自动行当成重复写入。",
@@ -442,6 +464,10 @@ export function registerFieldLane(tools) {
                 },
             };
         },
+        preflight: (args) => {
+            assertSelectionChoicesAllowed(args);
+            assertFieldFamilyAllowed(args);
+        },
         rollback: fieldRollbackSpec("field.create"),
     });
     writeTool({
@@ -633,6 +659,15 @@ async function loadFieldRowForUpdate(session, schemaCode, code) {
     const record = rows.find((row) => (row.code ?? row.propertyCode) === code);
     if (!record)
         throw new WireError("business", `field ${code} not found on ${schemaCode}`, 301001);
+    // Some platform list faces are diet projections and omit the display name;
+    // update readback must still preserve the existing name/name_i18n.
+    try {
+        const detail = (await wireCall(session, { path: ENDPOINTS.fieldGet, query: { schemaCode, propertyCode: code } })).data;
+        return { ...detail, ...record, name: record.name ?? detail.name, name_i18n: record.name_i18n ?? detail.name_i18n };
+    }
+    catch {
+        // The detail face is optional; retain the list row.
+    }
     return record;
 }
 async function countModelDataRows(session, schemaCode) {
@@ -1027,6 +1062,58 @@ async function runFieldUpdate(session, args) {
         ...(args.propertyEmpty !== undefined ? { propertyEmpty: args.propertyEmpty } : {}),
     };
     const prepared = prepareFieldUpdate(update);
+    const currentOptions = decodeJsonObjectColumn(record.options, { invalid: "throw", array: "accept", object: "accept" }) ?? {};
+    const requestedChanges = [];
+    const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+    if (args.name !== undefined && !same(record.name ?? null, prepared.name ?? args.name))
+        requestedChanges.push("name");
+    if (args.name_i18n !== undefined && !same(record.name_i18n ?? null, prepared.nameI18n ?? args.name_i18n))
+        requestedChanges.push("name_i18n");
+    if (args.relativeCode !== undefined && !same(record.relativeCode ?? null, args.relativeCode))
+        requestedChanges.push("relativeCode");
+    if (args.propertyEmpty !== undefined && !same(record.propertyEmpty ?? null, args.propertyEmpty))
+        requestedChanges.push("propertyEmpty");
+    if (args.options !== undefined) {
+        for (const key of new Set([...Object.keys(currentOptions), ...Object.keys(prepared.options)]))
+            if (!same(currentOptions[key] ?? null, prepared.options[key] ?? null))
+                requestedChanges.push(`options.${key}`);
+    }
+    const mutableOptionKeys = new Set([
+        // These are established field-row update surfaces (tickets 60/61 and the
+        // condition pairing round). Everything else stays fail-closed: the
+        // platform accepts many keys and silently drops them.
+        "dictionaryData", "optionsSet", "mappings", "schemaCode", "queryCode", "displayField", "displayFieldType", "displayFieldFormat",
+        "relativePropertyMatchCode", "relativePropertyCode", "linkMode", "showStyle", "searchFormula", "conditions",
+        "requiredFormula", "readonlyCondition", "displayFormula", "readonlyFormula", "scale",
+    ]);
+    const changedOptionKeys = requestedChanges.filter((field) => field.startsWith("options.")).map((field) => field.slice("options.".length));
+    const immutableOptionKeys = changedOptionKeys.filter((key) => !mutableOptionKeys.has(key));
+    if (immutableOptionKeys.length > 0) {
+        throw new ToolRefusalError({
+            status: "refused",
+            blocker: "field-options-immutable",
+            schemaCode: args.schemaCode,
+            code: args.code,
+            fields: immutableOptionKeys.map((key) => `options.${key}`),
+            mutableFields: [...mutableOptionKeys].map((key) => `options.${key}`),
+            message: `field.update 不允许经此面修改 options.${immutableOptionKeys.join("、")}；这类字段配置会被平台静默丢弃。可改白名单：${[...mutableOptionKeys].map((key) => `options.${key}`).join("、")}。关联结构（schemaCode/queryCode/displayField 等）请 field.delete + field.create 重建；条件请用字段条件配置。`,
+        });
+    }
+    if (args.choices !== undefined && !same(choiceCodesOf(currentOptions) ?? [], [...args.choices]))
+        requestedChanges.push("choices");
+    if (requestedChanges.length === 0) {
+        return {
+            performed: { errcode: 0, unchanged: true },
+            readback: {
+                face: "draft",
+                unchanged: true,
+                changedFields: [],
+                ...(record.name !== undefined ? { name: record.name } : {}),
+                ...(record.name_i18n !== undefined ? { name_i18n: record.name_i18n } : {}),
+                availableFields: ["name", "name_i18n", "options", "choices", "relativeCode", "propertyEmpty"],
+            },
+        };
+    }
     const performed = await wireCall(session, { path: ENDPOINTS.fieldUpdate, method: "POST", body: fieldUpdateWireBody(update, prepared) });
     const readback = await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "false" } });
     const after = wireRows(readback.data).find((row) => (row.code ?? row.propertyCode) === args.code);
@@ -1038,7 +1125,9 @@ async function runFieldUpdate(session, args) {
     // failure never hides the field write (it is surfaced as formConditionSync.error).
     let formConditionSync;
     let formConditionSyncError;
-    if (effectiveOptions !== undefined && !prepared.isChildTable) {
+    const conditionKeys = new Set(Object.keys(FORM_CONDITION_OPTION_KEYS));
+    const conditionChanged = effectiveOptions !== undefined && [...conditionKeys].some((key) => !fieldValuesEqual((decodeJsonObjectColumn(record.options, { invalid: "throw", array: "accept", object: "accept" }) ?? {})[key], prepared.options[key]));
+    if (conditionChanged && !prepared.isChildTable) {
         const previous = decodeJsonObjectColumn(record.options, { invalid: "throw", array: "accept", object: "accept" }) ?? {};
         try {
             const sync = await syncFormConditionDataRules(session, args.schemaCode, args.code, previous, prepared.options);
@@ -1054,6 +1143,19 @@ async function runFieldUpdate(session, args) {
     // confirm the write landed — the readback only named the field. Field
     // options are the form-interaction contract (ADR 0005), so read them back.
     const storedOptions = after !== undefined ? parseFieldOptionsForReadback(after.options) : undefined;
+    if (args.options !== undefined && storedOptions && typeof storedOptions === "object" && !Array.isArray(storedOptions)) {
+        const missed = Object.keys(args.options).filter((key) => !same(storedOptions[key] ?? null, prepared.options[key] ?? null));
+        if (missed.length > 0) {
+            throw new ToolRefusalError({
+                status: "refused",
+                blocker: "field-options-immutable",
+                schemaCode: args.schemaCode,
+                code: args.code,
+                fields: missed.map((key) => `options.${key}`),
+                message: `field.update 的 options.${missed.join("、")} 经此面提交后未生效；options 属于不可经此面修改的字段配置。请按字段族契约使用 field.delete + field.create 重建，或走对应的表单/数据规则工具（不要把 DELIVERED 当成已生效）。`,
+            });
+        }
+    }
     // r32（真机复现：field.update propertyEmpty:true 回 ok/DELIVERED，field.list --full
     // 与 model.inspect 都看不到该值）：平台字段行读面（bizproperty/list 与
     // bizproperty/get）都不回 propertyEmpty，这是**只写属性**。不编造读回值：
@@ -1079,8 +1181,12 @@ async function runFieldUpdate(session, args) {
             face: "draft",
             impact,
             fieldPresent: after !== undefined,
-            ...(after?.name !== undefined ? { name: after.name } : {}),
-            ...(typeof after?.name_i18n === "string" ? { name_i18n: after.name_i18n } : {}),
+            ...(after?.name !== undefined || prepared.name !== undefined || record.name !== undefined || record.propertyName !== undefined
+                ? { name: after?.name ?? prepared.name ?? record.name ?? record.propertyName }
+                : {}),
+            ...(typeof after?.name_i18n === "string" || typeof prepared.nameI18n === "string" || typeof record.name_i18n === "string"
+                ? { name_i18n: after?.name_i18n ?? prepared.nameI18n ?? record.name_i18n }
+                : {}),
             ...(after?.type !== undefined || after?.propertyType !== undefined ? { type: after?.type ?? after?.propertyType } : {}),
             ...(hasReadBackPropertyEmpty ? { propertyEmpty: after?.propertyEmpty } : {}),
             committed: committedKeys,
@@ -1345,6 +1451,13 @@ export async function executeFieldPublish(session, args) {
     const preRead = await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "true" } });
     const prePublishedRows = wireRows(preRead.data);
     const prePublished = prePublishedRows.map(codeOf).filter((code) => code.length > 0);
+    // Older servers accept a dangling relation row and only reveal it as the
+    // misleading 300010 at model publish.  Inspect the draft before POST so an
+    // existing poisoned model gets the same field-specific diagnosis as create.
+    const relationCandidates = await modelSchemaCodes(session);
+    const relationFailure = relationPublishFailureMessage(wireRows((await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "false" } })).data), relationCandidates);
+    if (relationFailure)
+        throw new ToolRefusalError({ status: "refused", blocker: "relation-target-not-found", schemaCode: args.schemaCode, message: relationFailure, candidates: relationCandidates.slice(0, 5) });
     // r29e F10/F11：旧短路只看「code 在发布面存在」，改了 options 仍报
     // already-published + verification.ok（假绿）。再比草稿/发布 options 指纹；
     // 不一致就真发布。name/type 仍由 verifyFieldDetails 核对。

package/dist/lanes/model-contract.js

@@ -116,7 +116,7 @@ export const MODEL_LANE_CONTRACT = Object.freeze({
         }),
         configure_model: Object.freeze({
             scope: MODEL_SCOPE,
-            description: "High-level: create a model with one field (fieldCode/fieldName/propertyType, legacy) or N fields (fields:[{code,name,propertyType,choices?,relativeCode?,options?}]) and drive it to the structurally usable state (model.create → field.create×N → model-scoped field.publish), optionally drafting and publishing the default form in the same package (publishForm:true → form.draft → form.publish) and configuring the default list view (`listview:{fieldCodes,...}` → listview.configure). Resumable: if the model already exists in the application tree, the model.create step is SKIPPED (reported as `skipped:\"model-exists\"`) and the field/publish steps still run — it does not abort on a pre-existing model. Family gates run per field BEFORE the write permission gate; for the form-only path use configure_form.",
+            description: "High-level: create a model with one field (fieldCode/fieldName/propertyType, legacy) or N fields (fields:[{code,name,propertyType,choices?,relativeCode?,options?}]) and drive it to the structurally usable state (model.create → field.create×N → model-scoped field.publish), optionally drafting and publishing the default form in the same package (publishForm:true → form.draft → form.publish) and configuring the default list view (`listview:{fieldCodes,...}` → listview.configure). Resumable: if the model already exists, the readback declares `created:false` and `mergedChanges`; `createOnly:true` refuses with `model-already-exists`. Model code is tenant-global and cannot be reused across applications. Family gates run per field BEFORE the write permission gate; for the form-only path use configure_form.",
         }),
         "model.deleteMany": Object.freeze({
             scope: MODEL_SCOPE,