openyida 2026.8.27-beta.0 → 2026.8.28

package/README.md

@@ -50,6 +50,10 @@ npm install -g openyida
 
 OpenYida requires Node.js 18 or later. The package exposes both `openyida` and `yida` commands.
 
+For npm global installations, OpenYida checks the npm registry before a normal command at most once every 24 hours. When a newer version is available, it installs that exact version and then reruns the original command. This behavior is identical whether the local command is launched from a terminal, Codex, Claude Code, or Qoder. Managed cloud Agent runtimes are excluded before any cache access, registry request, or npm invocation.
+
+Set `OPENYIDA_NO_AUTO_UPDATE=1` to disable automatic updates. `OPENYIDA_AUTO_UPDATE_SECS` can override the check interval for development and testing. The explicit `openyida update` command remains available.
+
 If Codex is already installed, OpenYida also imports a local Codex plugin during postinstall. Restart Codex after installation, then type `@宜搭` or `@openyida` in the composer to attach the OpenYida context.
 
 ### 2. Check Your Environment
@@ -105,21 +109,7 @@ Build an IPD workflow for chip production, including approval nodes and dashboar
 Generate a public landing page and publish it to my Yida app.
 ```
 
-The agent can then call OpenYida commands to create the application, generate source files, publish pages, and return the final Yida URLs. In Codex, QwenWork, QoderWork, Qoder, and Wukong environments, successful creation and publish commands also include a browser handoff so the agent can open the resulting Yida page in the in-app browser. Use `--open` to force this handoff or `--no-open` to suppress it.
-
-## Wukong Installation
-
-Wukong uses manual skill package installation instead of npm:
-
-1. Download the latest `.zip` skill package from [GitHub Releases](https://github.com/openyida/openyida/releases).
-2. Open Wukong.
-3. Go to **Skill Center** > **Upload Skill** and select the downloaded package.
-
-For Wukong terminal work, make sure its bundled Node.js path is active before running `node`, `npm`, or `npx` commands:
-
-```bash
-export PATH="$HOME/.real/.bin/node/bin:$PATH"
-```
+The agent can then call OpenYida commands to create the application, generate source files, publish pages, and return the final Yida URLs. In Codex, QwenWork, Qoder, Qoder IDE, and QoderWork environments, successful creation and publish commands also include a browser handoff so the agent can open the resulting Yida page in the in-app browser. Use `--open` to force this handoff or `--no-open` to suppress it.
 
 ## Supported AI Coding Tools
 
@@ -128,14 +118,13 @@ export PATH="$HOME/.real/.bin/node/bin:$PATH"
 | [Codex](https://openai.com/codex/) | Full support |
 | [Claude Code](https://claude.ai/code) | Full support |
 | [MuleRun](https://mulerun.com) | Full support |
-| [Aone Copilot](https://copilot.code.alibaba-inc.com) | Full support |
 | [OpenCode](https://opencode.ai) | Full support |
 | [Cursor](https://cursor.com/) | Full support |
 | [Visual Studio Code](https://code.visualstudio.com/) | Full support |
 | QwenWork（千问办公） | Full support |
-| [QoderWork](https://qoder.com) | Full support |
-| [Qoder](https://qoder.com) | Full support |
-| [Wukong](https://dingtalk.com/wukong) | Full support |
+| [Qoder](https://qoder.com/download) | Full support |
+| [Qoder IDE](https://qoder.com/ide) | Full support |
+| [QoderWork](https://qoder.com/download) | Full support |
 
 ## How It Works
 
@@ -232,6 +221,10 @@ openyida get-permission APP_XXX FORM_XXX
 }
 ```
 
