openxiangda-skill-kit 2.0.0-alpha.79 → 2.0.0-alpha.80

package/package.json

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

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

@@ -1,6 +1,20 @@
 # OpenXiangda 2.0 Backend
 
-Keep normal record CRUD in the platform Data API. Use `apps/server` only for typed business actions that need server-side logic. For an interactive request, the platform gateway supplies the verified current user, complete application-role union and capabilities from the same platform authorization snapshot used by Data API. Controllers bind operations and capabilities through `openxiangda/nest`; workers continue to use their explicit application identity.
+Keep normal record CRUD in the platform Data API. Use `apps/server` only for typed business actions that need server-side logic. For an interactive request, the platform gateway supplies the verified current user, complete application-role union and capabilities. Controllers bind operations and capabilities through `openxiangda/nest`; workers continue to use their explicit application identity.
+
+Every interactive business action uses `@OpenXiangdaOperation(operation)`. The
+guard checks `operation.requiredCapability` once at App API ingress. Inside that
+declared action, inject `OpenXiangdaBusinessDataApiService` or use
+`OpenXiangdaStandardOperations`: Native Data then runs as the trusted backend
+for this exact application, environment, version and operation. Do not forward
+the caller's resource, row or field permissions into that internal Data call,
+and do not author an `authorizationJSON` permission mirror. The platform still
+records the initiating user and action code in records, files, events and audit.
+
+`OpenXiangdaDataApiService` deliberately retains ordinary current-user Data
+authorization. Do not use it to implement a declared business action. The
+business facade also rejects routes without immutable `OpenXiangdaOperation`
+metadata, so a controller cannot silently gain trusted Data access.
 
 Do not duplicate resource persistence in controllers. Keep actions bounded and side-effect behavior explicit. Run `pnpm openxiangda dev` for the connected loop and `pnpm openxiangda check` before delivery.
 
@@ -16,15 +30,25 @@ Every constructor dependency in a `@Controller` or `@Injectable` class uses an
 explicit token:
 
 ```ts
-import { Controller, Inject } from '@nestjs/common';
-import { OpenXiangdaStandardOperations } from 'openxiangda/nest';
-
-@Controller('/api/visitor-reservations')
+import { Controller, Inject, Post } from '@nestjs/common';
+import { appOperations } from '@app/contracts';
+import {
+  OpenXiangdaBusinessDataApiService,
+  OpenXiangdaOperation,
+} from 'openxiangda/nest';
+
+@Controller()
 export class VisitorReservationsController {
   constructor(
-    @Inject(OpenXiangdaStandardOperations)
-    private readonly operations: OpenXiangdaStandardOperations,
+    @Inject(OpenXiangdaBusinessDataApiService)
+    private readonly data: OpenXiangdaBusinessDataApiService,
   ) {}
+
+  @Post('/api/reservations/enroll')
+  @OpenXiangdaOperation(appOperations.reservationEnroll)
+  async enroll() {
+    return await this.data.create('visitor-reservations', { status: 'pending' });
+  }
 }
 ```
 

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

@@ -65,7 +65,7 @@ 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.
 
-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 complete labeled snapshots; resource references additionally declare their source and snapshot fields. 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.
+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.
 
 Do not author raw schema or storage words as field types. `string`, `text`,
 `integer`, `decimal`, `boolean`, `date`, `datetime`, `uuid`, `json` and `file`

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

@@ -1,6 +1,22 @@
 # OpenXiangda 2.0 Delivery
 
-Run `pnpm openxiangda check`; it owns generation, static checks, tests and production builds. Deploy to test with `pnpm openxiangda deploy`. The CLI uses the official application Dockerfile and the platform-provided repository target to build and push the Nest image, then seals only its immutable digest. Never ask the developer for an image tag, digest, registry password, Docker configuration, or another public build command. If Docker, Buildx, repository configuration, or registry login is missing, preserve the stable machine error and retry with the same `pnpm openxiangda deploy` command after fixing that prerequisite.
+Run `pnpm openxiangda check --json`; it owns generation, static checks, tests
+and production builds but deliberately does not seal an AppPackage. Its
+`data.sealedArtifact` object and `.openxiangda/build/seal-status.json` make that
+state explicit even when an older `app-package.json` remains on disk. Deploy to
+test with the returned `openxiangda deploy` next command. Deploy owns the
+official application Dockerfile and platform-provided repository target,
+builds and pushes the Nest image, then writes a `sealed` status tied to the new
+immutable package digest. Never ask the developer for an image tag, digest,
+registry password, Docker configuration, or another public build command. If
+Docker, Buildx, repository configuration, or registry login is missing,
+preserve the stable machine error and retry with the same
+`pnpm openxiangda deploy` command after fixing that prerequisite.
+
+`pnpm openxiangda accept --plan <file>` is an optional manual preproduction
+test helper. It prepares expiring real identities but does not deploy, seal,
+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.
 

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

