openxiangda-skill-kit 2.0.0-alpha.125 → 2.0.0-alpha.128

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.0.0-alpha.125",
+  "version": "2.0.0-alpha.128",
   "description": "Validation and deterministic packaging for OpenXiangda 2.0 AI skills.",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
     "README.md"
   ],
   "dependencies": {
-    "openxiangda-devkit-core": "2.0.0-alpha.103"
+    "openxiangda-devkit-core": "2.0.0-alpha.105"
   },
   "devDependencies": {
     "tsx": "4.23.12",

package/skills/openxiangda-v2/references/data-authz.md

@@ -61,8 +61,13 @@ const visitorReservations = {
 ```
 
 Put it in `data: { resources: [visitorReservations] }`. Resource CRUD
-capabilities are derived by `resourceCapabilityCodes`; grant the needed values
-to roles. Directory-backed roles also require
+capabilities are derived by `resourceCapabilityCodes`. For a Native resource,
+grant `read` to each role that may enter its generated page; the compiler also
+grants that role every enabled generated create/update/delete operation. Remove
+an operation only when the role must be restricted, using the corresponding
+code in `deniedCapabilities`. The compiler validates the denial and seals only
+the resulting allow list, so runtime authorization has no second deny model.
+Non-Native mutation owners never receive this expansion. Directory-backed roles also require
 `app:<app-code>:directory:read`. Explicit field `access` capability codes are
 also granted only to the intended roles. They are owned and exported by the
 generated field policy, so do not repeat them in `authz.capabilities`.
@@ -108,15 +113,20 @@ normal authorized role union with that Perspective before capability, field,
 row-policy and RLS evaluation. Omit the header for the complete union. Never
 use Perspective to guard writes, workflows or custom actions.
 
-`required: true` owns both storage nullability and form validation. A field
-without `access` inherits the resource read/create/update capability. Each
-access array is all-of; `false` is explicit deny. The same arrays drive the
-generated UI and platform field policies.
+`required: true` is a logical application rule: generated forms show it as
+required, and the Native Data API rejects omission on create or explicit null
+on create/update. It does not create PostgreSQL `NOT NULL`; every authored
+business column remains physically nullable so fields can be added or made
+required without a historical-data backfill. Older rows may therefore contain
+null when they predate the rule. A field without `access` inherits the resource
+read/create/update capability. Each access array is all-of; `false` is explicit
+deny. The same arrays drive the generated UI and platform field policies.
 
 For `uuid` fields, omission never generates a value. Only the resource system
 field `id` is platform-generated. An omitted optional UUID remains `null`; a
-required UUID must be supplied explicitly and cannot rely on an implicit
-database default.
+required UUID must be supplied by a current create request and cannot rely on
+an implicit database default. This is Data API validation, not a physical
+`NOT NULL` constraint.
 
 Field types are semantic, not PostgreSQL storage aliases. Use the catalog in the generated `AGENTS.md`: for example `text.short`, `number.integer`, `user.single`, `department.multiple`, `resource-ref.single`, `file`, `address` and `subtable`. The compiler alone chooses storage columns and constraints. Reference fields store JSON display values. For `resource-ref.*`, `resourceCode`, `value`, `label`, optional `description` and optional `snapshot` are convenient historical display data only: the target resource remains authoritative, the platform does not create a foreign key or refresh/check the stored JSON, and business actions that need current target state must query it by `resourceCode` plus `value`. A resource source `labelField` must point to `text.short` or `text.long`; a `serial-number` field can be listed in `searchFields`, `descriptionFields` or `snapshotFields`, but it is not a display label. File limits exist only under `file`; `maxCount` owns the single/multiple bound and `maxSizeMb` owns the per-file size bound. There is no `file.multiple` key.
 

package/skills/openxiangda-v2/references/workspace.md

@@ -40,7 +40,7 @@
 - Visitor duplicate protection uses `createVisitorReservation({ duplicateMatch: { fieldCode: submittedValue }, ... })`. `duplicateMatch` is a non-empty value map, never a field-name array, and no mutable pre-read is allowed.
 - Desktop and mobile pages share values, validation and authorization, but use separate renderers. Options, members and departments store display snapshots; resource references store direct JSON display values; attachments, images and signatures use platform-managed file references.
 - `option.*`, `user.*`, `department.*` and `resource-ref.*` values never collapse to scalar IDs. Single values store one labeled object and multiple values store object arrays. `resource-ref.*` JSON is not a foreign key, trusted target snapshot or automatically refreshed copy; current target state is read by `resourceCode` plus `value`. A resource source `labelField` must be `text.short` or `text.long`; `serial-number` is allowed in source search, description and snapshot fields, but not as the label. `location` accepts only exact WGS84 coordinates captured by DingTalk or browser geolocation; it has no manual input or `manual` source. Roles that consume directory-backed fields explicitly include `app:<app-code>:directory:read`.
-- Derive role grants with `resourceCapabilityCodes(appCode, resourceCode)`. Declare current-user rows only with `currentUserDataPolicy(...)`; do not invent operators, values or alternate current-user spellings.
+- Derive role grants with `resourceCapabilityCodes(appCode, resourceCode)`. Grant a Native resource's `read` capability to every role allowed to enter its generated page; the compiler adds enabled generated create/update/delete capabilities by default. Tighten only exceptional roles with `deniedCapabilities`, which is compile-time authoring input and is removed from the sealed role. Non-Native mutation owners never receive this expansion. Declare current-user rows only with `currentUserDataPolicy(...)`; do not invent operators, values or alternate current-user spellings.
 - Do not add compatibility aliases, migration branches or silent fallbacks for an earlier 2.0 alpha contract. Replace an incorrect contract and regenerate the application.
 - Standard Workflow and Notification Hub are optional 2.0 modules. Enable them only through canonical `openxiangda.config.ts` declarations and generated clients. `standalone`/`hidden-handoff` default to the compiler-owned process operation; action-owned submission must instead declare `launch.submission.kind: 'named-operation'` with sealed create/existing input and output bindings so the standard PC/mobile page calls the original Named Action and accepts an explicit no-Workflow result. Never add a browser save callback or call Workflow prepare/start directly. Custom pages launch only through a verified Named Action using `OpenXiangdaBusinessProcessService`. PC and mobile render the same `ProcessCommandSurface` independently and recover only by `commandId`. To replace Workflow detail, declare both desktop and mobile `detailRouteCode` values whose routes contain exactly `:instanceId`. Add the current-user todo page only with `frontend.user.applicationTodoCenter: true`; never query Notification Hub management APIs from a user page.
 - Run `pnpm openxiangda check --json` after contract changes and read `data.sealedArtifact`; check never seals, and an older `.openxiangda/build/app-package.json` is not the current check result. Use `pnpm openxiangda accept --plan <file>` only for optional real preproduction identity acceptance; it never blocks delivery. Deploy with `pnpm openxiangda deploy`, inspect with `pnpm openxiangda status` and `pnpm openxiangda logs`, and use the platform rollback command rather than mutating K3s directly.