@shundoo-ai/dsh-cosmic 1.0.16 → 1.0.18

package/skills/cosmic-build/skills/cosmic-meta-api/contracts/cli/operation-validation.json

@@ -0,0 +1,134 @@
+{
+  "schemaVersion": "app-build-cli-contract/v1",
+  "command": "ensureOperationValidation",
+  "effect": "write",
+  "semantics": "Create one blocking single/all/any ConditionValidation, or update an explicitly selected existing validationId through compound input while preserving other validations.",
+  "targetBinding": {
+    "form": "Accept exactly one of formNumber or form-name. form-name resolves through prepareFormMutationTarget inside the same invocation.",
+    "operation": "Treat operationKey as an exact persisted key first. If that read fails, resolve one exact operation display name through listOperations.",
+    "field": "Resolve exact field keys first. For compound input, intersect candidate EntityKey values so a uniquely owned condition scopes duplicate captions in the same validation.",
+    "failClosed": "Ambiguous form, operation name or field caption stops before the operation write."
+  },
+  "requiredByAppBuild": [
+    "appRoot OR projectRoot",
+    "formNumber OR form-name",
+    "operation key OR exact display name",
+    "one of: when-element + operator + message; input with conditions[] + message"
+  ],
+  "operators": [
+    "=",
+    "<>",
+    ">",
+    ">=",
+    "<",
+    "<=",
+    "empty",
+    "not-empty",
+    "before-current-date",
+    "after-current-date"
+  ],
+  "example": {
+    "arguments": [
+      "--app-root",
+      "<trusted-app-root>",
+      "--form-name",
+      "<exact-form-name-or-number>",
+      "--operationKey",
+      "保存",
+      "--when-element",
+      "申请金额",
+      "--operator",
+      "empty",
+      "--message",
+      "申请金额不能为空"
+    ]
+  },
+  "compoundInput": {
+    "argument": "--input accepts inline JSON or a JSON file, and cannot be mixed with scalar condition flags",
+    "shape": {
+      "logic": "all | any; defaults to all",
+      "conditions": [
+        {
+          "element": "<exact key or business caption>",
+          "operator": "= | <> | > | >= | < | <= | empty | not-empty | before-current-date | after-current-date",
+          "value": "<omit for empty/not-empty/before-current-date/after-current-date>",
+          "valueElement": "<alternative field operand on the same entity; omit value when used>"
+        }
+      ],
+      "message": "<explicit blocking message>",
+      "description": "<optional stable identity>",
+      "entity": "<optional exact entity name/key or header/entries>",
+      "validationId": "<optional exact existing ConditionValidation ID; omission means add/ensure, never infer replacement>"
+    },
+    "example": {
+      "entity": "报销明细",
+      "logic": "all",
+      "conditions": [
+        {
+          "element": "报销金额",
+          "operator": ">",
+          "valueElement": "核定标准"
+        },
+        {
+          "element": "超标说明",
+          "operator": "empty"
+        }
+      ],
+      "message": "超标准报销请填写说明"
+    },
+    "operandRule": "Ordinary comparisons use exactly one of value or valueElement. Empty/not-empty/before-current-date/after-current-date omit both. A business standard must be supplied or resolved to an existing field, never invented."
+  },
+  "closure": [
+    "resolve the exact existing operation and condition fields; when validationId is supplied, require one same-entity ConditionValidation",
+    "for compound input, list fields once, infer one shared EntityKey from all candidates, resolve duplicate captions inside that scope, and join canonical expressions with AND/OR",
+    "derive EntityKey from the field's live owner",
+    "evaluate runtime emptiness independently of design defaults; preserve existing defaults",
+    "preserve every unrelated validation including its _Type_ and Id; preserve the selected validation Id and Enabled state during an explicit update",
+    "create a canonical error-level ConditionValidation or update the explicitly selected one, then independently verify the complete merged array",
+    "compile empty/not-empty with the operation-validator dialect: numeric fields use null comparison; non-numeric fields additionally compare the empty string; never use rule-engine-only isNull()/isEmpty() helpers",
+    "compile DateField before-current-date as DATEDIF(field, NOW(), 'D') > 0; compile after-current-date by comparing TO_CHAR(field, 'yyyy-MM-dd') > TO_CHAR(NOW(), 'yyyy-MM-dd') so tomorrow is not lost to DATEDIF full-interval truncation",
+    "migrate the command's own legacy isNull()/isEmpty() expression in place while preserving the validation Id and unrelated validations",
+    "return a verified no-op when the same validation already exists",
+    "update once and independently compare the complete validations array through getOperation"
+  ],
+  "failClosed": {
+    "descriptionConflict": "OPERATION_VALIDATION_DESCRIPTION_CONFLICT; do not append a second validation under the same identity",
+    "unsupportedFieldOrValue": "fails before operation mutation with writeAttempted=false",
+    "invalidValidationId": "OPERATION_VALIDATION_ID_NOT_FOUND / ID_AMBIGUOUS / TYPE_MISMATCH / ENTITY_MISMATCH; no operation write and no implicit creation"
+  },
+  "resultContract": {
+    "changed": "false means the exact validation already existed and no operation write occurred",
+    "preservedValidationCount": "number of pre-existing validations retained in the merged write",
+    "verification": "the underlying updateOperation closure compares the requested full validation list against getOperation",
+    "defaultPreservation": "An existing default does not forbid an empty-value validation. This command never clears or changes field defaults.",
+    "validationAction": "updated_existing identifies an explicit validationId update; data.validation returns the same selected ID"
+  },
+  "companionCommand": {
+    "command": "ensureMustInputValidation",
+    "semantics": "Idempotently enable the operation-level MustInputValidation that makes field MustInput and MustInputCondition block the operation at runtime.",
+    "arguments": [
+      "--app-root",
+      "<trusted-app-root>",
+      "--form-name",
+      "<exact-form-name-or-number>",
+      "--operationKey",
+      "保存"
+    ],
+    "closure": [
+      "read the exact existing operation",
+      "preserve all validations and their IDs",
+      "enable the single existing MustInputValidation and clear SkipMustInput=true, or create one when absent",
+      "return a verified no-op when it is already enabled",
+      "update once and compare the complete validations array through getOperation"
+    ],
+    "evidence": "On uhyl_demo_expense_apply, MustInput and MustInputCondition only rendered required markers while save.MustInputValidation omitted Enabled; manually setting Enabled=true made both static and conditional required values block save."
+  },
+  "existingValidationUpdate": {
+    "selection": "Reuse data.validation.Id from a prior receipt, or read the selected operation and identify one existing validation. Never pass a formRule ID or a display name as validationId.",
+    "input": "Use the same compound --input with validationId, conditions and message; one condition is allowed.",
+    "preserved": "The selected Id, Enabled state, custom metadata and all other validations retain their values and positions. EntityKey and validation type cannot change.",
+    "changed": "Expression, Message, TrueThrow=true and LevelId=2 implement the requested blocking condition. New validations use the business message as their readable Description. An explicitly selected legacy generated Description is refreshed on update; an existing business Description is retained unless explicitly supplied.",
+    "failure": "Missing, duplicate, wrong-type or other-entity IDs return a zero-write error. They never cause a new validation to be appended.",
+    "repeat": "An already matching selected validation returns a verified no-op."
+  }
+}

