@stalfh233/omc-cli 0.0.0-stage → 0.4.0

package/dist/lanes/dictionary-contract.js

@@ -0,0 +1,78 @@
+import { assertDescriptionCarries, assertLaneContract, behaviorBinding, CONTRACT_FAMILY, CONTRACT_REFERENCE_VERSION } from "./contract-support.js";
+import { LANES } from "./lane-ids.js";
+export const DICTIONARY_LANE_CONTRACT = Object.freeze({
+    lane: LANES.dictionary,
+    family: CONTRACT_FAMILY,
+    referenceVersion: CONTRACT_REFERENCE_VERSION,
+    endpoints: Object.freeze({
+        search: "dictionarySearch",
+        get: "dictionaryGet",
+        getByCode: "dictionaryGetByCode",
+        save: "dictionarySave",
+        updateStatus: "dictionaryUpdateStatus",
+        records: "dictionaryRecords",
+        recordsByCode: "dictionaryRecordsByCode",
+        enabledRecords: "dictionaryEnabledRecords",
+        enabledRecordsByCode: "dictionaryEnabledRecordsByCode",
+        parentRecords: "dictionaryParentRecords",
+        recordStatus: "dictionaryRecordStatus",
+        recordUsed: "dictionaryRecordUsed",
+        type: "dictionaryGetByType",
+        idAndNames: "dictionaryIdAndNames",
+        classes: "dictionaryClasses",
+        classDetail: "dictionaryClassDetail",
+        classSave: "dictionaryClassSave",
+        classDelete: "dictionaryClassDelete",
+        classDeleteBatch: "dictionaryClassDeleteBatch",
+    }),
+    wire: Object.freeze({
+        types: "KEY_VALUE=0, TREE=1",
+        save: "POST /api/api/data_dictionary/saveDictionary {id?,code,name,dictionaryType,classificationId?,records:[...]}",
+        record: "record {id?,code,name,name_i18n?,parentId?,status,dictionaryId?,sortKey,initialUsed?,children?}",
+        selectionDictionary: "optionsSet {optionsType:'dictionary',dictionary:{checkedDictionary,checkedDictionaryCode,valueText,dictionariesType,useDictionariesData}}",
+        selectionBusinessModel: "optionsSet {optionsType:'businessModel',businessModel:{schemaCode,sheetDataItem,modelName?,dataItemType?,orderByFields?,orderType?,conditions?}}",
+        relationFilters: "WORK_SHEET/MULT_WORK_SHEET options.searchFormula and options.conditions are JSON strings consumed by the form control",
+    }),
+    wireBindings: Object.freeze({
+        types: Object.freeze([behaviorBinding("test/dictionary.test.ts#dictionary.save sends KEY_VALUE records and dictionary.records reads enabled values", assertDictionaryContract)]),
+        save: Object.freeze([behaviorBinding("test/dictionary.test.ts#dictionary.save sends KEY_VALUE records and dictionary.records reads enabled values", assertDictionaryContract)]),
+        record: Object.freeze([behaviorBinding("test/dictionary.test.ts#dictionary.save preserves TREE children and dictionary option source emits the platform optionsSet", assertDictionaryContract)]),
+        selectionDictionary: Object.freeze([behaviorBinding("test/dictionary.test.ts#dictionary.save preserves TREE children and dictionary option source emits the platform optionsSet", assertDictionaryContract)]),
+        selectionBusinessModel: Object.freeze([behaviorBinding("test/dictionary.test.ts#dictionary.save preserves TREE children and dictionary option source emits the platform optionsSet", assertDictionaryContract)]),
+        relationFilters: Object.freeze([behaviorBinding("test/dictionary.test.ts#relation filters require JSON strings and are carried onto the relation control", assertDictionaryContract)]),
+    }),
+    evidence: Object.freeze([
+        "cp-sources/backend/decompiled-full/launcher-8.6.26/.../DataDictionaryController.java:157-410",
+        "cp-sources/backend/decompiled-full/launcher-8.6.26/.../DictionaryFacadeImpl.java:141-196",
+        "cp-sources/backend/decompiled-full/launcher-8.6.26/.../SchemaAnalyzer.java:349-454",
+        "cp-sources/frontend-dist/admin/js/30525.0fa42d55.js",
+        "packages/omc-cli/test/dictionary.test.ts",
+    ]),
+    tools: Object.freeze({
+        "dictionary.list": Object.freeze({ scope: "dictionary list", description: "分页读取数据字典（data_dictionary/searchDictionary），返回字典元数据。" }),
+        "dictionary.get": Object.freeze({ scope: "dictionary read", description: "按 id 或 code 读取数据字典及其元数据。" }),
+        "dictionary.records": Object.freeze({ scope: "dictionary records read", description: "读取字典记录；支持按 id/code、启用状态和 parentId 读取，保留树形 children。" }),
+        "dictionary.save": Object.freeze({ scope: "dictionary save", description: "创建或更新数据字典及记录（data_dictionary/saveDictionary）；KEY_VALUE=0，TREE=1，写入前需审批。" }),
+        "dictionary.status": Object.freeze({ scope: "dictionary status", description: "启用或停用字典或字典记录；停用字典时运行时不会返回选项。" }),
+        "dictionary.class": Object.freeze({ scope: "dictionary classification", description: "读取、新建、删除字典分类并维护分类关联字典。" }),
+        "dictionary.usage": Object.freeze({ scope: "dictionary record usage", description: "批量设置字典记录 initialUsed 使用状态；记录新增/更新仍随 dictionary.save.records。" }),
+        "dictionary.type": Object.freeze({ scope: "dictionary type read", description: "按 dictionaryType 读取字典。" }),
+        "dictionary.names": Object.freeze({ scope: "dictionary names read", description: "读取字典 id/name 摘要。" }),
+        "dictionary.parent": Object.freeze({ scope: "dictionary parent records read", description: "读取树型字典指定父节点的直接子记录。" }),
+        "dictionary.classes": Object.freeze({ scope: "dictionary classes", description: "读取字典分类及分类详情。" }),
+        "dictionary.class.save": Object.freeze({ scope: "dictionary class save", description: "创建或更新字典分类。" }),
+        "dictionary.class.delete": Object.freeze({ scope: "dictionary class delete", description: "删除一个或多个未被使用的字典分类。" }),
+    }),
+});
+export function assertDictionaryContract() {
+    assertLaneContract(DICTIONARY_LANE_CONTRACT);
+    assertDescriptionCarries(DICTIONARY_LANE_CONTRACT, "dictionary.save", ["saveDictionary", "KEY_VALUE=0", "TREE=1"]);
+    assertDescriptionCarries(DICTIONARY_LANE_CONTRACT, "dictionary.records", ["children"]);
+    assertDescriptionCarries(DICTIONARY_LANE_CONTRACT, "dictionary.class", ["分类"]);
+    assertDescriptionCarries(DICTIONARY_LANE_CONTRACT, "dictionary.usage", ["initialUsed"]);
+    if (!String(DICTIONARY_LANE_CONTRACT.wire.selectionDictionary).includes("checkedDictionary"))
+        throw new Error("dictionary contract must pin dictionary option keys");
+    if (!String(DICTIONARY_LANE_CONTRACT.wire.selectionBusinessModel).includes("sheetDataItem"))
+        throw new Error("dictionary contract must pin business-model option keys");
+}
+//# sourceMappingURL=dictionary-contract.js.map