+`configure-process` 会先通过表单绑定和流程版本只读接口证明 `processCode` ownership。目标已有 PUBLISHED 流程或 SAVED 草稿时，整图替换必须在人工确认后显式传入 `--replace`；未确认或 ownership 不匹配时远程写入数为 0。draft/save/publish 均为 one-shot，认证异常返回 `NON_IDEMPOTENT_RESULT_UNKNOWN`，不得自动重试。
+
+发布成功还必须精确回读同一 PUBLISHED `processId/processVersion` 的 `getProcessById` 平台视图，并验证可见节点的组件、名称、顺序和审批模式。只有输出 `verificationLevel: "PLATFORM_VIEW_VERIFIED"` 才表示平台 view 已验证；`PUBLISHED_UNVERIFIED` 表示发布可能已生效但回读不完整，不能宣称 `processJson` 已验证，也不能直接重放写请求。
+
 When creating or updating test data with `openyida data`, Yida date fields must use 13-digit millisecond timestamps, for example `"dateField_xxx": 1719705600000`. Do not submit `YYYY-MM-DD` strings for `DateField` or `CascadeDateField` values.
 Temporary JSON, CSV, and one-off import scripts should live under `.cache/openyida/` so generated run artifacts do not clutter the repository root.
 
@@ -320,8 +313,6 @@ OPENYIDA_E2E=1 npm run eval:all -- --skill yida-dashboard --screenshot
 # whitelist. Use the Node version you start it with, so run `nvm use 20` first.
 npm run eval:dashboard          # http://127.0.0.1:4500
 
-# You can also run eval directly via the CLI:
-openyida eval --mode comprehensive --skill yida-dashboard
 ```
 
 Configuration precedence is `CLI flag > env (OPENYIDA_EVAL_*) > scripts/eval/eval.config.json > defaults`.
@@ -354,8 +345,19 @@ openyida integration update APP_XXX FORM_XXX LPROC_XXX \
   --spec .cache/openyida/integration/desired-spec.json
 openyida create-report APP_XXX "Sales Dashboard" .cache/openyida/reports/charts.json
 openyida append-chart APP_XXX REPORT_XXX .cache/openyida/reports/chart.json
+
+# Aggregate tables use two independent optimistic-concurrency axes.
+openyida aggregate-table inspect APP_XXX FORM_XXX --json
+openyida aggregate-table preview APP_XXX FORM_XXX .cache/openyida/aggregate/design.json --json
+openyida aggregate-table save APP_XXX FORM_XXX .cache/openyida/aggregate/design.json --json --no-open
+openyida aggregate-table publish APP_XXX FORM_XXX .cache/openyida/aggregate/design.json --json --no-open
+openyida aggregate-table status APP_XXX FORM_XXX --json
 ```
 
+Aggregate-table `save` verifies the draft `stashGmtModified` axis; `publish` verifies the live `gmtModified` axis. Both commands require the corresponding GET readback revision to advance; when a response revision exists it must equal that readback axis. Both commands also require canonical readback of `relationForms`, `relationships`, `aggregatedFields`, `auxFields`, `formulaFields`, and `validators`. The CLI intentionally does not expose aggregate-table deletion, AI authoring, a high-level design DSL, or tenant-dynamic limits until the corresponding platform contracts are proven.
+
+The opt-in aggregate real-E2E runner additionally requires `OPENYIDA_AGGREGATE_E2E_RUN_ID` and an exact `OPENYIDA_AGGREGATE_E2E_OWNED_MARKER` beginning with `<runId>__`. Before its first write it verifies the exact list/inspect identity and name, persists a redacted manifest, registry, and baseline snapshot, then conditionally restores the baseline using the latest live revision. Missing ownership proof or concurrent revision movement produces `PLATFORM_PROBE_REQUIRED` / `restore_blocked` without a restore write.
+
 ## CLI Reference
 
 Run `openyida --help` or `openyida <command> --help` for detailed usage.
@@ -436,8 +438,8 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 
 | Command | Description |
 |---------|-------------|