@@ -1,6 +1,14 @@
 # Testing and Acceptance
 
-Run `pnpm openxiangda check` after declaration or code changes. It owns generation, static validation, unit tests and production builds; preserve its stable diagnostic instead of bypassing a failing stage.
+Run `pnpm openxiangda check --json` after declaration or code changes. It owns
+generation, static validation, unit tests and production builds; preserve its
+stable diagnostic instead of bypassing a failing stage. Read
+`data.sealedArtifact` in the machine result. A successful check always reports
+`state: "check-did-not-seal"`, `sealed: false` and
+`usableForDeploy: false`; it may also describe an older package as
+`previousArtifact`. Never treat an existing `.openxiangda/build/app-package.json`
+as output from the current check. Follow the exact `nextCommand`: rerun check
+when diagnostics fail, or run `openxiangda deploy` to build, seal and deploy.
 
 For each changed resource, verify the real chain:
 
@@ -11,6 +19,33 @@ For each changed resource, verify the real chain:
 5. stored values and audit records match the declared shape;
 6. PostgreSQL/RLS remains authoritative, including current-user and multi-role-union cases.
 
-Mock and unit tests are useful but do not close remote acceptance. Before production, deploy to preproduction and capture the exact AppVersion, environment Head, test identities, positive/negative results, browser behavior and request identifiers. Production promotion reuses that exact successful version; it is not another build.
+Mock and unit tests are useful but do not close remote acceptance. When real
+identity acceptance is needed, create a short-lived local plan and run:
+
+```bash
+pnpm openxiangda accept --plan .openxiangda/acceptance-plan.json --json
+```
+
+The plan is explicit and preproduction-only:
+
+```json
+{
+  "schemaVersion": "openxiangda.preproduction-acceptance-plan/v2",
+  "environmentKey": "preproduction",
+  "expiresInMinutes": 240,
+  "actors": [
+    { "key": "allowed", "roleCodes": ["resource_admin"] },
+    { "key": "denied", "roleCodes": ["resource_viewer"] }
+  ]
+}
+```
+
+The result returns real temporary users and one-time login URLs. Treat those
+URLs as secrets, do not commit the plan/result, and let them expire. `accept`
+is an additional manual test facility: it is never called by `check` or
+`deploy`, never becomes a release gate, and a skipped run must not block a
+release. When it is used, capture the exact AppVersion, environment Head,
+positive/negative result, browser behavior and request identifiers. Production
+promotion reuses the exact successful version; it is not another build.
 
 For a new toolchain release, also create a completely fresh workspace using only the packed or published `openxiangda` package. Do not use repository-relative imports, unpublished workspace links or machine-installed legacy Skills.

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

@@ -6,16 +6,17 @@
 - Never write resource-level `schemaVersion`, `appCode`, `schema`, `surface`, `capabilities`, `fieldPolicies` or `platform/data` modules. The compiler derives the strict DataResource, CRUD capabilities, Surface and AI Schema. The application manifest still starts with its one top-level `schemaVersion: 3`.
 - Ordinary list/get/create/update/delete, filters, export and batch operations use the platform Native Data API. Do not create Function CRUD or NestJS wrappers.
 - Add NestJS only for a named business action that needs a cross-resource transaction, an invariant or an external side effect.
+- Every interactive business action binds `@OpenXiangdaOperation(operation)` and injects `OpenXiangdaBusinessDataApiService` or `OpenXiangdaStandardOperations`. The platform checks the action capability once at App API ingress; the trusted backend then has full Data access only to its exact application/environment while audit retains the initiating user. Do not author `authorizationJSON` or reapply the user's resource, row and field permissions inside the action.
 - A NestJS backend declares only `enabled`, `isolation: 'shared' | 'dedicated'` and `resourceProfile: 'light' | 'standard'`. Never put raw Kubernetes resources, replicas, ports or environment maps in application metadata; the platform owns capacity and scaling.
 - Use the current logged-in user and the union of that user's application roles. The generated client uses same-origin cookies and does not transmit a RoleSession header. 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.
 - 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.
 - 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, departments and resource references store their complete display snapshots; 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 snapshot and multiple values store snapshot arrays. 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`.
+- 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.
 - 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; never 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.
-- Run `pnpm openxiangda check` after contract changes. 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.
+- 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`, and require its `aiCatalog` and `aiCatalogDigest` to match the normal compiler output. This is a stdio transport mode, not a ninth CLI command. Never write an application MCP server, Catalog file, preview store or second authorization path.