package/dist/lanes/dictionary-coverage.js

@@ -0,0 +1,24 @@
+import { claim, declareLaneCoverage } from "./coverage-declaration.js";
+import { DICTIONARY_LANE_CONTRACT } from "./dictionary-contract.js";
+const T = DICTIONARY_LANE_CONTRACT.tools;
+export const DICTIONARY_COVERAGE = declareLaneCoverage(DICTIONARY_LANE_CONTRACT.lane, [
+    {
+        capability: "Data dictionary lifecycle and field option sources",
+        evidence: ["packages/omc-cli/src/lanes/dictionary.ts", "packages/omc-cli/test/dictionary.test.ts"],
+        tools: [
+            claim("dictionary.list", T["dictionary.list"].scope),
+            claim("dictionary.type", T["dictionary.type"].scope),
+            claim("dictionary.names", T["dictionary.names"].scope),
+            claim("dictionary.get", T["dictionary.get"].scope),
+            claim("dictionary.records", T["dictionary.records"].scope),
+            claim("dictionary.parent", T["dictionary.parent"].scope),
+            claim("dictionary.save", T["dictionary.save"].scope),
+            claim("dictionary.status", T["dictionary.status"].scope),
+            claim("dictionary.usage", T["dictionary.usage"].scope),
+            claim("dictionary.classes", T["dictionary.classes"].scope),
+            claim("dictionary.class.save", T["dictionary.class.save"].scope),
+            claim("dictionary.class.delete", T["dictionary.class.delete"].scope),
+        ],
+    },
+]);
+//# sourceMappingURL=dictionary-coverage.js.map

package/dist/lanes/dictionary.js