-| `openyida configure-process <appType> ...` | Configure and publish process rules |
-| `openyida create-process <appType> ...` | Create process form (all-in-one) |
+| `openyida configure-process <appType> <formUuid> <definition> [processCode] [--replace]` | Configure and publish process rules |
+| `openyida create-process <appType> ... [--replace]` | Create process form (all-in-one) |
 | `openyida ai-form-setting <get\|fields\|models\|enable\|disable\|save> <appType> ...` | Manage process form AI approval prompts |
 | `openyida process preview <appType> ...` | Preview process instance (visual flowchart) |
 
@@ -456,6 +458,7 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 |---------|-------------|
 | `openyida create-report <appType> "<name>" ... [--open\|--no-open]` | Create a Yida report |
 | `openyida append-chart <appType> <reportId> ... [--open\|--no-open]` | Append chart to existing report |
+| `openyida report inspect <appType> <reportId> --json` | Inspect report runtime bindings (read-only) |
 
 ### Connectors
 
@@ -466,12 +469,13 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 | `openyida connector detail <id>` | View connector details |
 | `openyida connector delete <id> [--force]` | Show manual deletion guidance (CLI does not delete) |
 | `openyida connector add-action --operations <file> --connector-id <id>` | Add an action |
+| `openyida connector update-action --connector-id <id> --action <operationId> --query-json JSON --confirm` | Safely update action query defaults |
 | `openyida connector list-actions <id>` | List actions |
 | `openyida connector delete-action <id> <operation-id>` | Delete an action |
-| `openyida connector test --connector-id <id> --action <actionId>` | Test an action |
+| `openyida connector test --connector-id <id> --action <actionId> [--path-json JSON] [--query-json JSON] [--header-json JSON] [--body-json JSON] [--account-id <id>]` | Test an action |
 | `openyida connector list-connections <id>` | List auth connections |
 | `openyida connector create-connection <id> <name>` | Create an auth connection |
-| `openyida connector smart-create --curl "..."` | Smart create connector (from cURL) |
+| `openyida connector smart-create --curl "..."` | Generate a redacted action draft from cURL (no remote create) |
 | `openyida connector parse-api [options]` | Parse API information |
 | `openyida connector gen-template [output]` | Generate API document template |
 
@@ -501,7 +505,6 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 | `openyida copy [--force]` | Copy project working directory |
 | `openyida sample [--list]` | Output code samples/templates |
 | `openyida doctor [--fix]` | Environment diagnostics & auto-fix |
-| `openyida eval --mode <mode> [--skill <name>] [--runs N]` | Multi-dimensional skill evaluation (doc quality, routing accuracy, safety, etc.) |
 | `openyida db-seq-fix [--fix]` | Detect and repair PostgreSQL sequence drift |
 | `openyida formula evaluate <formula\|file> [--schema file]` | Static-check Yida formula syntax and field refs |
 | `openyida update` | Check and update to latest version |
@@ -519,6 +522,28 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 
 ### CLI Notes
 
