openxiangda-skill-kit 2.0.0-alpha.100 → 2.0.0-alpha.102

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.0.0-alpha.100",
+  "version": "2.0.0-alpha.102",
   "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.79"
+    "openxiangda-devkit-core": "2.0.0-alpha.81"
   },
   "devDependencies": {
     "tsx": "4.23.12",

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

@@ -4,4 +4,6 @@ Keep one React application, one optional NestJS service and one platform-owned d
 
 Declare resources, routes, capabilities, row policies and operation-aware field policies once in `openxiangda.config.ts`. The compiler owns derived contracts; the root package owns Field Kit, CRUD Renderer, Shell, clients and Nest integration; the platform owns identity, authorization, data, environment Heads and deployment state.
 
+The compiler alone derives the AppPackage `requiredPlatformCapabilities` closure. Each entry binds a capability `code`, exact `contractVersion` and deterministic `usageDigest` of only that capability's normalized declarations. Never write `platform.requiredCapabilities`, append requirements through a build API, edit the AppPackage or accept a feature whose status is not `available` or whose contract version differs. The platform authoritatively recomputes the closure from the sealed config and contract artifacts.
+
 Ordinary list, detail, create, update and delete operations go directly through Data API. Add a NestJS endpoint only for a business action that cannot be represented as CRUD. Run `pnpm openxiangda check` after every contract change.

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

@@ -149,8 +149,11 @@ invariants when all must hold:
 }
 ```
 
-`datetime-range` is always a non-empty half-open interval `[start, end)`.
-Adjacent values such as `[10:00, 11:00)` and `[11:00, 12:00)` do not overlap.
+Every `date-range` and `datetime-range` field explicitly declares
+`rangeBoundary: 'closed' | 'half-open'`. Values remain `{ start, end }`; callers
+never send or override the boundary. Closed ranges allow `start <= end` and use
+PostgreSQL `[]`; half-open ranges require `start < end` and use `[)`. Adjacent
+half-open values such as `[10:00, 11:00)` and `[11:00, 12:00)` do not overlap.
 Use the ordinary `overlaps` query operator or a `query-empty` transaction guard;
 never add or subtract milliseconds at the boundary.
 

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

@@ -34,9 +34,16 @@ promote or satisfy any release gate. Use it only when the requested acceptance
 needs real role membership and browser login.
 
 Use `pnpm openxiangda status` and `pnpm openxiangda logs` without an ID for the most recent run, or pass an explicit run ID.
+Treat DeploymentRun recovery as platform-authoritative. Inspect `rootFailure`,
+`latestFailure`, `candidate`, `recovery` and the append-only `attempts` ledger.
+Run only the published `recovery.nextCommand`; offer cancellation only when
+`recovery.cancelAllowed` is true. Never infer retryability or cancellation from
+status, the latest failure, or locally interpreted checkpoints.
 
 For the AI-native MCP entrypoint, `build_app` and `deployment_plan` are explicitly unsealed previews. After the user authorizes deployment, call `deploy_app` without any image coordinate; it owns the same automatic Buildx, push, digest and sealing path as the CLI.
 
 Applications with Native Data Resources automatically require `data.native-golden-crud`. If deployment returns `OPENXIANGDA_REQUIRED_CAPABILITY_UNAVAILABLE`, preserve the remediation to upgrade the platform and retry the same deploy command. Never remove the requirement, edit the AppPackage, construct a second identity path, or create Function-based CRUD.
 
+All AppPackage platform requirements are compiler-derived structured entries with `code`, exact `contractVersion` and a deterministic declaration-only `usageDigest`. The target platform feature must be `available` at exactly that contract version. Applications cannot declare `platform.requiredCapabilities`, pass additional requirements to the package compiler or use the deleted string `requiredCapabilities` shape.
+
 After a successful test run, deploy the exact same version with `pnpm openxiangda deploy --environment production --from <test-deployment-id>`. Roll back with `pnpm openxiangda rollback --environment production --to <app-version-id>`. The platform owns durable deployment state.

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

@@ -69,6 +69,17 @@ operation pages under `/admin/operations`; parameterized routes remain
 reachable but cannot be menu references. `defineAdminContributions` remains an
 admin-only helper and intentionally rejects `user` routes.
 
+The platform also owns admin appearance. Wrap bespoke admin content in
+`OpenXiangdaAdminPage`. Ant Design components inherit the existing
+`ConfigProvider`; do not create another theme provider. Use
+`useOpenXiangdaTheme()` for TypeScript-rendered values such as chart colors and
+the public `--oxa-color-*`, `--oxa-shadow-surface`, and
+`--oxa-radius-surface` variables for custom CSS. Never hard-code white, black,
+or neutral greys as admin canvas, card, border, or text colors. Application
+brand and categorical colors may remain explicit only when they are not used as
+structural theme colors. Verify every custom admin page in light, dark, and
+follow-system modes.
+
 Declare application-owned login visuals with optional
 `frontend.authentication`. The only supported account contract is
 `existing-platform-users-only` with `registration.mode: 'reject'`; use exact

package/skills/openxiangda-v2/references/workflow-events.md

@@ -17,21 +17,27 @@ Use these optional modules only when the application has a real standard approva
 
 ## Workflow declaration
 
-Declare workflow topology and bindings once in `openxiangda.config.ts`. Use only approval, condition and end nodes for the standard module. Keep business data in Data API/App API and pass an immutable `dataRef`, business revision and bounded facts into prepare/start.
+Declare workflow topology and bindings once in `openxiangda.config.ts`. Use only approval, condition and end nodes for the standard module. Every definition `inputSchema` is a closed root object (`type: 'object'`, `additionalProperties: false`). Keep business data in Data API/App API and pass the exact `{ resourceCode, id }` `dataRef`, a separate positive `dataRevision`, and bounded schema-valid facts into prepare/start. Undeclared facts and answers fail closed.
+
+`workflows.activations` is the complete desired set for the deployed version,
+not a patch list. Removing a declaration deactivates that workflow for new
+starts. Every assignee provider binding uses candidate `min`/`max` defaults of
+1/200 and may not exceed 200. Application Provider callbacks accept only the
+signed `openxiangda.workflow-assignee-request/v2.1` envelope, including the
+business/data/version tuple and `factDigest`.
 
 Every definition declares a launch mode: `standalone` for a self-contained
-generated save-and-start page, `custom-page` for an application operation page,
+generated durable-process page, `custom-page` for an application operation page,
 `hidden-handoff` for a non-menu handoff route, or `work-center-only` when users
 only act on existing tasks. Only `standalone` may be referenced by
 `adminWorkflowLaunchPage`; the generated browser runtime uses the workflow's
 localized definition title, so applications do not maintain code-to-title
-maps. A standalone page receives all durable business context through its
-typed save handler and URL/search contract; it must never depend on transient
-router location state. Work center, task and instance pages remain reachable
-without becoming launch menu entries. Bind the generated metadata with
-`defineWorkflowLaunchContributions(workflowDefinitions, handlers)`; handlers
-only persist the durable business revision, while generated code keeps title
-and launch mode authoritative.
+maps. `standalone` and `hidden-handoff` receive a compiler-owned
+`processOperationCode` and subject declaration. The browser submits the
+platform standard process commit and persists only `commandId` in the URL; it
+never owns a save callback, facts/dataRef, preparation token, or direct start.
+Custom pages launch only inside a verified Named Action through
+`OpenXiangdaBusinessProcessService`.
 
 Use an assignee Provider only when resolution depends on application data. The Provider returns stable Native user/role subjects and never makes the final task authorization decision.
 
@@ -39,10 +45,10 @@ The standard operations are approve, reject, return, resubmit, transfer, delegat
 
 ## Submission and concurrency
 
-1. Persist the business draft through Data API/App API.
-2. Bind prepare to the saved revision and all submission answers.
-3. Resolve required organization/approver choices.
-4. Start with a stable idempotency key distinct from the draft-save key.
+1. Commit the bounded Native mutation and Workflow intent as one durable command.
+2. Persist `commandId` in the route and reload `ProcessCommandSurface` after refresh.
+3. Answer only requirements emitted for that command revision.
+4. Let the platform worker start the pinned Workflow exactly once.
 5. Use the Surface revision/concurrency token for every command.
 
 Duplicate commands return the stored command receipt. Stale revisions fail with a structured conflict. A task/participant state transition, operation log, Workflow fact and event outbox commit atomically.
@@ -135,8 +141,8 @@ back silently.
 Standard launch entry is also a platform Surface. Desktop uses
 `/admin/workflows/:workflowCode/new` and mobile uses
 `/m/workflows/:workflowCode/start`; both first load
-`loadWorkflowLaunchSurface(workflowCode)`, then use the same durable
-`saveBusinessRevision -> prepareWorkflowStart -> startWorkflow` protocol.
+`loadWorkflowLaunchSurface(workflowCode)`, verify its compiler-owned subject and
+process operation, then use the standard durable process commit.
 `custom-page` and `work-center-only` declarations do not expose the standard
 launch Surface. After start, navigate through the device's standard instance
 entry so the current `detailRouteCode` contract can redirect consistently.
@@ -158,7 +164,12 @@ Use direct card actions first for approve/reject. Return, transfer, delegate and
 
 ## Event handling
 
-Consume typed participant/task/instance facts with durable idempotency. Order Workflow message projection by `instanceId + instanceSequence`; never assume global event order. Terminal instance facts dominate stale participant facts and update every historical message for that instance.
+Consume typed participant/task/instance facts with durable idempotency. Declare
+event delivery `ordering: 'workflow-instance'` when the handler requires the
+platform to serialize by instance; `workflow_instance` is not an alias. Still
+verify `instanceSequence` in the consumer and never assume global event order.
+Terminal instance facts dominate stale participant facts and update every
+historical message for that instance.
 
 For Native Data facts, the platform owns the capture plan under the exact Event
 revision, Data revision, AuthZ revision and resource tuple selected by the

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

@@ -14,6 +14,7 @@
 - Use the current logged-in user and the union of that user's application roles. An optional declared Perspective projects only read visibility (pages, rows and fields); create/update/delete, workflows and custom actions continue to authorize against the complete union. Standard Data API calls inherit `X-OpenXiangda-Perspective` automatically. Use `@CurrentPerspective()` only when custom Nest code reads outside the standard Data API, and apply an equivalent read projection explicitly. Business code must not persist a platform Token or authorization result and must not implement a second identity path.
 - Fields inherit the resource read/create/update capabilities. Use field `access` only to tighten them; arrays are all-of and `false` is explicit deny. There is no `write` fallback.
 - Field `type` is semantic, never a hand-authored database type. The supported catalog is exactly `text.short`, `text.long`, `text.rich`, `number.integer`, `number.decimal`, `boolean`, `date`, `time`, `datetime`, `date-range`, `datetime-range`, `option.single`, `option.multiple`, `cascade.single`, `cascade.multiple`, `user.single`, `user.multiple`, `department.single`, `department.multiple`, `resource-ref.single`, `resource-ref.multiple`, `file`, `image`, `signature`, `address`, `location`, `json`, `serial-number`, `uuid` and `subtable`. The compiler alone derives PostgreSQL columns, constraints and indexes.
+- Every `date-range` and `datetime-range` field explicitly declares `rangeBoundary: 'closed' | 'half-open'`. Values remain `{ start, end }`; callers never send or override the boundary. Closed ranges allow `start <= end` and use PostgreSQL `[]`; half-open ranges require `start < end` and use `[)`.
 - Declare every custom operation capability in `authz.capabilities` with `kind: 'backend'`, then reference that same code from the operation and its allowed roles. Generated resource CRUD capabilities do not go in this catalog.
 - Build App Operation request/response schemas with `resourceRecordSchema`, `schemaRef`, `composeJsonSchema` and `composeAppOperationSchemas` from `openxiangda/config`. They project the same Resource declaration and canonical field value protocols; never import a physical toolchain package or repeat user, department, resource-reference or managed-file schemas by hand.
 - 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.
@@ -21,6 +22,6 @@
 - `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.
 - 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 the canonical `openxiangda.config.ts` declarations and generated clients; declare each Workflow launch as `standalone`, `custom-page`, `hidden-handoff` or `work-center-only`, put only self-contained standalone launch pages in navigation, and bind durable save handlers with `defineWorkflowLaunchContributions` without repeating generated titles. Desktop and mobile standard launch pages load the same canonical Workflow launch Surface. To replace Workflow detail, declare both desktop and mobile `detailRouteCode` values whose routes contain exactly `:instanceId`; Work Center, the application todo center and notification channels consume the platform-resolved paths, while every Surface and command remains server-authorized. Add the standard current-user todo page only with `adminApplicationTodoCenterPage()`; never query Notification Hub management APIs from a user page. Never depend on temporary router location state or copy 1.x workflow/message code, tables, APIs, templates or callbacks into this workspace. Keep ordinary CRUD and application-specific state machines independent of them.
+- 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` use the compiler-owned process operation and Durable Business Process Command; 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 `adminApplicationTodoCenterPage()`; 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.
 - AI-native clients start the workspace protocol through the same pinned binary: `pnpm exec openxiangda --mcp-stdio --cwd <workspace>`. Read `openxiangda://workspace/contracts` or call `contract_describe`; for first-time menu authoring, copy `data.adminNavigationAuthoring.suggestion.expression` once into `frontend.admin.navigation` with its listed `openxiangda/config` imports, then edit that application-owned declaration. Never treat the proposal as runtime discovery. When AppSpec is enabled, also read `openxiangda://workspace/appspec` or call `appspec_context`. Require `aiCatalog` and `aiCatalogDigest` to match the normal compiler output. This is a stdio transport mode, not another application-owned server. Never write an application MCP server, Catalog file, preview store or second authorization path.