@@ -0,0 +1,235 @@
+import { z } from "zod";
+import { ENDPOINTS } from "../endpoints.js";
+import { capabilityArg, environmentArg } from "../args.js";
+import { governedRead } from "../read.js";
+import { writeTool } from "../write.js";
+import { defineTool, ToolRefusalError } from "../tool-types.js";
+import { wireCall, WireError } from "../wire.js";
+import { DICTIONARY_LANE_CONTRACT } from "./dictionary-contract.js";
+const LANE = DICTIONARY_LANE_CONTRACT.lane;
+const TOOLS = DICTIONARY_LANE_CONTRACT.tools;
+const dictionaryType = z.union([z.literal(0), z.literal(1)]).describe("KEY_VALUE=0 or TREE=1");
+const nameI18n = z.record(z.string(), z.unknown()).optional();
+const recordSchema = z.object({
+    id: z.string().optional(),
+    code: z.string().min(1),
+    name: z.string().min(1),
+    name_i18n: nameI18n,
+    parentId: z.string().nullable().optional(),
+    status: z.boolean().default(true),
+    dictionaryId: z.string().optional(),
+    sortKey: z.number().int().default(0),
+    initialUsed: z.boolean().optional(),
+}).passthrough();
+const recordsArg = z.array(recordSchema.extend({ children: z.array(recordSchema).optional() })).optional();
+function normalizeRecord(record, dictionaryId, parentId) {
+    const children = Array.isArray(record.children) ? record.children.map((child) => normalizeRecord(child, dictionaryId, String(record.id ?? parentId ?? "") || null)) : undefined;
+    return {
+        ...record,
+        ...(dictionaryId ? { dictionaryId } : {}),
+        ...(parentId !== undefined ? { parentId } : {}),
+        ...(children ? { children } : {}),
+        name_i18n: typeof record.name_i18n === "string" ? record.name_i18n : JSON.stringify(record.name_i18n ?? { "zh-CN": record.name, en: record.name }),
+        status: record.status !== false,
+        sortKey: Number.isInteger(record.sortKey) ? record.sortKey : 0,
+    };
+}
+function dictionaryView(value) {
+    const row = (value && typeof value === "object" ? value : {});
+    return {
+        id: row.id,
+        code: row.code,
+        name: row.name,
+        name_i18n: row.name_i18n,
+        dictionaryType: row.dictionaryType,
+        status: row.status,
+        sortKey: row.sortKey,
+        classificationId: row.classificationId,
+        classificationName: row.classificationName,
+    };
+}
+function recordsPage(value) {
+    const page = (value && typeof value === "object" ? value : {});
+    return {
+        totalElements: page.totalElements ?? 0,
+        totalPages: page.totalPages ?? 0,
+        content: Array.isArray(page.content) ? page.content : [],
+    };
+}
+function requireExactlyOne(id, code) {
+    if ((id ? 1 : 0) + (code ? 1 : 0) !== 1)
+        throw new ToolRefusalError({ status: "refused", blocker: "dictionary-target-required", message: "dictionary.get/records 必须且只能提供 id 或 code" });
+}
+export function registerDictionaryLane(tools) {
+    tools.push(defineTool({
+        name: "dictionary.list",
+        layer: "low",
+        kind: "read",
+        lane: LANE,
+        scope: TOOLS["dictionary.list"].scope,
+        description: TOOLS["dictionary.list"].description,
+        inputSchema: { environment: environmentArg, capability: capabilityArg, classificationId: z.string().optional(), searchWord: z.string().optional(), page: z.number().int().min(1).default(1), size: z.number().int().min(1).max(200).default(20), sortColumn: z.string().optional(), sortDirection: z.enum(["asc", "desc"]).optional() },
+        handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
+            const data = await wireCall(session, { path: ENDPOINTS.dictionarySearch, query: { classificationId: args.classificationId ?? "", searchWord: args.searchWord ?? "", page: String(args.page), size: String(args.size), sortColumn: args.sortColumn ?? "", sortDirection: args.sortDirection ?? "desc" } });
+            return { dictionaries: recordsPage(data.data) };
+        }),
+    }));
+    tools.push(defineTool({
+        name: "dictionary.type",
+        layer: "low",
+        kind: "read",
+        lane: LANE,
+        scope: TOOLS["dictionary.type"].scope,
+        description: TOOLS["dictionary.type"].description,
+        inputSchema: { environment: environmentArg, capability: capabilityArg, type: dictionaryType },
+        handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
+            const data = await wireCall(session, { path: ENDPOINTS.dictionaryGetByType, query: { type: String(args.type) } });
+            return { dictionaryType: args.type, dictionaries: Array.isArray(data.data) ? data.data.map(dictionaryView) : [] };
+        }),
+    }));
+    tools.push(defineTool({
+        name: "dictionary.names",
+        layer: "low",
+        kind: "read",
+        lane: LANE,
+        scope: TOOLS["dictionary.names"].scope,
+        description: TOOLS["dictionary.names"].description,
+        inputSchema: { environment: environmentArg, capability: capabilityArg },
+        handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
+            const data = await wireCall(session, { path: ENDPOINTS.dictionaryIdAndNames, query: {} });
+            return { dictionaries: Array.isArray(data.data) ? data.data.map(dictionaryView) : [] };
+        }),
+    }));
+    tools.push(defineTool({
+        name: "dictionary.get",
+        layer: "low",
+        kind: "read",
+        lane: LANE,
+        scope: TOOLS["dictionary.get"].scope,
+        description: TOOLS["dictionary.get"].description,
+        inputSchema: { environment: environmentArg, capability: capabilityArg, id: z.string().optional(), code: z.string().optional() },
+        handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
+            requireExactlyOne(args.id, args.code);
+            const data = await wireCall(session, { path: args.id ? ENDPOINTS.dictionaryGet : ENDPOINTS.dictionaryGetByCode, query: args.id ? { id: args.id } : { code: args.code } });
+            return { dictionary: dictionaryView(data.data) };
+        }),
+    }));
+    tools.push(defineTool({
+        name: "dictionary.records",
+        layer: "low",
+        kind: "read",
+        lane: LANE,
+        scope: TOOLS["dictionary.records"].scope,
+        description: TOOLS["dictionary.records"].description,
+        inputSchema: { environment: environmentArg, capability: capabilityArg, id: z.string().optional(), code: z.string().optional(), parentId: z.string().optional(), searchWord: z.string().optional(), enabledOnly: z.boolean().default(false), page: z.number().int().min(1).default(1), size: z.number().int().min(1).max(200).default(200) },
+        handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
+            requireExactlyOne(args.id, args.code);
+            if (args.parentId) {
+                const data = await wireCall(session, { path: ENDPOINTS.dictionaryParentRecords, query: { parentId: args.parentId } });
+                return { parentId: args.parentId, records: Array.isArray(data.data) ? data.data : [] };
+            }
+            if (args.enabledOnly) {
+                const dictionary = args.id ? { id: args.id } : (await wireCall(session, { path: ENDPOINTS.dictionaryGetByCode, query: { code: args.code } })).data;
+                const id = String(dictionary.id ?? "");
+                if (!id)
+                    throw new WireError("business", "dictionary code not found", 301001);
+                const data = await wireCall(session, { path: ENDPOINTS.dictionaryEnabledRecords, query: { dicId: id } });
+                return { dictionaryId: id, enabledOnly: true, records: Array.isArray(data.data) ? data.data : [] };
+            }
+            const path = args.code ? ENDPOINTS.dictionaryRecordsByCode : ENDPOINTS.dictionaryRecords;
+            const query = args.code
+                ? { code: args.code, searchWord: args.searchWord ?? "", page: String(args.page), size: String(args.size) }
+                : { id: args.id, searchWord: args.searchWord ?? "", page: String(args.page), size: String(args.size) };
+            const data = await wireCall(session, { path, query });
+            return { records: recordsPage(data.data) };
+        }),
+    }));
+    writeTool(tools, "dictionary.save", LANE, TOOLS["dictionary.save"].scope, TOOLS["dictionary.save"].description, {
+        id: z.string().optional(), code: z.string().min(1), name: z.string().min(1), name_i18n: nameI18n, dictionaryType, classificationId: z.string().optional(), sortKey: z.number().int().optional(), status: z.boolean().optional(), records: recordsArg,
+    }, async (session, args) => {
+        const existing = (await wireCall(session, { path: ENDPOINTS.dictionaryGetByCode, query: { code: args.code } })).data;
+        if (!args.id && existing && typeof existing === "object" && Object.keys(existing).length > 0)
+            throw new ToolRefusalError({ status: "refused", blocker: "dictionary-create-duplicate", code: args.code, message: `字典 ${args.code} 已存在；更新请传 id` });
+        const body = {
+            ...(args.id ? { id: args.id } : {}), code: args.code, name: args.name, name_i18n: JSON.stringify(args.name_i18n ?? { "zh-CN": args.name, en: args.name }), dictionaryType: args.dictionaryType,
+            classificationId: args.classificationId ?? "", sortKey: args.sortKey ?? 0, status: args.status ?? true,
+            records: (args.records ?? []).map((record) => normalizeRecord(record)),
+        };
+        const performed = await wireCall(session, { path: ENDPOINTS.dictionarySave, method: "POST", body });
+        const after = (await wireCall(session, { path: ENDPOINTS.dictionaryGetByCode, query: { code: args.code } })).data;
+        // The create/update response only carries the header; the records the caller
+        // just sent are invisible unless they make another call (dogfood R3). Read
+        // them back here so "the header saved" cannot be mistaken for "the records
+        // were verified".
+        let recordsReadback = { totalElements: 0, totalPages: 0, content: [] };
+        try {
+            const stored = (await wireCall(session, { path: ENDPOINTS.dictionaryEnabledRecordsByCode, query: { code: args.code } })).data;
+            const all = (await wireCall(session, { path: ENDPOINTS.dictionaryRecordsByCode, query: { code: args.code, searchWord: "", page: "1", size: "200" } })).data;
+            recordsReadback = { ...recordsPage(all), enabledCount: Array.isArray(stored) ? stored.length : 0 };
+        }
+        catch {
+            // best-effort: the save itself is already authoritative; a record-read
+            // failure must not turn a landed write into a failure.
+        }
+        return { performed: { errcode: performed.errcode }, readback: { present: Boolean(after && Object.keys(after).length > 0), dictionary: dictionaryView(after), records: recordsReadback } };
+    });
+    writeTool(tools, "dictionary.status", LANE, TOOLS["dictionary.status"].scope, TOOLS["dictionary.status"].description, {
+        target: z.enum(["dictionary", "record"]), id: z.string().min(1), status: z.boolean(),
+    }, async (session, args) => {
+        const path = args.target === "dictionary" ? ENDPOINTS.dictionaryUpdateStatus : ENDPOINTS.dictionaryRecordStatus;
+        const performed = await wireCall(session, { path, method: "POST", body: { id: args.id, status: args.status } });
+        return { performed: { errcode: performed.errcode }, readback: { id: args.id, status: args.status } };
+    });
+    writeTool(tools, "dictionary.usage", LANE, TOOLS["dictionary.usage"].scope, TOOLS["dictionary.usage"].description, {
+        ids: z.array(z.string().min(1)).min(1).max(1000),
+    }, async (session, args) => {
+        const performed = await wireCall(session, { path: ENDPOINTS.dictionaryRecordUsed, method: "POST", body: { id: args.ids.join(";") } });
+        return { performed: { errcode: performed.errcode, ids: args.ids }, readback: { ids: args.ids, initialUsed: true } };
+    });
+    tools.push(defineTool({
+        name: "dictionary.parent",
+        layer: "low",
+        kind: "read",
+        lane: LANE,
+        scope: TOOLS["dictionary.parent"].scope,
+        description: TOOLS["dictionary.parent"].description,
+        inputSchema: { environment: environmentArg, capability: capabilityArg, parentId: z.string().min(1) },
+        handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
+            const data = await wireCall(session, { path: ENDPOINTS.dictionaryParentRecords, query: { parentId: args.parentId } });
+            return { parentId: args.parentId, records: Array.isArray(data.data) ? data.data : [] };
+        }),
+    }));
+    tools.push(defineTool({
+        name: "dictionary.classes",
+        layer: "low",
+        kind: "read",
+        lane: LANE,
+        scope: TOOLS["dictionary.classes"].scope,
+        description: TOOLS["dictionary.classes"].description,
+        inputSchema: { environment: environmentArg, capability: capabilityArg, detail: z.boolean().default(false) },
+        handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
+            const data = await wireCall(session, { path: args.detail ? ENDPOINTS.dictionaryClassDetail : ENDPOINTS.dictionaryClasses, query: {} });
+            return { detail: args.detail, classes: Array.isArray(data.data) ? data.data : [] };
+        }),
+    }));
+    writeTool(tools, "dictionary.class.save", LANE, TOOLS["dictionary.class.save"].scope, TOOLS["dictionary.class.save"].description, {
+        id: z.string().optional(), name: z.string().min(1), dictionaryIds: z.array(z.string()).optional(), sortKey: z.number().int().optional(),
+    }, async (session, args) => {
+        const performed = await wireCall(session, { path: ENDPOINTS.dictionaryClassSave, method: "POST", body: { ...(args.id ? { id: args.id } : {}), name: args.name, dictionaryIds: args.dictionaryIds ?? [], sortKey: args.sortKey ?? 0 } });
+        // Read back the created/updated class so the caller (and the audit trail)
+        // gets its id, not just the name it sent.
+        const listed = (await wireCall(session, { path: ENDPOINTS.dictionaryClasses, query: {} })).data;
+        const classes = Array.isArray(listed) ? listed : [];
+        const saved = classes.find((entry) => entry.name === args.name && (args.id === undefined || entry.id === args.id)) ?? classes.find((entry) => entry.name === args.name);
+        return { performed: { errcode: performed.errcode }, readback: { present: saved !== undefined, id: saved?.id, name: args.name, dictionaryIds: args.dictionaryIds ?? [] } };
+    });
+    writeTool(tools, "dictionary.class.delete", LANE, TOOLS["dictionary.class.delete"].scope, TOOLS["dictionary.class.delete"].description, {
+        ids: z.array(z.string().min(1)).min(1),
+    }, async (session, args) => {
+        const path = args.ids.length === 1 ? ENDPOINTS.dictionaryClassDelete : ENDPOINTS.dictionaryClassDeleteBatch;
+        const body = args.ids.length === 1 ? { id: args.ids[0] } : { ids: args.ids };
+        const performed = await wireCall(session, { path, method: "POST", body });
+        return { performed: { errcode: performed.errcode, ids: args.ids }, readback: { absent: true, ids: args.ids } };
+    });
+}
+//# sourceMappingURL=dictionary.js.map