+#### Connector Safety and Real E2E
+
+`connector test` keeps the legacy flat `--params` option, but dispatches each key only to the location proven by the action schema. Unknown or ambiguous keys fail closed. Authenticated connectors require `--account-id`, and that account must belong to the selected connector. The test response follows the frontend canonical contract `{statusLine,responseHeaders,content}`; unknown envelopes and non-2xx status lines are failures.
+
+`connector update-action --connector-id <id> --action <operationId> --query-json '{"currentPage":"1"}' --confirm` is the narrow safe path for editing existing query defaults. It requires a complete connector/action preflight, changes only declared query defaults mirrored in `inputs` and `parameters`, submits the complete action collection once, and verifies an unchanged connector fingerprint, action count, non-target actions, and stable IDs. Missing/empty/unknown parameters, duplicate IDs, incomplete readback, and unknown write outcomes fail closed without automatic retry. `add-action` no longer overwrites an existing action ID; use `update-action` for query-only edits.
+
+The opt-in connector E2E is intentionally separate from the shared full runner:
+
+```bash
+OPENYIDA_E2E=1 \
+OPENYIDA_E2E_CONNECTOR=1 \
+OPENYIDA_E2E_CORP_ID='<target-corp-id>' \
+OPENYIDA_E2E_CONNECTOR_ECHO_URL='https://<team-controlled-host>/<stable-echo-path>' \
+OPENYIDA_E2E_CONNECTOR_FIXTURE_MARKER='<expected-response-marker>' \
+OPENYIDA_E2E_CONNECTOR_FIXTURE_OWNER='<expected-owner-header-value>' \
+node scripts/e2e-real/connector/runner.js
+```
+
+The runner rejects public generic echo services such as httpbin and example.com. Before its first remote write it selects and verifies the explicit organization profile, prints a redacted resource plan, and persists synchronized registry/manifest evidence plus the SHA-256 of the preserved operations fixture. The controlled fixture must return exact JSON fields `content.runId`, `content.fixtureMarker`, and `content.authorization === "Basic ***"`, plus the exact `x-openyida-fixture-owner` response header. Substring matches, malformed JSON, and wrong fields fail closed. Each remote create is persisted as `attempted` before execution and becomes `completed` only after exact readback; an exception is recorded as `outcome_unknown` with a non-owned residual candidate and is never retried. The runner deletes only its temporary local copy and reports remote connector/account cleanup as blocked because the CLI has no proven delete API. If organization or fixture ownership cannot be proven, it returns `PLATFORM_PROBE_REQUIRED` with zero remote writes.
+
+The opt-in `node scripts/e2e-real/connector/action-update-runner.js` regression uses the owner-confirmed login-free `www.aliwork.com` fixture and a single owned NONE-auth connector containing a target action plus one preservation sentinel. Enable it with `OPENYIDA_E2E=1 OPENYIDA_E2E_CONNECTOR_ACTION_UPDATE=1`. It verifies isolated `currentPage`, `pageSize`, `userLanguage`, `searchFieldJson`, and dynamic `_stamp` edits, restores each field and the final baseline, and persists only response structure, data count, and SHA-256. It never stores response row values or auth/profile/corp identifiers, never retries unknown writes, and intentionally leaves the owned connector as a `cleanup_blocked` residual because no proven delete API exists.
+
 `openyida asset resolve --hero <path-or-url> --product <path-or-url> --require-hero --upload-assets --json` is the preferred preflight for homepage visuals. It verifies public image URLs, uploads local images when CDN is configured, mirrors verified external images to CDN when `--upload-assets` is passed, and returns `materialStatus: final|draft|none` so agents do not claim an unfinished visual page is final.
 
 #### Environment and Localization
@@ -545,22 +570,20 @@ Form field definitions can include `alias` or `componentAlias` to populate Yida
 
 ## Agent Skills
 
-The `yida-skills/` directory is the source skill library used by OpenYida during development. Release assets for Wukong are generated by `npm run build:skills`: the expanded package is written to `dist/skills/openyida/`, and the upload-ready zip is written to `openyida-skills.zip`.
+The `yida-skills/` directory is the source skill library used by OpenYida during development and distributed with the npm package.
 
 | Path | Purpose |
 |------|---------|
 | `yida-skills/SKILL.md` | Entry point and skill index |
 | `yida-skills/skills/` | Self-contained sub-skills for app, form, process, page, data, and integration work |
 | `yida-skills/references/` | Shared Yida API, model API, and query-condition references |
-| `dist/skills/openyida/` | Generated Wukong upload package root; contains one root `SKILL.md` and reference-only subskill docs |
-| `openyida-skills.zip` | Generated Wukong upload package; upload this file in Wukong |
 
 When OpenYida is used inside a supported AI coding environment, these skills help the agent choose the right command sequence and file conventions.
 
