@stalfh233/omc-cli 0.4.102 → 0.5.0

package/dist/bench/discovery-cost-eval.js

@@ -128,6 +128,8 @@ async function runScenario(scenario) {
     };
 }
 export async function runDiscoveryCostBaseline() {
+    // r29（2026-10-29）：describe 重复提示读项目 ledger，组合测试顺序会改变它——测量面禁用保证字节确定性。
+    process.env.OMC_DESC_REPEAT_HINT = "0";
     const scenarios = [];
     for (const scenario of SCENARIOS)
         scenarios.push(await runScenario(scenario));

package/dist/cli.js

@@ -17,8 +17,8 @@ import { cmdModelPurge } from "./model-purge.js";
 import { environmentWritable, requiresProductionConfirmation } from "./environment-policy.js";
 import { CLI_EXIT_CODES, classifyResult, envelope, errorEnvelope, refusalText, requestId } from "./cli-contract.js";
 import { configureOutput, humanSummary, stripOutputFlags, writeEnvelope } from "./cli-output.js";
-import { beginUsage, completeUsage, ensureProjectIgnore, recordUsageOutput, usageReport } from "./usage-log.js";
-import { artifactFetchHint, artifactRoot, boundResult, emitInvalid, emitResult, emitTransportResult, outputBudget, readArtifact, withTransport, } from "./command-transport.js";
+import { beginUsage, completeUsage, currentUsageArgsDigest, ensureProjectIgnore, priorIdenticalSuccess, recordUsageOutput, usageReport } from "./usage-log.js";
+import { artifactFetchHint, artifactRoot, boundResult, emitInvalid, emitResult, emitThrown, emitTransportResult, outputBudget, readArtifact, withTransport, } from "./command-transport.js";
 import { CLI_DEFAULT_OUTPUT_BYTES, assertSafeOutputPath, pruneArtifacts } from "./artifacts.js";
 import { projectJsonPath, projectJsonPathFanout, projectResultExtract } from "./path-projection.js";
 import { basename, join, resolve } from "node:path";
@@ -44,8 +44,11 @@ import { planIntent, readbackIntent, applyIntent, intentWarnings } from "./inten
 import { listSkills, readSkill, readSkillOutline, readSkillSection, searchSkills } from "./skills.js";
 import { parseToolInput, ToolInputError } from "./tool-types.js";
 import { WireError, wireCall } from "./wire.js";
+import { DEFAULT_PULL_CONCURRENCY, GraphIndexAbsentError, GraphPullLockHeldError, MAX_PULL_CONCURRENCY, impactGraph, publishGraphPull, queryGraphReferences, readGraphStatus, searchGraphRules, } from "./graph.js";
 import { ENDPOINTS } from "./endpoints.js";
+import { makeToolContext } from "./context.js";
 import { cmdRollbackList, cmdRollbackPlan, cmdRollbackApply } from "./rollback.js";
+import { SessionManager } from "./session-manager.js";
 async function ask(question) {
     const rl = createInterface({ input: stdin, output: process.stderr });
     try {
@@ -879,8 +882,20 @@ function cmdDiscovery(kind, transport, value, options = {}) {
         // second identical read returns an artifact reference instead of the body.
         result = full ? (repeatFullDescribe(value ?? "", full) ?? full) : full;
     }
-    else
+    else {
         result = describeTool(registry, value ?? "");
+        // r28b 账本（2026-10-28）：describe rule.save×11 / form.publish×9——firstCall 教学后
+        // 仍反复全量 describe。同参数近期已 ok 时附降载提示，引导 --param/--example 精准取。
+        // 无项目 ledger（golden/repo 测试/一次性运行）时 priorIdenticalSuccess 返回
+        // undefined，输出保持 byte-stable。
+        if (result) {
+            const digest = currentUsageArgsDigest();
+            const prior = digest === undefined ? undefined : priorIdenticalSuccess(`describe ${String(value ?? "")}`, digest);
+            if (prior !== undefined && prior.count >= 1)
+                result.describeRepeatHint =
+                    `同参数 describe 近期已执行过 ${prior.count + 1} 次（含本次）。在找单个参数：omc describe ${String(value ?? "")} --param <参数名>（几百字节）；找可抄的完整例子：--example <配方id>；都不必重读整面`;
+        }
+    }
     if (!result) {
         // Name the closest candidates so a near-miss tool name does not cost a
         // guess-and-retry call (round-4 dogfood: `form.create` / `data.create` /
@@ -1029,6 +1044,106 @@ async function cmdIntentReadback(file, environment, transport) {
         return read.code;
     return emitResult(await readbackIntent(read.intent, environment), transport);
 }
+/**
+ * ADR-0008 — `omc graph` family: the local derived rule-graph index. A CLI
+ * management face like `intent`/`rollback`: NOT a call tool, not in the tool
+ * registry or `commands --json`. Results are candidate pointers only — plan /
+ * apply / readback keep reading the live baseline.
+ */
+async function cmdGraphPull(environment, concurrency, transport) {
+    const workers = concurrency ?? DEFAULT_PULL_CONCURRENCY;
+    if (!Number.isSafeInteger(workers) || workers < 1 || workers > MAX_PULL_CONCURRENCY)
+        return emitInvalid(transport, { message: `--concurrency 必须是 1–${MAX_PULL_CONCURRENCY} 的整数（平台负载有界；默认 ${DEFAULT_PULL_CONCURRENCY}）` });
+    const context = makeToolContext({ sessions: new SessionManager(new ConfigStore(defaultPaths())) });
+    try {
+        const session = await context.sessions.session(environment);
+        const data = await publishGraphPull(session, workers);
+        const edgesByKind = {};
+        for (const edge of data.edges)
+            edgesByKind[edge.kind] = (edgesByKind[edge.kind] ?? 0) + 1;
+        const gapsByKind = {};
+        for (const gap of data.gaps)
+            gapsByKind[gap.kind] = (gapsByKind[gap.kind] ?? 0) + 1;
+        return emitResult({
+            status: "ok",
+            environment: data.meta.environmentName,
+            applicationCode: data.meta.applicationCode,
+            identityFingerprint: data.meta.identityFingerprint,
+            pulledAtIso: data.meta.pulledAtIso,
+            scope: data.meta.scope,
+            freshness: data.gaps.length === 0 ? "complete" : "partial",
+            scanned: { models: data.scanned.models, rules: data.scanned.rules, datarules: data.scanned.datarules, views: data.scanned.views, ...(data.scanned.parseFailures > 0 ? { parseFailures: data.scanned.parseFailures } : {}) },
+            edges: edgesByKind,
+            ...(data.gaps.length > 0 ? { gaps: { count: data.gaps.length, byKind: gapsByKind } } : {}),
+            dbBytes: data.dbBytes,
+            timings: data.timings,
+            nextCommand: "omc graph references <kind> <code>",
+        }, transport);
+    }
+    catch (error) {
+        if (error instanceof GraphPullLockHeldError)
+            return emitResult({ status: "refused", blocker: "graph-pull-lock-held", message: error.message, nextCommand: "omc graph status" }, transport);
+        if (error instanceof WireError)
+            return emitResult({ status: "uncertain", reason: "wire-transport", message: `graph pull 中断（${error.message}）；索引未发布，重跑 omc graph pull --env <env>` }, transport);
+        return emitThrown(error, transport);
+    }
+}
+function cmdGraphReferences(kind, code, transport) {
+    if (!["service", "model", "field"].includes(kind))
+        return emitInvalid(transport, { message: "kind 必须是 service / model / field（同 rule.references 第一版边界）" });
+    try {
+        const result = queryGraphReferences(kind, code);
+        return emitResult({
+            status: "ok",
+            kind: result.kind,
+            code: result.code,
+            matches: result.matches,
+            index: result.index,
+            ...(result.note !== undefined ? { note: result.note } : {}),
+            ...(result.gapWarning !== undefined ? { gapWarning: result.gapWarning } : {}),
+        }, transport);
+    }
+    catch (error) {
+        if (error instanceof GraphIndexAbsentError)
+            return emitResult({ status: "refused", blocker: "graph-index-absent", message: error.message, nextCommand: "omc graph pull --env <env>" }, transport);
+        return emitThrown(error, transport);
+    }
+}
+function cmdGraphStatus(transport) {
+    try {
+        const status = readGraphStatus();
+        return emitResult({ status: "ok", index: status.index, dbBytes: status.dbBytes, gaps: status.gaps }, transport);
+    }
+    catch (error) {
+        if (error instanceof GraphIndexAbsentError)
+            return emitResult({ status: "refused", blocker: "graph-index-absent", message: error.message, nextCommand: "omc graph pull --env <env>" }, transport);
+        return emitThrown(error, transport);
+    }
+}
+function cmdGraphImpact(kind, code, transport) {
+    if (!["service", "model", "field"].includes(kind))
+        return emitInvalid(transport, { message: "kind 必须是 service / model / field（同 rule.references 第一版边界）" });
+    try {
+        const result = impactGraph(kind, code);
+        return emitResult({ status: "ok", ...result }, transport);
+    }
+    catch (error) {
+        if (error instanceof GraphIndexAbsentError)
+            return emitResult({ status: "refused", blocker: "graph-index-absent", message: error.message, nextCommand: "omc graph pull --env <env>" }, transport);
+        return emitThrown(error, transport);
+    }
+}
+function cmdGraphSearch(term, transport) {
+    try {
+        const result = searchGraphRules(term);
+        return emitResult({ status: "ok", ...result }, transport);
+    }
+    catch (error) {
+        if (error instanceof GraphIndexAbsentError)
+            return emitResult({ status: "refused", blocker: "graph-index-absent", message: error.message, nextCommand: "omc graph pull --env <env>" }, transport);
+        return emitThrown(error, transport);
+    }
+}
 /** Ticket 119 — `omc intent apply <plan-file>`: plan integrity + baseline drift gates, then serial execution through the EXISTING apply_changes machinery. */
 async function cmdIntentApply(planPath, options, transport) {
     return applyIntent(planPath, options, {
@@ -1714,6 +1829,25 @@ async function main() {
     intentCommand.command("readback <file>").option("--env <environment>").option("--max-output-bytes <bytes>").action(async (file, options) => {
         commandExitCode = await withTransport(options, request, (transport) => cmdIntentReadback(file, options.env, transport));
     });
+    // ADR-0008: local derived rule-graph index — CLI management face, not a call
+    // tool (so it stays out of `commands --json`/coverage by construction).
+    const graphCommand = command.command("graph").description("本地派生规则图索引（ADR-0008）：pull 全量重建（有界并发）/ references 离线引用 / impact 影响面 / search 规则全文 / status 完整性与新鲜度。候选定位器——不进 baseline/plan/写门禁");
+    graphCommand.command("pull").option("--env <environment>").option("--environment <environment>").option("--concurrency <n>", "并发 wire 读数（1–32，默认 16）：拉取已流水线化，墙钟 ≈ max(模型面,规则面)/并发 × 延迟；过高可能触发平台限流形成缺口").option("--max-output-bytes <bytes>").addHelpText("after", "\n只读远端（model.list → 每模型 rule.list+datarule.list → 每规则 rule.get，统一任务池流水线并发）+ 本地原子重建；不写环境、不占环境写锁。新鲜度随结果回报（complete|partial），查询走 graph references / impact / search。\n").action(async (options) => {
+        const parsed = options.concurrency === undefined ? undefined : Number.parseInt(String(options.concurrency), 10);
+        commandExitCode = await withTransport(options, request, (transport) => cmdGraphPull(options.environment ?? options.env, parsed, transport));
+    });
+    graphCommand.command("references <kind> <code>").option("--max-output-bytes <bytes>").addHelpText("after", "\n离线查询（零 wire）：kind = service|model|field，语义同 rule.references 第一版边界；结果带索引新鲜度与扫描缺口（有缺口时零命中不构成「无引用」证明）。\n").action(async (kind, code, options) => {
+        commandExitCode = await withTransport(options, request, (transport) => cmdGraphReferences(kind, code, transport));
+    });
+    graphCommand.command("impact <kind> <code>").option("--max-output-bytes <bytes>").addHelpText("after", "\n影响面（离线）：跳1=引用该编码的规则（同 references），跳2=这些规则还读写哪些 service/model/field——改前看爆炸半径。截断上限 50 规则×每类 20 码。\n").action(async (kind, code, options) => {
+        commandExitCode = await withTransport(options, request, (transport) => cmdGraphImpact(kind, code, transport));
+    });
+    graphCommand.command("search <term...>").option("--max-output-bytes <bytes>").addHelpText("after", "\n规则全文检索（code+name，FTS5，末词前缀匹配）：找到\"关于 X 的规则\"拿 code，再走 references/impact。中文需给全词或词首（如 报名*）。\n").action(async (term, options) => {
+        commandExitCode = await withTransport(options, request, (transport) => cmdGraphSearch(term.join(" "), transport));
+    });
+    graphCommand.command("status").option("--max-output-bytes <bytes>").action(async (options) => {
+        commandExitCode = await withTransport(options, request, (transport) => cmdGraphStatus(transport));
+    });
     // `--jq` expressions the shell split arrive as several tokens; re-join them.
     await command.parseAsync(joinSplitFlagValues(stripOutputFlags(argv), ["--jq"]));
     return commandExitCode;
@@ -1742,7 +1876,7 @@ main().then((code) => {
     // envelope (or, for `env --json`, their own JSON) and were printing a second
     // empty envelope after it (live 2026-10-23: `omc rollback apply` answered two
     // lines, violating the one-envelope stdout contract).
-    const ownsStdout = ["call", "script", "artifact", "commands", "describe", "contract", "capabilities", "capability", "next", "usage", "intent", "help", "form-default", "compute", "rule-when", "approval-flow", "model-scaffold", "model-purge", "rollback", "env", "--version", "-V"];
+    const ownsStdout = ["call", "script", "artifact", "commands", "describe", "contract", "capabilities", "capability", "next", "usage", "intent", "help", "form-default", "compute", "rule-when", "approval-flow", "model-scaffold", "model-purge", "rollback", "env", "graph", "--version", "-V"];
     if (ownsStdout.includes(argv[2] ?? "")) {
         completeUsage(code);
         finish(code);

package/dist/field-change.js

@@ -91,7 +91,7 @@ export function prepareFieldUpdate(input) {
             message: `子表字段 ${input.schemaCode}.${input.code} 不接受 options/choices/subFields。子表列就是 schemaCode=${input.code} 上的普通字段：增列用 field.create --args '{"schemaCode":"${input.code}","code":"<子列>",...}'，改列/删列用 field.update/field.delete（同 schemaCode），改完对父模型 field.publish 即发布`,
         });
     const currentOptions = decodeJsonObjectColumn(input.base.options, { invalid: "throw", array: "accept", object: "accept" }) ?? {};
-    const nextOptions = isChildTable
+    const rebuiltOptions = isChildTable
         ? currentOptions
         : ensureRelationDisplayFieldOptions(recordType, {
             ...currentOptions,
@@ -101,6 +101,22 @@ export function prepareFieldUpdate(input) {
                 ...(effectiveOptions ? { options: effectiveOptions } : {}),
             }),
         });
+    // 2026-10-29 防御（治豪 issue 的 optionsSet 覆盖风险）：带 choices 更新选项族时
+    // optionsSet 走保留式合并——以服务端原文 optionsSet 为基线，只换 custom 条目，
+    // optionStructure/treeSelect/businessModel 等未声明键（含跨版本导入态）一律继承，
+    // 不整体重建。锚定线（8.6/1.1.25）实测无此形状，纯防御。
+    const nextOptions = isChildTable
+        ? currentOptions
+        : input.choices !== undefined
+            && rebuiltOptions.optionsSet !== undefined
+            && currentOptions.optionsSet !== undefined
+            && currentOptions.optionsSet !== null
+            && typeof currentOptions.optionsSet === "object"
+            ? {
+                ...rebuiltOptions,
+                optionsSet: { ...currentOptions.optionsSet, ...rebuiltOptions.optionsSet },
+            }
+            : rebuiltOptions;
     if (!isChildTable && !effectiveOptions && !input.choices)
         Object.assign(nextOptions, currentOptions);
     if (!isChildTable) {

package/dist/graph.js

@@ -0,0 +1,734 @@
+import { createRequire } from "node:module";
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { joinConfigRoot } from "./command-transport.js";
+import { decodeJsonColumn, JSON_COLUMN_NULL_COALESCE } from "./json-column.js";
+import { ENDPOINTS } from "./endpoints.js";
+import { flattenTreeRows, resolveApplicationCode, sha256 } from "./support.js";
+import { wireCall, wireRows } from "./wire.js";
+/**
+ * `node:sqlite` must stay OUT of the CLI's startup module graph: a static
+ * import emits the ExperimentalWarning during ESM linking, before any user
+ * code (including the stderr filter cli.ts installs as its first import) can
+ * run — that is why omc-core is lazily loaded too (sqlite-warning-filter.ts /
+ * omc-core-lazy.ts). Load it on first use, inside a command.
+ */
+let sqliteModule;
+function nodeSqlite() {
+    if (sqliteModule === undefined)
+        sqliteModule = createRequire(import.meta.url)("node:sqlite");
+    return sqliteModule;
+}
+/**
+ * ADR-0008 — the local derived rule-graph index.
+ *
+ * `rule.references` treats the r23 enumeration storm (171 rule.get calls) but
+ * re-scans the whole platform on every invocation and swallows per-model read
+ * failures, so a repeat question pays full wire cost again and its zero-hit
+ * answer can be a silent false negative. This module materializes the same
+ * walk ONCE into a local SQLite index:
+ *
+ * - scope: current-effective business rule graphs only (model.list → rule.list
+ *   rows → businessRuleGet per row id — the exact wire reads rule.references
+ *   makes; rows from the list face are current, so no stale-row double-read);
+ * - edges are api-fact only, extracted with rule.references' matching
+ *   semantics (service/model/field — see extractReferenceEdges);
+ * - fail-closed completeness: every swallowed read/parse failure is a recorded
+ *   gap; a zero-hit answer over a gapped index never claims "no references";
+ * - derived locator, never authority: results are candidate pointers; plan /
+ *   apply / readback keep reading the live baseline;
+ * - no raw payloads persist: whitelisted rule columns + graph sha256 + edges;
+ * - identity-bound: meta carries the canonical environment identity
+ *   fingerprint (which includes baseUrl/enterpriseId/applicationCode by
+ *   construction — it is NOT a config-content fingerprint and never certifies
+ *   "config unchanged"; freshness is complete|partial|unknown only);
+ * - each pull rebuilds wholesale into a staging DB and publishes atomically;
+ *   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 STALE_LOCK_MS = 15 * 60 * 1000;
+export const DEFAULT_PULL_CONCURRENCY = 16;
+export const MAX_PULL_CONCURRENCY = 32;
+export class GraphIndexAbsentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GraphIndexAbsentError";
+    }
+}
+export class GraphPullLockHeldError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GraphPullLockHeldError";
+    }
+}
+export function graphDbPath() {
+    return join(joinConfigRoot(), ".omc", "graph", "graph.db");
+}
+/**
+ * Extract api-fact reference edges from one rule's stored node graph. The
+ * matching mirrors `rule.references` exactly (businessrule.ts) so the index and
+ * the live scan answer the same question; anything rule.references cannot see
+ * (condition leaves, datarules — its v1 boundary) is equally invisible here.
+ */
+export function extractReferenceEdges(schemaCode, ruleCode, nodes) {
+    const edges = [];
+    const push = (kind, code, node, via) => {
+        if (code === "")
+            return;
+        edges.push({
+            kind,
+            code,
+            schemaCode,
+            ruleCode,
+            nodeCode: String(node.nodeCode ?? ""),
+            nodeType: String(node.nodeType ?? ""),
+            via,
+        });
+    };
+    for (const node of nodes) {
+        const mapping = node.methodMapping;
+        if (node.nodeType === "BIZ_ACTION" && mapping) {
+            push("service", String(mapping.serviceCode ?? ""), node, "methodMapping.serviceCode");
+        }
+        if (["CREATE", "UPDATE", "DELETE"].includes(String(node.nodeType ?? ""))) {
+            push("model", String(node.targetObjectCode ?? ""), node, "targetObjectCode");
+            if (Array.isArray(node.dataActions))
+                for (const action of node.dataActions)
+                    push("field", String(action.targetDataItem ?? ""), node, "dataActions.targetDataItem");
+        }
+        if (mapping) {
+            push("model", String(mapping.schemaCode ?? ""), node, "methodMapping.schemaCode");
+            for (const [key, label] of [["inputMappings", "inputMappings.bizCode"], ["outputMappings", "outputMappings.bizCode"]]) {
+                if (Array.isArray(mapping[key]))
+                    for (const row of mapping[key])
+                        if (String(row.bizCode ?? "") !== "" && (row.codeType === undefined || row.codeType === 1))
+                            push("field", String(row.bizCode), node, label);
+            }
+        }
+    }
+    return edges;
+}
+/**
+ * datarule face (phase 2): `dataRuleList` is one call per model and the LIST
+ * rows already carry the target fields (`propertyCodes`) and the stored
+ * `options` (formulas/conditions with `{field}` tokens) — no per-rule get.
+ * Target codes are api-fact field edges; `{token}` inside serialized options
+ * is the same class of stored-config reference (the braces are the platform's
+ * own field-reference syntax, cf. formulaFromEditorText).
+ */
+export function extractDataRuleEdges(schemaCode, row) {
+    const targets = Array.isArray(row.propertyCodes) ? row.propertyCodes.map((code) => String(code)) : typeof row.propertyCode === "string" && row.propertyCode !== "" ? [row.propertyCode] : [];
+    const edges = [];
+    const locator = targets.join("+");
+    for (const code of targets)
+        edges.push({ kind: "field", code, schemaCode, ruleCode: "", nodeCode: locator, nodeType: "datarule", via: "datarule.targets" });
+    const tokens = new Set();
+    try {
+        for (const token of JSON.stringify(row.options ?? {}).matchAll(/\{([A-Za-z0-9_.-]+)\}/g))
+            tokens.add(token[1]);
+    }
+    catch {
+        // options stringify never throws; guard anyway
+    }
+    for (const code of tokens)
+        edges.push({ kind: "field", code, schemaCode, ruleCode: "", nodeCode: locator, nodeType: "datarule", via: "datarule.options-token" });
+    return edges;
+}
+/**
+ * listview face (phase 2b): `listQueryList` is one call per model but carries
+ * only code/name — the column/sort/condition field references live in
+ * `listQueryGet` per view (queryColumns/querySorts/queryConditions
+ * propertyCode; the same projector listview.get reads back). Views are
+ * always-live (no draft lifecycle), so a get is the current state.
+ */
+export function extractListViewEdges(schemaCode, viewCode, model) {
+    const edges = [];
+    const push = (code, via) => {
+        if (typeof code === "string" && code !== "")
+            edges.push({ kind: "field", code, schemaCode, ruleCode: "", nodeCode: viewCode, nodeType: "listview", via });
+    };
+    for (const column of Array.isArray(model.queryColumns) ? model.queryColumns : [])
+        push(column.propertyCode, "listview.columns");
+    for (const sort of Array.isArray(model.querySorts) ? model.querySorts : [])
+        push(sort.propertyCode, "listview.sorts");
+    for (const condition of Array.isArray(model.queryConditions) ? model.queryConditions : [])
+        push(condition.propertyCode, "listview.conditions");
+    return edges;
+}
+/**
+ * The full pull walk, PIPELINED: one shared bounded worker pool executes both
+ * task kinds — per-model face reads (rule.list + dataruleList) and per-rule
+ * graph reads. A model face completing submits its rule reads straight into
+ * the pool, so wall time ≈ max(modelFaces, ruleReads) / concurrency instead of
+ * the phased sum. Read failures are gaps, never silent, and per FACE: a model
+ * whose datarule list fails still contributes its business rules (gap kind
+ * `datarule-list`) and vice versa (`rule-list`). Output is sorted so the
+ * published DB is byte-stable regardless of completion order.
+ */
+export async function pullRuleGraph(session, concurrency = DEFAULT_PULL_CONCURRENCY) {
+    const identity = session.environmentFingerprint();
+    const pulledAtIso = new Date().toISOString();
+    const totalStart = Date.now();
+    let listMs = 0;
+    let readMs = 0;
+    // Model enumeration mirrors the governed `model.list` tool exactly: the
+    // application tree flattened to BizModel rows. The bare `modelList` endpoint
+    // returns EMPTY data on a real platform (works only against the fake face)
+    // — using it here made the first live pull enumerate zero models and (pre-
+    // zero-guard) wedge the scheduler.
+    const applicationCode = await resolveApplicationCode(session, undefined).catch(() => "");
+    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 rules = [];
+    const edges = [];
+    const gaps = [];
+    let parseFailures = 0;
+    let dataruleCount = 0;
+    let viewCount = 0;
+    // --- shared scheduler: bounded starts, dynamic task submission ---
+    class Semaphore {
+        // Handoff semantics: a released slot is handed DIRECTLY to the head
+        // waiter (free is NOT incremented). The naive `free += 1; wake()` lets a
+        // task submitted in the microtask gap steal the slot, driving free
+        // negative — a waiter is then never woken, the pull promise never
+        // settles, and Node exits 0 SILENTLY when the event loop drains (no
+        // envelope, lock left behind). Direct handoff keeps the invariant.
+        free = concurrency;
+        waiters = [];
+        async acquire() {
+            if (this.free > 0) {
+                this.free -= 1;
+                return;
+            }
+            await new Promise((resolve) => this.waiters.push(resolve));
+        }
+        release() {
+            const waiter = this.waiters.shift();
+            if (waiter !== undefined) {
+                waiter();
+                return;
+            }
+            this.free += 1;
+        }
+    }
+    const semaphore = new Semaphore();
+    let inflight = 0;
+    let resolveAll = () => { };
+    const allDone = new Promise((resolve) => {
+        resolveAll = resolve;
+    });
+    const maybeDone = () => {
+        if (inflight === 0)
+            resolveAll();
+    };
+    const submit = (task) => {
+        inflight += 1;
+        void (async () => {
+            await semaphore.acquire();
+            try {
+                await task();
+            }
+            catch (error) {
+                gaps.push({ kind: "pull-task", ref: "internal", note: error instanceof Error ? error.message : String(error) });
+            }
+            finally {
+                semaphore.release();
+                inflight -= 1;
+                maybeDone();
+            }
+        })();
+    };
+    // --- task kinds ---
+    const runModelFace = async (schemaCode) => {
+        const faceStart = Date.now();
+        // Independent per-face reads: one face failing must not drop the other's
+        // rows (review: Promise.all here mis-filed datarule failures as rule gaps).
+        let rows = [];
+        let ruleListOk = true;
+        try {
+            rows = wireRows((await wireCall(session, { path: ENDPOINTS.businessRuleListBySchemaCode, query: { schemaCode } })).data);
+        }
+        catch (error) {
+            ruleListOk = false;
+            gaps.push({ kind: "rule-list", ref: schemaCode, note: error instanceof Error ? error.message : String(error) });
+        }
+        let dataruleRows = [];
+        try {
+            dataruleRows = wireRows((await wireCall(session, { path: ENDPOINTS.dataRuleList, query: { schemaCode } })).data);
+            dataruleCount += dataruleRows.length;
+            for (const row of dataruleRows)
+                edges.push(...extractDataRuleEdges(schemaCode, row));
+        }
+        catch (error) {
+            gaps.push({ kind: "datarule-list", ref: schemaCode, note: error instanceof Error ? error.message : String(error) });
+        }
+        try {
+            const views = wireRows((await wireCall(session, { path: ENDPOINTS.listQueryList, query: { schemaCode, clientType: "PC" } })).data);
+            for (const view of views) {
+                const viewCode = typeof view.code === "string" ? view.code : "";
+                if (viewCode === "")
+                    continue;
+                submit(() => runListViewRead(schemaCode, viewCode));
+            }
+        }
+        catch (error) {
+            gaps.push({ kind: "listview-list", ref: schemaCode, note: error instanceof Error ? error.message : String(error) });
+        }
+        listMs += Date.now() - faceStart;
+        if (!ruleListOk)
+            return;
+        const readSubmit = Date.now();
+        let queued = 0;
+        for (const row of rows) {
+            const ruleCode = String(row.code ?? "");
+            const ruleId = row.id;
+            if (ruleCode === "" || typeof ruleId !== "string" || ruleId === "") {
+                gaps.push({ kind: "rule-row-id", ref: `${schemaCode}/${ruleCode || "?"}` });
+                continue;
+            }
+            queued += 1;
+            submit(() => runRuleRead(schemaCode, ruleCode, ruleId));
+        }
+        if (queued > 0)
+            readMs += Date.now() - readSubmit;
+    };
+    const runRuleRead = async (schemaCode, ruleCode, ruleId) => {
+        const start = Date.now();
+        try {
+            const record = (await wireCall(session, { path: ENDPOINTS.businessRuleGet, query: { id: ruleId } })).data;
+            if (!record) {
+                gaps.push({ kind: "rule-get", ref: `${schemaCode}/${ruleCode}`, note: "empty readback" });
+                return;
+            }
+            const nodes = decodeJsonColumn(record.node, JSON_COLUMN_NULL_COALESCE);
+            if (!Array.isArray(nodes)) {
+                parseFailures += 1;
+                gaps.push({ kind: "rule-graph-parse", ref: `${schemaCode}/${ruleCode}` });
+                return;
+            }
+            rules.push({
+                schemaCode,
+                ruleCode,
+                name: String(record.name ?? ruleCode),
+                enabled: typeof record.enabled === "boolean" ? record.enabled : null,
+                status: typeof record.status === "string" ? record.status : null,
+                defaultRule: typeof record.defaultRule === "boolean" ? record.defaultRule : null,
+                rowId: ruleId,
+                graphSha256: sha256({ nodes, routes: decodeJsonColumn(record.route, JSON_COLUMN_NULL_COALESCE) }),
+            });
+            edges.push(...extractReferenceEdges(schemaCode, ruleCode, nodes));
+        }
+        catch (error) {
+            gaps.push({ kind: "rule-get", ref: `${schemaCode}/${ruleCode}`, note: error instanceof Error ? error.message : String(error) });
+        }
+        finally {
+            readMs += Date.now() - start;
+        }
+    };
+    const runListViewRead = async (schemaCode, viewCode) => {
+        try {
+            const got = (await wireCall(session, { path: ENDPOINTS.listQueryGet, query: { schemaCode, code: viewCode, clientType: "PC" } })).data;
+            if (got === null || !got.id) {
+                gaps.push({ kind: "listview-get", ref: `${schemaCode}/${viewCode}`, note: "empty readback" });
+                return;
+            }
+            viewCount += 1;
+            edges.push(...extractListViewEdges(schemaCode, viewCode, got));
+        }
+        catch (error) {
+            gaps.push({ kind: "listview-get", ref: `${schemaCode}/${viewCode}`, note: error instanceof Error ? error.message : String(error) });
+        }
+    };
+    for (const schemaCode of schemaCodes)
+        submit(() => runModelFace(schemaCode));
+    // Zero-scope guard: with no models there are no tasks, so no finally ever
+    // calls maybeDone — awaiting allDone would wedge the pull until the event
+    // loop drained and Node exited 0 silently. Resolve explicitly.
+    maybeDone();
+    await allDone;
+    rules.sort((a, b) => (a.schemaCode === b.schemaCode ? a.ruleCode.localeCompare(b.ruleCode) : a.schemaCode.localeCompare(b.schemaCode)));
+    edges.sort((a, b) => a.kind === b.kind
+        ? a.code === b.code
+            ? a.schemaCode === b.schemaCode
+                ? a.ruleCode === b.ruleCode
+                    ? a.nodeCode === b.nodeCode
+                        ? a.via.localeCompare(b.via)
+                        : a.nodeCode.localeCompare(b.nodeCode)
+                    : a.ruleCode.localeCompare(b.ruleCode)
+                : a.schemaCode.localeCompare(b.schemaCode)
+            : a.code.localeCompare(b.code)
+        : a.kind.localeCompare(b.kind));
+    gaps.sort((a, b) => (a.kind === b.kind ? a.ref.localeCompare(b.ref) : a.kind.localeCompare(b.kind)));
+    return {
+        meta: {
+            schemaVersion: GRAPH_SCHEMA_VERSION,
+            scope: "businessrule",
+            identityFingerprint: identity,
+            environmentName: session.environmentName,
+            applicationCode: session.profile.applicationCode,
+            pulledAtIso,
+        },
+        rules,
+        edges,
+        gaps,
+        scanned: { models: schemaCodes.length, rules: rules.length, datarules: dataruleCount, views: viewCount, parseFailures },
+        timings: { listMs, readMs, totalMs: Date.now() - totalStart },
+    };
+}
+function ensureGraphDir() {
+    const dir = dirname(graphDbPath());
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}
+/**
+ * Cross-process pull lock: O_EXCL create; a lock older than STALE_LOCK_MS is
+ * considered abandoned and taken over. This is a LOCAL index lock — pull never
+ * writes the environment, so it must not touch the environment write lock.
+ */
+async function withGraphPullLock(run) {
+    ensureGraphDir();
+    const lockPath = `${graphDbPath()}.lock`;
+    const owner = `${process.pid} ${new Date().toISOString()}`;
+    let fd;
+    try {
+        try {
+            fd = openSync(lockPath, "wx");
+            writeFileSync(fd, owner);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            let stale = false;
+            try {
+                stale = Date.now() - statSync(lockPath).mtimeMs > STALE_LOCK_MS;
+            }
+            catch {
+                stale = false;
+            }
+            if (!stale)
+                throw new GraphPullLockHeldError("graph pull 已在进行（本地索引锁被占用）；稍后重试，或确认无进行中拉取后删除 <配置根>/.omc/graph/graph.db.lock");
+            rmSync(lockPath, { force: true });
+            try {
+                fd = openSync(lockPath, "wx");
+                writeFileSync(fd, owner);
+            }
+            catch (error) {
+                // Lost the stale-takeover race to another pull — still a lock refusal
+                // (exit 12), never a generic thrown error (exit 10).
+                if (error.code === "EEXIST")
+                    throw new GraphPullLockHeldError("graph pull 已在进行（陈旧锁接管竞争失败）；稍后重试");
+                throw error;
+            }
+        }
+        return await run();
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+        try {
+            unlinkSync(lockPath);
+        }
+        catch {
+            // already gone — another stale takeover won the race
+        }
+    }
+}
+/** Wholesalerebuild + atomic publish (staging file + rename), 0600. */
+export async function publishGraphPull(session, concurrency = DEFAULT_PULL_CONCURRENCY) {
+    try {
+        return await withGraphPullLock(async () => {
+            const data = await pullRuleGraph(session, concurrency);
+            const staging = `${graphDbPath()}.staging-${process.pid}`;
+            rmSync(staging, { force: true });
+            const DatabaseSyncCtor = nodeSqlite().DatabaseSync;
+            const db = new DatabaseSyncCtor(staging);
+            try {
+                // The index is a rebuildable cache: crash durability is worthless here,
+                // and the default per-transaction journal fsync costs MINUTES on a
+                // network filesystem (observed 165s wall for a 2s pull on NFS /vol1 —
+                // D-state in folio_wait_bit_common). One transaction + memory journal
+                // + synchronous=OFF makes the build effectively free.
+                db.exec("PRAGMA journal_mode=MEMORY; PRAGMA synchronous=OFF;");
+                db.exec(`BEGIN;
+        CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+        CREATE TABLE rules (
+          schema_code TEXT NOT NULL,
+          rule_code TEXT NOT NULL,
+          name TEXT,
+          enabled INTEGER,
+          status TEXT,
+          default_rule INTEGER,
+          row_id TEXT NOT NULL,
+          graph_sha256 TEXT NOT NULL,
+          PRIMARY KEY (schema_code, rule_code)
+        );
+        CREATE TABLE edges (
+          kind TEXT NOT NULL,
+          code TEXT NOT NULL,
+          schema_code TEXT NOT NULL,
+          rule_code TEXT NOT NULL,
+          node_code TEXT,
+          node_type TEXT,
+          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);
+      `);
+                const insertMeta = db.prepare("INSERT INTO meta (key, value) VALUES (?, ?)");
+                for (const [key, value] of Object.entries(data.meta))
+                    insertMeta.run(key, String(value));
+                const insertRule = db.prepare("INSERT INTO rules (schema_code, rule_code, name, enabled, status, default_rule, row_id, graph_sha256) VALUES (?, ?, ?, ?, ?, ?, ?, ?)");
+                for (const rule of data.rules)
+                    insertRule.run(rule.schemaCode, rule.ruleCode, rule.name, rule.enabled === null ? null : rule.enabled ? 1 : 0, rule.status, rule.defaultRule === null ? null : rule.defaultRule ? 1 : 0, rule.rowId, rule.graphSha256);
+                const insertEdge = db.prepare("INSERT INTO edges (kind, code, schema_code, rule_code, node_code, node_type, via) VALUES (?, ?, ?, ?, ?, ?, ?)");
+                for (const edge of data.edges)
+                    insertEdge.run(edge.kind, edge.code, edge.schemaCode, edge.ruleCode, edge.nodeCode, edge.nodeType, edge.via);
+                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);
+                // 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');
+      `);
+                db.exec("COMMIT;");
+            }
+            finally {
+                db.close();
+            }
+            chmodSync(staging, 0o600);
+            const dbBytes = statSync(staging).size;
+            renameSync(staging, graphDbPath());
+            return { ...data, dbBytes };
+        });
+    }
+    catch (error) {
+        // A failed build must not leave staging garbage next to the index.
+        rmSync(`${graphDbPath()}.staging-${process.pid}`, { force: true });
+        throw error;
+    }
+}
+function openGraphIndex() {
+    const dbPath = graphDbPath();
+    if (!existsSync(dbPath))
+        throw new GraphIndexAbsentError("没有本地规则图索引（<配置根>/.omc/graph/graph.db）；先运行 omc graph pull --env <env> 全量重建");
+    let db;
+    try {
+        const DatabaseSyncCtor = nodeSqlite().DatabaseSync;
+        db = new DatabaseSyncCtor(dbPath, { readOnly: true });
+        const meta = {};
+        for (const row of db.prepare("SELECT key, value FROM meta").all())
+            meta[row.key] = row.value;
+        if (meta.schemaVersion !== GRAPH_SCHEMA_VERSION)
+            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 edgeRows = db.prepare("SELECT kind, COUNT(*) AS n FROM edges GROUP BY kind").all();
+        const edges = {};
+        for (const row of edgeRows)
+            edges[row.kind] = row.n;
+        const gapRows = db.prepare("SELECT kind, COUNT(*) AS n FROM gaps GROUP BY kind").all();
+        const byKind = {};
+        let gapCount = 0;
+        for (const row of gapRows) {
+            byKind[row.kind] = row.n;
+            gapCount += row.n;
+        }
+        return {
+            db,
+            summary: {
+                environmentName: meta.environmentName ?? "",
+                applicationCode: meta.applicationCode ?? "",
+                identityFingerprint: meta.identityFingerprint ?? "",
+                pulledAtIso: meta.pulledAtIso ?? "",
+                freshness: gapCount === 0 ? "complete" : "partial",
+                models: modelCount,
+                rules: ruleCount,
+                edges,
+                gaps: { count: gapCount, byKind },
+            },
+        };
+    }
+    catch (error) {
+        db?.close();
+        throw error instanceof GraphIndexAbsentError ? error : new GraphIndexAbsentError(`索引不可读（schema 不匹配或文件损坏）：${error instanceof Error ? error.message : String(error)}；重跑 omc graph pull`);
+    }
+}
+export function queryGraphReferences(kind, code) {
+    const { db, summary } = openGraphIndex();
+    try {
+        const rows = db
+            .prepare("SELECT schema_code, rule_code, node_code, node_type, via FROM edges WHERE kind = ? AND code = ? ORDER BY schema_code, rule_code, node_code, via")
+            .all(kind, code);
+        const matches = rows.map((row) => ({
+            schemaCode: row.schema_code,
+            ruleCode: row.rule_code,
+            nodeCode: row.node_code ?? "",
+            nodeType: row.node_type ?? "",
+            via: row.via,
+        }));
+        const gapped = summary.gaps.count > 0;
+        return {
+            kind,
+            code,
+            matches,
+            index: summary,
+            ...(matches.length === 0
+                ? {
+                    note: gapped
+                        ? "零命中，但索引存在扫描缺口——不可作为「无引用」证明；先 omc graph pull 重建再查"
+                        : "零命中=索引覆盖范围内没有引用它（规则面：service→methodMapping.serviceCode；model→targetObjectCode/methodMapping.schemaCode；field→dataActions.targetDataItem/映射 bizCode；数据规则面：propertyCodes 目标与 options {字段} 引用；视图面：列/排序/条件的 propertyCode。不含规则条件叶子/流程绑定）",
+                }
+                : {}),
+            ...(gapped
+                ? { gapWarning: `索引有 ${summary.gaps.count} 个扫描缺口（${Object.entries(summary.gaps.byKind).map(([k, v]) => `${k}:${v}`).join(", ")}）；命中列表可能不完整` }
+                : {}),
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+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 };
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Bounded FTS5 lookup over rule code + name — the "find the rule about X"
+ * entry point (references/impact need an exact code; search gets you the
+ * code). Tokens are quoted (no FTS syntax injection); the LAST token becomes
+ * 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) {
+    const { db, summary } = openGraphIndex();
+    try {
+        const tokens = term.trim().split(/\s+/).filter((token) => token !== "");
+        let matches = [];
+        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);
+            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: [] };
+                for (const edge of refsFor.all(row.schema_code, row.rule_code))
+                    if (edge.kind in refs)
+                        refs[edge.kind].push(edge.code);
+                return {
+                    schemaCode: row.schema_code,
+                    ruleCode: row.rule_code,
+                    name: row.name ?? "",
+                    enabled: row.enabled === null ? null : row.enabled === 1,
+                    status: row.status,
+                    refs,
+                };
+            });
+        }
+        const gapped = summary.gaps.count > 0;
+        return {
+            term,
+            rules: matches,
+            index: summary,
+            ...(matches.length === 0
+                ? { note: tokens.length === 0 ? "检索词为空" : "没有命中规则（code+name 全文；引用检索用 references/impact <kind> <code>）" }
+                : {}),
+            ...(gapped ? { gapWarning: `索引有 ${summary.gaps.count} 个扫描缺口；命中列表可能不完整` } : {}),
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Reverse blast radius over the reference edges: hop 1 = rules referencing the
+ * given code (what `references` answers), hop 2 = everything those rules touch
+ * (services/models/fields). "Change field X → these rules fire, and they also
+ * read/write these codes — verify those too." Bounded: 50 rules, 20 codes per
+ * kind; the same fail-closed gap semantics as references apply.
+ */
+export function impactGraph(kind, code) {
+    const { db, summary } = openGraphIndex();
+    try {
+        const hop1 = db
+            .prepare("SELECT DISTINCT schema_code, rule_code FROM edges WHERE kind = ? AND code = ? AND node_type NOT IN ('datarule', 'listview') ORDER BY schema_code, rule_code LIMIT 51")
+            .all(kind, code);
+        const dataruleHits = db
+            .prepare("SELECT DISTINCT schema_code, node_code AS targets, via FROM edges WHERE kind = ? AND code = ? AND node_type = 'datarule' ORDER BY schema_code, node_code, via LIMIT 21")
+            .all(kind, code);
+        const listViewHits = db
+            .prepare("SELECT DISTINCT schema_code, node_code AS view_code, via FROM edges WHERE kind = ? AND code = ? AND node_type = 'listview' ORDER BY schema_code, node_code, via LIMIT 21")
+            .all(kind, code);
+        const capped = hop1.length > 50;
+        const refsFor = db.prepare("SELECT kind, code, via FROM edges WHERE schema_code = ? AND rule_code = ? AND node_type <> 'datarule' ORDER BY kind, code, via");
+        const ruleName = db.prepare("SELECT name FROM rules WHERE schema_code = ? AND rule_code = ?");
+        const services = new Set();
+        const models = new Set();
+        const fields = new Set();
+        const rules = hop1.slice(0, 50).map((row) => {
+            const via = [];
+            const touches = { service: [], model: [], field: [] };
+            for (const edge of refsFor.all(row.schema_code, row.rule_code)) {
+                if (edge.kind === kind && edge.code === code) {
+                    if (!via.includes(edge.via))
+                        via.push(edge.via);
+                    continue; // the queried code itself is not "additional blast radius"
+                }
+                const bucket = touches[edge.kind];
+                if (bucket && !bucket.includes(edge.code))
+                    bucket.push(edge.code);
+                if (edge.kind === "service")
+                    services.add(edge.code);
+                else if (edge.kind === "model")
+                    models.add(edge.code);
+                else if (edge.kind === "field")
+                    fields.add(edge.code);
+            }
+            for (const key of ["service", "model", "field"]) {
+                const bucket = touches[key];
+                if (bucket.length > 20)
+                    touches[key] = bucket.slice(0, 20);
+            }
+            const name = ruleName.get(row.schema_code, row.rule_code)?.name ?? "";
+            return { schemaCode: row.schema_code, ruleCode: row.rule_code, name, matchedVia: via, touches };
+        });
+        const gapped = summary.gaps.count > 0;
+        return {
+            kind,
+            code,
+            rules,
+            datarules: dataruleHits.slice(0, 20).map((hit) => ({ schemaCode: hit.schema_code, targets: hit.targets ?? "", via: hit.via })),
+            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,
+            ...(hop1.length === 0 && dataruleHits.length === 0 && listViewHits.length === 0
+                ? {
+                    note: gapped
+                        ? "零命中，但索引存在扫描缺口——不可作为「无影响」证明；先 omc graph pull 重建再查"
+                        : "零命中=索引覆盖范围内没有引用它（规则面+数据规则面+视图列/排序/条件面；流程绑定暂不在索引内）",
+                }
+                : {}),
+            ...(capped || dataruleHits.length > 20 || listViewHits.length > 20
+                ? { truncated: true, note: `命中超过上限已截断（规则 50/实际 ${hop1.length}，数据规则 20/实际 ${dataruleHits.length}，视图 20/实际 ${listViewHits.length}）；完整规则清单用 references` }
+                : {}),
+            ...(gapped ? { gapWarning: `索引有 ${summary.gaps.count} 个扫描缺口（${Object.entries(summary.gaps.byKind).map(([k, v]) => `${k}:${v}`).join(", ")}）；影响面可能不完整` } : {}),
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+//# sourceMappingURL=graph.js.map

package/dist/lanes/businessrule.js

@@ -4,6 +4,7 @@ import { capabilityArg, environmentArg } from "../args.js";
 import { governedRead } from "../read.js";
 import { writeTool } from "../write.js";
 import { decodeJsonColumn, JSON_COLUMN_NULL_COALESCE } from "../json-column.js";
+import { flattenTreeRows, resolveApplicationCode } from "../support.js";
 import { executeRuleSaveWrite, ruleNodeGraphArg } from "../rule-support.js";
 import { defineTool, ToolInputError, ToolRefusalError } from "../tool-types.js";
 import { resolveRuleRowId } from "../identity.js";
@@ -135,8 +136,13 @@ export function registerBusinessRuleLane(tools) {
             // schema×ruleCode 组合（171 次 rule.get / 229KB）。没有引用检索面时，
             // 全库枚举是理性选择——所以给它一个。客户端聚合：模型清单 → 每模型
             // rule.list → 每规则 rule.get → 图内匹配，一次调用、只回命中行。
+            // Model enumeration mirrors `model.list`: the bare modelList endpoint
+            // returns EMPTY rows on a real platform (live 2026-10-29: a full scan
+            // "found" 0 models → false zero-hit), so walk the application tree.
             const scoped = args.schemaCodes === undefined
-                ? wireRows((await wireCall(session, { path: ENDPOINTS.modelList })).data).map((row) => String(row.schemaCode ?? "")).filter((code) => code !== "")
+                ? flattenTreeRows(wireRows((await wireCall(session, { path: ENDPOINTS.applicationTree, query: { appCode: await resolveApplicationCode(session, undefined).catch(() => "") } })).data))
+                    .filter((row) => row.type === "BizModel" && typeof row.code === "string" && row.code !== "")
+                    .map((row) => String(row.code))
                 : (Array.isArray(args.schemaCodes) ? args.schemaCodes : [args.schemaCodes]);
             const wanted = args.code;
             const matches = [];

package/dist/recipes/field.js

@@ -277,8 +277,62 @@ const formulaAggregationCrossModel = Object.freeze({
     requiresEnvironmentDerivedIds: true,
     prerequisiteData: { source: "field.list(published:true) ×2（来源模型 + 目标模型）", fields: ["source.model", "source.dataItemCode", "source.matchField", "target.matchField"] },
 });
+/**
+ * r29（2026-10-29 中冶终轮）+ 用户领域知识：外部数据（企查查/NC 等）在表单上
+ * 「填表时即带出」的标准模式——两段式组合。此前三轮探针（r24/r28b/r29）都发明
+ * 了「按钮触发规则回写」的重方案，因为没人知道标准模式；r29 实证 GetList 规则
+ * 实时调接口替换数据源在 1.1.25 不成立（CREATE 节点被校验器禁止指向本模型），
+ * 但「数据段落表 + 表单段关联下拉查表带出」完全成立且是平台正解。
+ *
+ * 2026-10-29 用户定案修正：GetList/Load 规则**实时调接口也是成立的**——触发点是
+ * 填表时**前端发起**的关联控件查询链（接口方法配 frontEndExtensionEnable:true，
+ * 前端直调）；r29 判「不成立」是因为用 data.list（后端 REST 查询）验证，该链不
+ * 执行 BIZ_ACTION 出参替换。验证必须走门户填表（关键字回车→候选→选中带出）。
+ */
+const externalLookupModel = Object.freeze({
+    id: "external-lookup-model",
+    title: "外部数据映射模型：接口数据落表 + 关联单选下拉带出（填表时即映射）",
+    aliases: ["外部数据源", "接口映射模型", "企查查下拉", "关联带出", "映射模型", "外部数据带出"],
+    status: "requires-prior-readback",
+    tool: "field.create",
+    args: {
+        environment,
+        schemaCode: model,
+        code: "ext_lookup_ref",
+        name: "外部数据引用",
+        propertyType: "WORK_SHEET",
+        options: {
+            schemaCode: "<映射模型code>",
+            queryCode: "<映射模型code>",
+            displayField: "<映射模型显示字段>",
+            mappings: [{ source: "<映射模型.业务字段>", target: "<本模型.落点字段>" }],
+        },
+    },
+    preconditions: [
+        "映射模型已建且字段与接口返回字段一一对应（如 qcc_company: company_name/credit_code）",
+        "数据段已通：接口数据已能落进映射模型表（见 conditionalRequirements 第 1 条的三个已验证组合）",
+    ],
+    conditionalRequirements: [
+        "**数据段首选（平台标准模式，2026-10-29 playwright 门户实证定案）**：映射模型的 GetList/Load 规则挂 BIZ_ACTION 实时调接口（接口方法配 frontEndExtensionEnable:true）——门户关联控件**打开即触发**前端查询链→GetList 规则→BIZ_ACTION 实时调外部接口（引擎日志 bizBusService.invoke + 外部网关日志双侧铁证）。**验证必须走门户填表；data.list 后端查询不反映此链，别用它判死**（r29 曾据此误判不成立）。配置侧三个收尾点：① WORK_SHEET 字段必须带 relativeCode（仅 options.schemaCode 发布表单会 301015 关联业务模型为空）；② GetList 规则的 BIZ_ACTION 入参映射要接前端搜索词（实测未配词时 invoke 参数为空 {}）；③ 出参→列表行的映射配完候选才回显（未配时弹窗 Total 0 但接口已调）。「下拉框形态（输关键字回车查询）」是表单 attributes 层的控件形态设置，默认弹窗形态。备选（不需要实时时）：预置 Create/Update 规则落映射表 / TIMING 定时同步。图内「BIZ_ACTION→CREATE 落表→再查」回环在 1.1.25 不可表达，不要走这条岔路。",
+        "**表单段是平台原生能力**：关联单选指向映射模型后，门户上输入关键字回车即查映射表、选中即 mappings 带出——前台填表时映射自然出现，无需按钮/脚本。",
+        "下拉框形态（输入关键字回车查询而非弹窗选择）在表单 attributes 层配置（form.draft 改控件形态），不在字段 options。",
+        "映射模型表要有数据下拉才有选项——空表=空下拉；数据段先通再配表单段。",
+    ],
+    priorToolReferences: [
+        { tool: "model.create", args: { environment }, purpose: "建映射模型（字段与接口返回一一对应）" },
+        { tool: "rule.save", args: { environment }, purpose: "数据段规则（三选一，见 conditionalRequirements）" },
+    ],
+    dryRun: { supported: true, command: `omc call field.create --env ${environment} --dry-run --args '<recipe.args>'`, notes: "校验 WORK_SHEET options 与 mappings 形状" },
+    expectedReadback: { readback: { field: { propertyType: "WORK_SHEET", options: { mappings: [{ source: "<映射模型.业务字段>" }] } } }, next: ["field.publish", "form.draft（控件形态配下拉框）", "form.publish", "门户填表验证：输关键字回车→选中→字段带出"] },
+    refusalRecovery: [
+        { code: "field-family-options-invalid", action: "WORK_SHEET options 必带 schemaCode/queryCode/displayField；mappings 用数组或 JSON 字符串均可（CLI 就地归一）" },
+        ...commonRecovery,
+    ],
+    notes: "r29 终轮定案：此模式是「外部数据填表带出」的平台正解；按钮触发回写是下策（多一次交互且体验差）。映射模型数据段的三个组合全部基于已验证的出参回写三前提（平铺端点/预置规则上下文/data 触发）。",
+    requiresEnvironmentDerivedIds: true,
+});
 export const FIELD_METADATA = Object.freeze({
     "field.update": Object.freeze({ recipes: [fieldSerialNumber, formConditionalRequired, formAlwaysReadonly, formConditionalReadonly], relatedTools: ["field.list", "field.publish", "form.draft", "form.publish"] }),
-    "field.create": Object.freeze({ recipes: [numericTwoDecimals, dictionarySelection, childTable, businessModelDropdown, formulaAggregationCrossModel], relatedTools: ["dictionary.names", "dictionary.records", "discover_environment", "field.list", "field.publish", "form.draft", "configure_form", "form.publish"] }),
+    "field.create": Object.freeze({ recipes: [numericTwoDecimals, dictionarySelection, childTable, businessModelDropdown, formulaAggregationCrossModel, externalLookupModel], relatedTools: ["dictionary.names", "dictionary.records", "discover_environment", "field.list", "field.publish", "form.draft", "configure_form", "form.publish"] }),
 });
 //# sourceMappingURL=field.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stalfh233/omc-cli",
-  "version": "0.4.102",
+  "version": "0.5.0",
   "description": "CloudPivot 8.6 configuration capability CLI — governed, fail-closed, coverage-manifest bounded.",
   "type": "module",
   "bin": {
@@ -41,7 +41,9 @@
     "test:live-permission": "node conformance/live-permission-acceptance.mjs",
     "sandbox:dogfood": "node conformance/setup-dogfood-sandbox.mjs",
     "payload:report": "tsx scripts/payload-report.ts",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "build:fast": "tsc --project tsconfig.build.json --incremental",
+    "typecheck:fast": "tsc --noEmit --incremental --tsBuildInfoFile .typecheck.tsbuildinfo"
   },
   "engines": {
     "node": ">=20"
@@ -50,9 +52,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@stalfh233/omc-fake-platform": "0.4.102",
+    "@stalfh233/omc-fake-platform": "0.5.0",
     "commander": "14.0.3",
-    "omc-core": "0.4.102",
+    "omc-core": "0.5.0",
     "proper-lockfile": "4.1.2",
     "write-file-atomic": "6.0.0",
     "zod": "^3.23.8",

package/skills/omc-write-hazards.md

@@ -21,6 +21,7 @@ omc help omc-write-hazards
 - `form.draft rebuild:true` 会重建布局，但会保留已存在的非结构性控件 options；Sheet201 columns 以最新 subSchema 为准。
 - 空布局 `[]`/`{}` 默认拒绝；只有显式 `allowEmptyLayout:true` 才能清空。
 - **列数由 viewJson 行分组决定，不是 span**（2026-10-27 r24 真机实证）：`viewJson` 是行的数组，一行内 N 个 code 即 N 列；`span` 只是 24 栅格下的控件宽度。只把字段 `span` 改 8 而不动行分组 → 控件变窄但每行仍两个，不是三列。改列数必须同时改行分组（三列=每行 3 个 code，字段 span=8）→ `form.publish` → `form.get` 回读 viewJson 核对。系统字段行与业务字段行分开调整。
+- **下拉/单选/复选的选项在表单控件有两份独立副本**（2026-10-29 治豪 issue 同源事实，8.6/1.1.25 机制一致）：数据项 `options.optionsSet.custom` 之外，表单控件的 `options.options.custom` 与 `options.optionsSet.custom` 是独立副本（× draft/published 双版本）——**只改字段不重存表单，门户/设计器不会变**。标准生效链：`field.update`（选项）→ `field.publish` → `form.draft`（rebuild 重建控件同步副本）→ `form.publish`；验收以表单面回读为准，数据项一致 ≠ 表单生效。
 - **模型不支持跨应用迁移**（1.1.25 真机实证：`folder-other-application` 拒绝）：模型建错应用时走「新应用重建 + 关联引用改指 + 旧模型删除」，不存在物理迁移命令。
 - **流程编排器是线性的，无并行会签**（1.1.25 实证）：多部门会签只能建成顺序节点链；需求里的「并行会签」按顺序节点落地并在交付说明里披露。
 - **BIZ_ACTION 服务出参只认响应 JSON 根级平铺键**（p7/r26 双实证）：嵌套在信封里（如 `{data:{level}}`）静默映射不上、目标字段全空——先把这类判断列进方案：接口形态要在「平铺 vs 信封」间做选择时，需要回写本平台的出参一律平铺。外部系统本身回信封的，扩展整形转发或放弃出参回写。