package/dist/lanes/environment-contract.js

@@ -0,0 +1,70 @@
+import { assertDescriptionCarries, assertLaneContract, behaviorBinding, CONTRACT_FAMILY, CONTRACT_REFERENCE_VERSION } from "./contract-support.js";
+import { LANES } from "./lane-ids.js";
+/**
+ * environment-governance wire facts (live-proven). The read-only discovery
+ * surface and the canonical fingerprint are the single source for the handler
+ * descriptions and the coverage declarations.
+ */
+export const ENVIRONMENT_WIRE = Object.freeze({
+    discoveryReads: "applicationList + applicationGroupList + applicationTree(appCode) + modelList(parentId='')",
+    readiness: "readiness {ready, blockers, preconditions, warnings, recovery, facts} derives from the same application/group/profile/version reads; no capability fan-out",
+    applicationScope: "lists every application the tenant exposes; applicationCode selects one and returns its folders/models",
+    portalVisibility: "group membership decides portal visibility: the portal renders NAMED groups; an app in the fallback group (code === 'all', case-insensitive) or with an unresolvable groupId is flagged portalHidden:true; move it with app.update {code, groupId}",
+    fingerprint: "canonical environment fingerprint (environment, origin, application, enterprise) from the authenticated session",
+});
+export const ENVIRONMENT_LANE_CONTRACT = Object.freeze({
+    lane: LANES.environment,
+    family: CONTRACT_FAMILY,
+    referenceVersion: CONTRACT_REFERENCE_VERSION,
+    endpoints: Object.freeze({
+        applicationList: "applicationList",
+        applicationGroupList: "applicationGroupList",
+        applicationTree: "applicationTree",
+        modelList: "modelList",
+    }),
+    wire: Object.freeze({
+        discoveryReads: ENVIRONMENT_WIRE.discoveryReads,
+        readiness: ENVIRONMENT_WIRE.readiness,
+        applicationScope: ENVIRONMENT_WIRE.applicationScope,
+        portalVisibility: ENVIRONMENT_WIRE.portalVisibility,
+        fingerprint: ENVIRONMENT_WIRE.fingerprint,
+    }),
+    wireBindings: Object.freeze({
+        discoveryReads: Object.freeze([behaviorBinding("test/discovery-group-visibility.test.ts#discover_environment exposes group membership and flags fallback-group apps", assertEnvironmentContract)]),
+        readiness: Object.freeze([behaviorBinding("test/ticket-04-environment-readiness.test.ts#discover_environment reports structured blockers when applications and groups are absent", assertEnvironmentContract)]),
+        applicationScope: Object.freeze([behaviorBinding("test/discovery-group-visibility.test.ts#discover_environment with applicationCode returns that app's models", assertEnvironmentContract)]),
+        portalVisibility: Object.freeze([behaviorBinding("test/discovery-group-visibility.test.ts#discover_environment fails closed: an unresolvable groupId is portalHidden", assertEnvironmentContract)]),
+        fingerprint: Object.freeze([behaviorBinding("test/lane-contracts.test.ts#environment lane contract pins the discovery/fingerprint wire", assertEnvironmentContract)]),
+    }),
+    evidence: Object.freeze([
+        "src/dbsweep.ts",
+        ".scratch/omc-route-wayfinder/leg2-closeout.md",
+        "packages/omc-cli/src/lanes/environment.ts",
+    ]),
+    tools: Object.freeze({
+        discover_environment: Object.freeze({
+            scope: "discovery fingerprint",
+            description: "发现应用、模型、字段与默认表单（只读）。默认列出全部应用及其门户分组归属；传入 applicationCode 时进入该应用并返回其下的模型。每个应用带 groupId/groupCode/groupName 与 portalHidden：落在兜底分组「全部」(code=all) 或分组解析不到的应用标 portalHidden:true——门户按具名分组渲染，这些应用在门户不可见，须用 app.update {code,groupId} 迁入具名分组。",
+        }),
+        "environment.fingerprint": Object.freeze({
+            scope: "fingerprint",
+            description: "Canonical environment fingerprint (environment, origin, application, enterprise).",
+        }),
+    }),
+});
+export function assertEnvironmentContract() {
+    assertLaneContract(ENVIRONMENT_LANE_CONTRACT);
+    assertDescriptionCarries(ENVIRONMENT_LANE_CONTRACT, "discover_environment", ["只读", "applicationCode", "模型", "分组", "portalHidden"]);
+    if (!ENVIRONMENT_WIRE.readiness.includes("no capability fan-out"))
+        throw new Error("environment contract must pin readiness as a bounded projection");
+    assertDescriptionCarries(ENVIRONMENT_LANE_CONTRACT, "environment.fingerprint", ["fingerprint", "environment"]);
+    if (!ENVIRONMENT_WIRE.discoveryReads.includes("applicationList"))
+        throw new Error("environment contract must pin the discovery reads");
+    if (!ENVIRONMENT_WIRE.applicationScope.includes("applicationCode"))
+        throw new Error("environment contract must pin the application scope selector");
+    if (!ENVIRONMENT_WIRE.portalVisibility.includes("portalHidden"))
+        throw new Error("environment contract must pin the portal-visibility flag");
+    if (!ENVIRONMENT_WIRE.fingerprint.includes("environment"))
+        throw new Error("environment contract must pin the fingerprint fields");
+}
+//# sourceMappingURL=environment-contract.js.map