-For Wukong manual import, upload the generated `openyida-skills.zip`. The package follows Wukong's custom skill rules: folder name and `frontmatter.name` are both `openyida`, root frontmatter only contains `name` and `description`, and long references live under `references/`.
-
 For QwenWork, use the same user-level global skills layout as QoderWork: `~/.qwenworkcn/skills/yida-skills/`. Skip QwenWork setup when `~/.qwenworkcn` is not present.
 
+Qoder and Qoder IDE share the user-level `~/.qoder/skills/yida-skills/` directory. QoderWork remains a separate product and uses `~/.qoderwork/skills/yida-skills/`.
+
 For Codex, `npm install -g openyida` additionally creates a local plugin marketplace under `~/.openyida/codex-plugin` and enables `openyida@openyida` in `~/.codex/config.toml` when Codex is detected. This makes OpenYida show up in Codex's `@` plugin menu as **宜搭** after Codex reloads.
 
 ## Examples

package/bin/yida.js

@@ -20,77 +20,6 @@ const command = process.argv[2];
 const args = process.argv.slice(3);
 const rawArgs = process.argv.slice(3);
 
-function isAgentEnvironment(env) {
-  return !!(
-    env.CODEX_SHELL ||
-    env.CODEX_CI ||
-    env.CODEX_THREAD_ID ||
-    env.CODEX_HOME ||
-    env.CLAUDE_CODE ||
-    env.CLAUDE_CODE_ENTRYPOINT ||
-    env.MULERUN_CHAT_ID ||
-    env.MULE_DATA_DIR ||
-    env.MULE_WORKSPACE_DIR ||
-    env.OPENCODE ||
-    env.OPENCODE_CLIENT ||
-    env.QODER_IDE ||
-    env.QODER_AGENT ||
-    env.QODERCLI_INTEGRATION_MODE ||
-    env.QODER_WORK_INTEGRATION_PRODUCT ||
-    env.QWENWORK_INTEGRATION_MODE ||
-    env.QWENWORKCN_INTEGRATION_MODE ||
-    env.QWENWORK ||
-    env.QWENWORK_CLIENT ||
-    env.QWENWORK_WORKSPACE_DIR ||
-    env.QWENWORK_SANDBOX_ID ||
-    env.QWENWORK_PREVIEW_URL ||
-    env.QWENWORK_VNC_URL ||
-    (env.AGENT_PLATFORM || '').toLowerCase().includes('qwenwork') ||
-    env.CURSOR_TRACE_ID ||
-    env.AGENT_WORK_ROOT ||
-    env.OPENYIDA_AGENT_MODE ||
-    (env.__CFBundleIdentifier || '').toLowerCase().includes('codex') ||
-    (env.__CFBundleIdentifier || '').toLowerCase().includes('qoder') ||
-    (env.__CFBundleIdentifier || '').toLowerCase().includes('qwenwork') ||
-    (env.__CFBundleIdentifier || '').toLowerCase().includes('qwen-work')
-  );
-}
-
-function shouldRunUpdateCheck() {
-  if (process.env.OPENYIDA_SKIP_UPDATE_CHECK || process.env.NO_UPDATE_NOTIFIER) {
-    return false;
-  }
-  if (process.env.CI || isAgentEnvironment(process.env)) {
-    return false;
-  }
-  if (!process.stderr.isTTY) {
-    return false;
-  }
-  if (!command || command === '--help' || command === '-h' || command === '--version' || command === '-v') {
-    return false;
-  }
-  if (args.includes('--help') || args.includes('-h')) {
-    return false;
-  }
-  if (command === 'commands' || command === 'agent-capabilities' || command === 'mcp') {
-    return false;
-  }
-  if (args.includes('--json') || args.includes('--check-only')) {
-    return false;
-  }
-  return true;
-}
-
-function maybeCheckForUpdate() {
-  if (!shouldRunUpdateCheck()) {
-    return;
-  }
-  const { checkUpdate } = require('../lib/core/check-update');
-  checkUpdate(currentVersion).catch(() => {});
-}
-
-maybeCheckForUpdate();
-
 function shouldUseEnvManagement(argsList) {
   const subCommand = argsList[0];
   return !!subCommand && subCommand !== '--json';
@@ -369,7 +298,6 @@ const UNSUPPORTED_LEGACY_LOGIN_FLAGS = new Set([
   '--browser',
   '--codex',
   '--qoder',
-  '--wukong',
 ]);
 
 function findUnsupportedLegacyLoginFlag(...argLists) {
@@ -598,6 +526,18 @@ async function main() {
   applyQuietFlag();
   applyGlobalEnvironmentFlags();
 
+  const { maybeAutoUpdate } = require('../lib/core/update');
+  const updateResult = await maybeAutoUpdate({
+    currentVersion,
+    command,
+    args,
+    argv: process.argv,
+  });
+  if (updateResult.reexecuted) {
+    process.exitCode = updateResult.exitCode;
+    return;
+  }
+
   if (!command || command === '--help' || command === '-h') {
     handleFirstRunGuide();
     printHelp();
@@ -1059,6 +999,16 @@ async function main() {
       break;
     }
 
+    case 'report': {
+      const subCommand = args[0];
+      if (subCommand !== 'inspect') {
+        throwCliUsage('用法: openyida report inspect <appType> <reportId> --json');
+      }
+      const { run } = require('../lib/report/inspect');
+      await run(args.slice(1));
+      break;
+    }
+
     case 'cdn-config': {
       const { run: runCdnConfig } = require('../lib/cdn/cdn-config-cmd');
       await runCdnConfig(args);
@@ -1093,6 +1043,7 @@ async function main() {
         'detail':            '../lib/connector/connector-detail',
         'delete':            '../lib/connector/connector-delete',
         'add-action':        '../lib/connector/connector-add-action',
+        'update-action':     '../lib/connector/connector-update-action',
         'list-actions':      '../lib/connector/connector-list-actions',
         'delete-action':     '../lib/connector/connector-delete-action',
         'test':              '../lib/connector/connector-test',
@@ -1113,12 +1064,13 @@ async function main() {
   detail <connector-id>                        查看连接器详情
   delete <connector-id> [--force]              删除连接器
   add-action --operations <file> --connector-id <id>  添加执行动作
+  update-action --connector-id <id> --action <id> --query-json <JSON> --confirm  安全更新动作 Query 默认值
   list-actions <connector-id>                  列出执行动作
   delete-action <connector-id> <operation-id>  删除执行动作
-  test --connector-id <id> --action <actionId> 测试执行动作
+  test --connector-id <id> --action <actionId> [结构化 JSON 参数] 测试执行动作
   list-connections <connector-id>              列出鉴权账号
   create-connection <connector-id> <name>      创建鉴权账号
-  smart-create --curl "curl命令"               智能创建连接器
+  smart-create --curl "curl命令"               生成脱敏连接器动作草稿（不创建远端资源）
   parse-api [选项]                             解析接口信息
   gen-template [输出路径]                       生成接口文档模板
 
@@ -1258,12 +1210,6 @@ async function main() {
       break;
     }
 
-    case 'eval': {
-      const { main: evalMain } = require('../scripts/eval/runner');
-      await evalMain(args);
-      break;
-    }
-
     default: {
       throwUnknownCommand(command, args);
     }

package/lib/aggregate-table/aggregate-table.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const querystring = require('querystring');
 
+const { CliError } = require('../core/cli-error');
 const { createAuthRef: createCoreAuthRef, createYidaClient, isAuthRefReady } = require('../core/yida-client');
 const { t } = require('../core/i18n');
 const { buildYidaTitleI18n, normalizeYidaLocale, resolveContentLocale } = require('../core/yida-i18n');
@@ -15,6 +16,10 @@ const {
 } = require('./contract');
 
 const FORM_TYPE_VIRTUAL_VIEW = 'virtualView';
+const ACTION_REVISION_AXES = Object.freeze({
+  save: 'stashGmtModified',
+  publish: 'gmtModified',
+});
 
 function hasHelpFlag(args) {
   return (args || []).includes('--help') || (args || []).includes('-h');
@@ -48,6 +53,7 @@ function parseFlags(args) {
     json: false,
     keyword: '',
     locale: null,
+    expectedRevision: null,
   };
 
   for (let index = 0; index < openOption.args.length; index++) {
@@ -68,6 +74,10 @@ function parseFlags(args) {
       flags.locale = locale;
       continue;
     }
+    if (arg === '--expected-revision' && openOption.args[index + 1]) {
+      flags.expectedRevision = openOption.args[++index];
+      continue;
+    }
     positional.push(arg);
   }
 
@@ -236,11 +246,67 @@ function normalizeDesignConfig(rawConfig, formUuid) {
 
   const normalized = { formUuid };
   for (const key of DESIGN_KEYS) {
-    normalized[key] = Array.isArray(config[key]) ? config[key] : [];
+    normalized[key] = config[key] === undefined ? [] : config[key];
   }
   return normalized;
 }
 
+function getActionRevisionAxis(action) {
+  const axis = ACTION_REVISION_AXES[action];
+  if (!axis) {
+    throw new Error(`Unknown aggregate table revision action: ${action}`);
+  }
+  return axis;
+}
+
+function selectActionRevision(config, action) {
+  const axis = getActionRevisionAxis(action);
+  return config && config[axis];
+}
+
+function isMissingRevision(value) {
+  return value === undefined || value === null || value === '';
+}
+
+function assertActionRevisionAdvanced(action, beforeConfig, responseContent, readbackConfig) {
+  const revisionAxis = getActionRevisionAxis(action);
+  const beforeRevision = selectActionRevision(beforeConfig, action);
+  const responseRevision = responseContent && responseContent.gmtModified;
+  const readbackRevision = selectActionRevision(readbackConfig, action);
+
+  if (isMissingRevision(readbackRevision)) {
+    const error = new Error('AGGREGATE_WRITE_READBACK_REVISION_MISSING');
+    error.code = 'AGGREGATE_WRITE_READBACK_REVISION_MISSING';
+    throw error;
+  }
+  if (!isMissingRevision(beforeRevision) && String(readbackRevision) === String(beforeRevision)) {
+    const error = new Error('AGGREGATE_WRITE_READBACK_REVISION_UNCHANGED');
+    error.code = 'AGGREGATE_WRITE_READBACK_REVISION_UNCHANGED';
+    throw error;
+  }
+  if (!isMissingRevision(responseRevision) && String(responseRevision) !== String(readbackRevision)) {
+    const error = new Error('AGGREGATE_WRITE_RESPONSE_READBACK_REVISION_MISMATCH');
+    error.code = 'AGGREGATE_WRITE_RESPONSE_READBACK_REVISION_MISMATCH';
+    error.details = {
+      revisionAxis,
+      responseRevision,
+      readbackRevision,
+    };
+    throw error;
+  }
+
+  const revisionSource = isMissingRevision(responseRevision) ? 'readback' : 'response';
+
+  return {
+    revisionAxis,
+    revisionSource,
+    verifiedRevision: readbackRevision,
+    beforeRevision,
+    responseRevision: isMissingRevision(responseRevision) ? null : responseRevision,
+    readbackRevision,
+  };
+}
+
 function summarizeDesignConfig(config) {
   const safeConfig = config || {};
   return {
@@ -388,9 +454,7 @@ async function loadDesignForMutation(authRef, appType, formUuid, input, action)
   const designInfo = normalizeDesignConfig(rawConfig, formUuid);
   const currentResult = await getVirtualViewConfig(authRef, appType, formUuid);
   const currentConfig = assertSuccess(currentResult, t('aggregate_table.inspect'));
-  const gmtModified = action === 'save'
-    ? currentConfig.stashGmtModified
-    : currentConfig.gmtModified;
+  const gmtModified = selectActionRevision(currentConfig, action);
   return { designInfo, currentConfig, gmtModified };
 }
 
@@ -447,6 +511,18 @@ async function runSaveOrPublish(args, action) {
 
   const authRef = await createAuthRef();
   const { designInfo, currentConfig, gmtModified } = await loadDesignForMutation(authRef, appType, formUuid, input, action);
+  if (flags.expectedRevision !== null && (
+    isMissingRevision(gmtModified) || String(gmtModified) !== String(flags.expectedRevision)
+  )) {
+    throw new CliError('AGGREGATE_WRITE_PRECONDITION_FAILED', {
+      code: 'AGGREGATE_WRITE_PRECONDITION_FAILED',
+      details: {
+        revisionAxis: getActionRevisionAxis(action),
+        expectedRevision: flags.expectedRevision,
+        observedRevision: isMissingRevision(gmtModified) ? null : gmtModified,
+      },
+    });
+  }
   assertAggregateDesignConfig(designInfo, { mode: isPublish ? 'publish' : 'draft' });
 
   const result = await postVirtualViewDesign(authRef, appType, formUuid, designInfo, action, gmtModified);
@@ -454,20 +530,7 @@ async function runSaveOrPublish(args, action) {
   const readbackResult = await getVirtualViewConfig(authRef, appType, formUuid);
   const readback = assertSuccess(readbackResult, t('aggregate_table.inspect'));
   assertAggregateDesignReadback(designInfo, readback);
-  const responseRevision = content && content.gmtModified;
-  const readbackRevision = readback && readback.gmtModified;
-  if ((responseRevision === undefined || responseRevision === null) &&
-      (readbackRevision === undefined || readbackRevision === null)) {
-    const error = new Error('AGGREGATE_WRITE_REVISION_MISSING');
-    error.code = 'AGGREGATE_WRITE_REVISION_MISSING';
-    throw error;
-  }
-  if ((responseRevision === undefined || responseRevision === null) &&
-      currentConfig && String(readbackRevision) === String(currentConfig.gmtModified)) {
-    const error = new Error('AGGREGATE_WRITE_REVISION_UNCHANGED');
-    error.code = 'AGGREGATE_WRITE_REVISION_UNCHANGED';
-    throw error;
-  }
+  const revisionProof = assertActionRevisionAdvanced(action, currentConfig, content, readback);
   const designUrl = buildDesignUrl(authRef.baseUrl, appType, formUuid);
   const workbenchUrl = buildWorkbenchUrl(authRef.baseUrl, appType, formUuid);
 
@@ -486,6 +549,12 @@ async function runSaveOrPublish(args, action) {
     aggregateTableId: formUuid,
     formUuid,
     gmtModified: content && content.gmtModified,
+    revisionAxis: revisionProof.revisionAxis,
+    revision: revisionProof.verifiedRevision,
+    revisionSource: revisionProof.revisionSource,
+    beforeRevision: revisionProof.beforeRevision,
+    responseRevision: revisionProof.responseRevision,
+    readbackRevision: revisionProof.readbackRevision,
     response: content,
     readbackVerified: true,
     designUrl,
@@ -561,6 +630,8 @@ async function run(args) {
 module.exports = {
   DESIGN_KEYS,
   FORM_TYPE_VIRTUAL_VIEW,
+  ACTION_REVISION_AXES,
+  assertActionRevisionAdvanced,
   buildCreateEmptyPostData,
   buildDesignPostData,
   filterAggregateTables,
@@ -568,6 +639,7 @@ module.exports = {
   normalizeDesignConfig,
   parseFlags,
   readJsonInput,
+  selectActionRevision,
   summarizeDesignConfig,
   run,
   __api__: {