package/skills/cosmic-build/skills/cosmic-meta-api/contracts/cli/property-batch.json

@@ -0,0 +1,152 @@
+{
+  "schemaVersion": "app-build-property-policy/v1",
+  "commands": {
+    "configureSelectionFields": {
+      "effect": "write",
+      "scope": "一个准确现有表单",
+      "arguments": [
+        "app_root",
+        "formNumber 或 form_name",
+        "input：{fields:[{field,entities,options?,default?}],preserveExisting:true}"
+      ],
+      "semantics": "一条意图级命令为一个或多个选择字段只补缺失选项、保留已有选项，再通过现有属性 policy 路径批量设置并独立验证默认值",
+      "resultContract": "data.optionResults 返回每个实体范围的选项结果，data.propertyResult 返回已验证的默认值批次"
+    },
+    "listDefaultCandidates": {
+      "effect": "read",
+      "scope": "one exact existing form",
+      "arguments": [
+        "app_root OR project_root with app identity",
+        "formNumber OR form_name",
+        "input as {targets:<property-policy targets>,limit:1..20}"
+      ],
+      "semantics": "resolves exact fields and entities, then uses recordCandidates items on the existing setProperties API to query each field's bound business-record entity without saving metadata",
+      "resultContract": "data.recordCandidates maps each element key to baseEntityNumber and real id/number/name candidates or an exact unsupported reason; writeAttempted=false"
+    },
+    "setSplitTables": {
+      "effect": "write",
+      "scope": "一个准确的已有表单及其一个实体",
+      "arguments": [
+        "app_root 或带应用身份的 project_root",
+        "formNumber 或 form_name",
+        "entityKey 或 entity，取准确实体 key 或唯一业务名称",
+        "suffix 取一个 ASCII 字母，下划线由平台自己拼接",
+        "description 取拆分表的业务名称"
+      ],
+      "semantics": "在实体的 SplitTables 复杂属性里声明一张拆分表，追加到该实体已声明的内容之后，再用独立设计态读取证明。哪些字段存放在该表里是每个字段自己的 Suffix 属性，这里不写",
+      "targetRules": {
+        "entity": "只接受实体；不公开 SplitTables 的控件报 SPLIT_TABLE_NOT_SUPPORTED_BY_ELEMENT 且 writeAttempted=false",
+        "suffix": "L 是平台多语言表专用，会被拒绝；_f 与 f 指向同一张表"
+      },
+      "negativeExamples": [
+        "setComplexProperty --complexType splitTables —— 整表替换：漏掉已有后缀会报「已被字段引用，无法删除」，小写 suffix/description 键报「后缀不能为空」，而且没有读回",
+        "addEntryEntity —— 拆分表是已有实体的属性，绝不是新增分录"
+      ],
+      "preflight": "解析实体用的同一次实时清单读取，会把字段标识跨实体重复的表单以 FORM_DUPLICATE_FIELD_KEYS 拒绝，因为设计器会拒绝这种表单的每一次保存，而平台错误不给补救办法",
+      "idempotency": "已声明过的后缀返回 status true、changed=false、resumed=true 且 writeAttempted=false",
+      "readBack": "getPropertySchema.SplitTables 必须包含请求的后缀；写入后不一致按 unknown_after_write 报出"
+    },
+    "setInstantSync": {
+      "effect": "write",
+      "scope": "一个准确的已有表单及其一个单据体",
+      "arguments": [
+        "app_root 或带应用身份的 project_root",
+        "formNumber 或 form_name",
+        "entryKey 或 entry，取准确单据体 key 或唯一业务名称",
+        "realtime_off 取 实时请求 开关为关的列（名称或标识）",
+        "realtime_on 取恢复默认实时请求的列",
+        "row_click / row_dblclick 取 on|off，对应 行单击 / 行双击",
+        "allow_full_metadata_write 用于授权行事件那条写入路",
+        "clear 用于清空该单据体的整条配置"
+      ],
+      "semantics": "配置一个单据体的 数据实时同步（InstantSync），并自己承担写入形状与存储形状的翻译：接受的列载荷里 columns 是 {fieldkey, canUpdate} 的 LIST，而平台存的是 JSON 字符串、其中 columns 是以列为 key 的对象且 canUpdate true 会被丢弃；action 用同一种反向存储记录**被禁用**的行事件。请求合并到线上值，没点名的列和没动的行事件保持原状，再用 InstantSync 的独立读取证明",
+      "routes": {
+        "columnsOnly": "setComplexProperty complexType instantSync，elementKey 传单据体 key",
+        "rowEventsOrPreservingAnAction": "loadFullMetadata → 在该分录 EntryAp 上 patch /formmeta/Items/<i>/InstantSync → saveFullMetadata，由 allow_full_metadata_write 把关。这条路会替换**整张表单**的元数据，而且平台保存时自己重新序列化，所以补丁后的文档一旦在那一个指针之外还有差异就拒绝，并把平台的保存提示原样放进 data.platformWarning"
+      },
+      "targetRules": {
+        "entry": "只接受单据体（EntryEntity、SubEntryEntity、EmbedSubEntryEntity、TreeEntryEntity）；其它元素报 INSTANT_SYNC_TARGET_NOT_ENTRY 且 writeAttempted=false，与平台的 目标控件不是单据体 对齐",
+        "columns": "点名的列必须是该单据体的子列；否则平台答 fieldkey '<k>' 不存在于单据体 '<entry>' 的子控件中",
+        "rowAction": "行事件那一半到不了 ai-meta 属性写入面（10 种载荷编码都返回 保存成功 而 action 不变；setProperties 以复杂属性为由拒绝；modifyMeta 改该属性答 METADATA_UNCHANGED）。所以请求行事件、或者在已禁用行事件的分录上改列，都需要 allow_full_metadata_write；不带它就以 INSTANT_SYNC_NEEDS_FULL_METADATA_WRITE 失败关闭（retryable=true），并同时给出该授权项和设计器两条出路。不要把行事件说成做不到"
+      },
+      "negativeExamples": [
+        "setComplexProperty --complexType instantSync 且 columns 传对象 —— 平台答 columns 必须是 List 类型。（尽管它存下来的正是那个对象）",
+        "setComplexProperty --complexType instantSync 且传 click/dbclick 布尔 —— 返回 保存成功 但被静默丢弃，读回的 action 仍为空",
+        "在已禁用行事件的分录上用 setComplexProperty 写列 —— 写入成功但会把那些事件悄悄打开，这也是该场景要改走全量元数据的原因",
+        "setProperties InstantSync=<json 字符串> —— 本地以 PROPERTY_REQUIRES_COMPLEX_SETTER 拒绝"
+      ],
+      "idempotency": "请求与线上值已一致时返回 status true、changed=false 且 writeAttempted=false，两条路都是",
+      "readBack": "getProperties.InstantSync 从 JSON 字符串解码后，canUpdate 为 false 的列集合必须等于请求，且解码出来的每个行事件状态也必须等于请求；清空必须读回 null。写入后不一致按 unknown_after_write 报出"
+    },
+    "setProperties": {
+      "legacyFailureReceipt": {
+        "results": "retains each raw result, including the failed item and unknown write state",
+        "failedOperation": "resolved exact element and requested property values for the failed item",
+        "pendingOperations": "only unexecuted resolved operations with values, not a policy payload",
+        "recovery": "reconcile possible writes first; then use the smallest supported property input for remaining work without replaying completed operations"
+      },
+      "effect": "write",
+      "scope": "one exact existing form",
+      "preferredInput": "policy",
+      "staticFieldLock": "Lock-only and mixed policies use the verified form-control writer for FieldAp.Lock. Mixed policies preflight all targets/properties before sequential writes, retain completed/failed/pending operations on failure, and are not a rollback transaction. Caller-side UI routing or raw MetaOps are not required.",
+      "semantics": "the same compact policy represents one or many fields; the CLI resolves and expands targets in memory, preflights every operation, sends items through the existing setProperties API when supported, and serially falls back only after an explicit legacy validation rejection proves zero writes",
+      "arguments": [
+        "app_root OR project_root with app identity",
+        "formNumber OR form_name",
+        "policy as compact inline JSON or one JSON file path"
+      ],
+      "policy": {
+        "targets": {
+          "allFields": "optional true",
+          "fields": "optional exact caption/key selectors; use {field,entity} for duplicate captions",
+          "elements": "compatibility alias for fields; normalized before live reads and cannot be combined with fields",
+          "fieldTypes": "optional exact field type names",
+          "entities": "optional header, entry/entries, or exact entity captions/keys"
+        },
+        "set": "optional common simple-property map",
+        "complex": "optional common map for MustInputCondition, Features, CtlTips, and Style; display labels are normalized, style scalar keys join the simple map, and border/padding/margin retain merge semantics",
+        "default": "optional one typed scalar/design/record/multi-record/composite default shared by every selected field; mutually exclusive with defaultsByType",
+        "emptyTextTemplate": "optional explicit template supporting {caption}, {key}, and {type}",
+        "emptyTextPreset": "optional standard; mutually exclusive with emptyTextTemplate",
+        "defaultsByType": "optional exact fieldType to a direct non-null JSON scalar, {kind:scalar,value:<scalar>}, {kind:design,input:{...}}, {kind:record,value:<exact record name, number, or id>}, {kind:multi-record,values:[<exact selectors>]}, or DateRangeField {kind:composite,values:[<start>,<end>]} mapping; {DefValue:...} is invalid and record functions are forbidden inside kind=design",
+        "requireDefaultForAll": "optional boolean; missing types return PROPERTY_POLICY_INPUT_REQUIRED before writes",
+        "onUnsupported": "optional fail|skip, default fail; skip omits only properties absent from a selected element's live Schema and reports every omission",
+        "onRecordMismatch": "optional fail|skip, default fail; skip retries inside the same CLI only after a zero-write backend preflight whose every failure is a record-default mismatch, preserving non-default properties and reporting skipped record defaults",
+        "overrides": "optional small per-field exception array; each item requires exactly one field, element, or elementKey selector and may contain set, complex, emptyText, default, or skip; fields arrays are invalid; use elementKey for duplicate captions"
+      },
+      "legacyInput": "--element/--elementKey plus --input remains accepted for existing callers but is not the model-facing route",
+      "compatibilityPolicyAlias": "set.default is normalized to top-level default; canonical output always uses top-level default",
+      "compatibilityInputAliases": "targets.elements -> targets.fields, required -> set.MustInput, emptyText -> emptyTextTemplate, and defaults -> defaultsByType; aliases fail on canonical conflicts and are never the documented preferred shape",
+      "propertyDiscovery": "describePropertyInput accepts one live property name, display label, or unique allowed-value caption; ambiguous option captions return propertyName candidates instead of dumping every property",
+      "backend": {
+        "new": "POST the existing setProperties path with exact items plus onUnsupported/requiredPropertyNames; backend performs one load, complete preflight, one save, and one metadata reload without per-element Schema HTTP reads",
+        "legacy": "safe concurrent live-Schema preflight followed by the existing items batch, or serial per-element setters only after explicit old-DTO rejection",
+        "transport": "expanded items are HTTP body data and never terminal arguments"
+      },
+      "guarantees": [
+        "model behavior is cardinality-independent",
+        "one authentication and one form binding",
+        "the 29 previously supported direct/special properties shown by the field multi-selection surface keep their existing routes, while the four newly released dialog properties use validated in-memory mutations inside the same one-save batch",
+        "no shell/Python loops or background/concurrent writes",
+        "complete live-schema preflight before any write",
+        "new backend policy fast path reports schemaReadCount=0 and policyFastPath=backend_single_load",
+        "onUnsupported=skip never hides invalid values, read-only properties, or other preflight failures",
+        "strong recorded simple-property names are canonicalized case-insensitively; enum captions compile to persisted ids, invalid enum values and object/array values for recorded scalar storage fail before authentication",
+        "reference defaults without exact records fail with writeAttempted=false",
+        "single-record reference defaults resolve and verify id, number, and name through kind=record",
+        "multi-record defaults resolve selectors through kind=multi-record and encode FuncParameter as an identity JSON object whose id value is the platform's comma-separated record ids",
+        "DateRangeField composite defaults compile two endpoints to the designer's comma-separated scalar; TimeRangeField remains unsupported because its live Schema exposes no DefValue",
+        "unknown backend outcome never triggers fallback",
+        "object/array values can never enter scalar DefValue or reach the Java setter",
+        "requireDefaultForAll makes unsupported default properties fatal before every write while unrelated unsupported outcomes may still be skipped"
+      ],
+      "resultContract": {
+        "defaultCoverage": "selectedFieldCount, defaultTargetCount, missingDefaultTypes, skippedDefaultCount, appliedDefaultCount, strictDefaultCoverage, and complete",
+        "completionGate": "when defaultCoverage is incomplete, blocks finalization until every missing type is covered or explicitly excluded by the user",
+        "completionRule": "complete=true is required before claiming that every selected field has a default",
+        "failureGuidance": "policy validation/preflight failures publish retryAdvice, retryLimit=1, allowedNextActions, and forbiddenNextActions; they never require describePropertyInput, getFormSchema, command help, or result-file inspection",
+        "allUnsupported": "If every requested property is skipped with zero verified properties and confirmed zero writes, return PROPERTY_BATCH_NO_APPLICABLE_PROPERTIES with status=false, verified=false and alreadySatisfied=false; this is failed_preflight, never verified_noop. Preserve the skipped property details."
+      }
+    }
+  }
+}