package/dist/lanes/environment-coverage.js

@@ -0,0 +1,14 @@
+import { claim, declareLaneCoverage } from "./coverage-declaration.js";
+import { ENVIRONMENT_LANE_CONTRACT } from "./environment-contract.js";
+const T = ENVIRONMENT_LANE_CONTRACT.tools;
+export const ENVIRONMENT_COVERAGE = declareLaneCoverage(ENVIRONMENT_LANE_CONTRACT.lane, [
+    {
+        capability: "Environment governance (discovery/fingerprint/compat/dbsweep/license renewal)",
+        evidence: ["src/dbsweep.ts", ".scratch/omc-route-wayfinder/leg2-closeout.md"],
+        tools: [
+            claim("discover_environment", T["discover_environment"].scope),
+            claim("environment.fingerprint", T["environment.fingerprint"].scope),
+        ],
+    },
+]);
+//# sourceMappingURL=environment-coverage.js.map

package/dist/lanes/environment.js

@@ -0,0 +1,163 @@
+import { z } from "zod";
+import { ENDPOINTS } from "../endpoints.js";
+import { capabilityArg, environmentArg } from "../args.js";
+import { governedRead } from "../read.js";
+import { environmentWritable, requiresProductionConfirmation } from "../environment-policy.js";
+import { flattenTreeRows } from "../support.js";
+import { defineTool } from "../tool-types.js";
+import { wireCall, wireRows } from "../wire.js";
+import { ENVIRONMENT_LANE_CONTRACT } from "./environment-contract.js";
+const ENVIRONMENT_LANE = ENVIRONMENT_LANE_CONTRACT.lane;
+const ENVIRONMENT_TOOLS = ENVIRONMENT_LANE_CONTRACT.tools;
+export function registerEnvironmentLane(tools) {
+    tools.push(defineTool({
+        name: "discover_environment",
+        layer: "high",
+        kind: "read",
+        lane: ENVIRONMENT_LANE,
+        scope: ENVIRONMENT_TOOLS["discover_environment"].scope,
+        description: ENVIRONMENT_TOOLS["discover_environment"].description,
+        inputSchema: {
+            environment: environmentArg,
+            applicationCode: z.string().optional(),
+            modelCode: z.string().optional(),
+            full: z.boolean().optional().describe("内联完整发现结果；默认返回计数与 detailFile"),
+            capability: capabilityArg,
+        },
+        handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
+            // List every application the tenant exposes — the configured
+            // applicationCode is a default, never the only application. Resolve
+            // the active code through the same priority chain as writes:
+            // explicit > project-env binding > configured default > tenant's
+            // first application.
+            const appRows = wireRows((await wireCall(session, { path: ENDPOINTS.applicationList, query: {} })).data);
+            // Ticket 57: group membership decides portal visibility. The portal
+            // renders NAMED groups; an app parked in the fallback group
+            // (code === "all", case-insensitive) is not rendered by that view, and
+            // an unresolvable groupId must fail closed rather than be assumed
+            // visible. The discovery read face exposes both so "choose an app" is
+            // an informed decision.
+            const groups = wireRows((await wireCall(session, { path: ENDPOINTS.applicationGroupList, query: {} })).data).map((row) => {
+                const code = String(row.code ?? "");
+                return { id: String(row.id ?? ""), code, name: row.name ?? row.groupName ?? code, isFallback: code.toLowerCase() === "all" };
+            });
+            const groupById = new Map(groups.map((group) => [group.id, group]));
+            const apps = appRows.map((row) => {
+                const groupId = row.groupId === undefined || row.groupId === null ? undefined : String(row.groupId);
+                const group = groupId ? groupById.get(groupId) : undefined;
+                return {
+                    code: String(row.appCode ?? row.code),
+                    name: row.appName ?? row.name,
+                    groupId: groupId ?? null,
+                    groupCode: group?.code ?? null,
+                    groupName: group?.name ?? null,
+                    portalHidden: group === undefined || group.isFallback === true,
+                };
+            });
+            const configured = session.profile.applicationCode?.trim() || undefined;
+            const explicit = typeof args.applicationCode === "string" && args.applicationCode.trim() ? args.applicationCode.trim() : undefined;
+            const selected = explicit ?? configured ?? apps.find((app) => typeof app.code === "string" && app.code)?.code;
+            const selectedApp = selected ? apps.find((app) => app.code === selected) : undefined;
+            const applicationResolution = explicit
+                ? selectedApp ? { status: "resolved", source: "explicit", requested: explicit } : { status: "requested-unresolved", source: "explicit", requested: explicit }
+                : configured
+                    ? selectedApp ? { status: "resolved", source: "configured", requested: configured } : { status: "configured-unresolved", source: "configured", requested: configured }
+                    : selectedApp ? { status: "resolved", source: "first-tenant-application", requested: selectedApp.code } : { status: "absent", source: "tenant", requested: null };
+            const groupStatus = groups.length === 0
+                ? { status: "absent" }
+                : groups.some((group) => !group.id) ? { status: "unresolved" } : { status: "resolved" };
+            const version = session.detectedVersion();
+            const readinessBlockers = [];
+            const readinessPreconditions = [];
+            const readinessWarnings = [];
+            const readinessRecovery = [];
+            if (applicationResolution.status === "absent") {
+                readinessBlockers.push({ code: "application-absent", message: "租户没有可选择的应用" });
+                readinessRecovery.push({ code: "app-create-prerequisite-missing", action: "先确认应用分组存在；分组缺失需由管理侧创建" });
+            }
+            else if (applicationResolution.status !== "resolved") {
+                readinessBlockers.push({ code: "configured-application-unresolved", requested: applicationResolution.requested, message: "配置的 applicationCode 在租户应用列表中不存在" });
+                readinessRecovery.push({ code: "application-selection-unresolved", action: "选择 discover_environment applications 中存在的 code，或清除错误的配置 applicationCode" });
+            }
+            if (groupStatus.status === "absent") {
+                readinessBlockers.push({ code: "application-groups-absent", message: "租户没有可用于应用创建的分组" });
+                readinessRecovery.push({ code: "app-create-prerequisite-missing", action: "由管理侧创建应用分组后重新 discover_environment" });
+            }
+            else if (groupStatus.status !== "resolved") {
+                readinessBlockers.push({ code: "application-groups-unresolved", message: "应用分组返回了无法解析的记录" });
+            }
+            const writable = environmentWritable(session.profile);
+            if (!writable)
+                readinessBlockers.push({ code: "environment-not-writable", message: "环境 writable=false，应用配置写入会被拒绝" });
+            if (!version)
+                readinessBlockers.push({ code: "version-evidence-missing", message: "未取得 CloudPivot 版本族证据，写入应 fail closed" });
+            if (requiresProductionConfirmation(session.profile))
+                readinessPreconditions.push({ code: "production-confirmation-required", requiredArg: "confirmProduction:true" });
+            readinessWarnings.push({ code: "app-publish-out-of-boundary", message: "app.create 不发布应用；需在设计器发布并核对具名分组后再做门户验证" });
+            const readiness = {
+                ready: readinessBlockers.length === 0,
+                blockers: readinessBlockers,
+                preconditions: readinessPreconditions,
+                warnings: readinessWarnings,
+                recovery: readinessRecovery,
+                facts: { writable, production: session.profile.production === true, versionEvidence: Boolean(version), selectedApplicationResolved: applicationResolution.status === "resolved", applicationGroupsResolved: groupStatus.status === "resolved" },
+            };
+            let foldersAndModels = [];
+            let models = [];
+            if (selectedApp) {
+                // Live (2026-09-17) the app tree is NESTED (Folder -> BizModel
+                // children); the previous top-level map dropped every model, so
+                // foldersAndModels showed only the folder. Flatten first (the same
+                // helper resolveModelTreeNode uses).
+                const tree = flattenTreeRows(wireRows((await wireCall(session, { path: ENDPOINTS.applicationTree, query: { appCode: selected } })).data));
+                foldersAndModels = tree.map((row) => ({ id: row.id, type: row.type, code: row.code, name: row.name ?? row.text }));
+                // The models under THIS application — derived from its tree, not the
+                // tenant-wide list_schema (which returned every model in the tenant
+                // regardless of applicationCode, contradicting the lane contract
+                // "applicationCode selects one and returns its folders/models").
+                models = tree
+                    .filter((row) => String(row.type ?? "").toLowerCase() === "bizmodel")
+                    .filter((row) => !args.modelCode || row.code === args.modelCode || row.schemaCode === args.modelCode)
+                    .map((row) => ({ schemaCode: row.code ?? row.schemaCode, name: row.name }));
+            }
+            return {
+                applications: apps,
+                groups,
+                applicationCode: selected ?? null,
+                applicationResolution,
+                applicationGroups: groupStatus,
+                readiness,
+                foldersAndModels,
+                models,
+            };
+        }, {
+            full: args.full === true,
+            target: `discover_environment:${args.applicationCode ?? ""}:${args.modelCode ?? ""}`,
+            compact: (result) => {
+                const compact = { ...result };
+                for (const key of ["applications", "groups", "foldersAndModels", "models"]) {
+                    const value = compact[key];
+                    if (Array.isArray(value)) {
+                        compact[`${key}Count`] = value.length;
+                        delete compact[key];
+                    }
+                }
+                return compact;
+            },
+        }),
+    }));
+    tools.push(defineTool({
+        name: "environment.fingerprint",
+        layer: "low",
+        kind: "read",
+        lane: ENVIRONMENT_LANE,
+        scope: ENVIRONMENT_TOOLS["environment.fingerprint"].scope,
+        description: ENVIRONMENT_TOOLS["environment.fingerprint"].description,
+        inputSchema: { environment: environmentArg, capability: capabilityArg },
+        handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => ({
+            environment: session.environmentName,
+            fingerprint: session.environmentFingerprint(),
+        })),
+    }));
+}
+//# sourceMappingURL=environment.js.map