# App 动作协议模型 / App-action protocol model

这是研究设计的可执行例子，只在内存中使用合成账户、实体、确认句柄和回执。没有网络调用、真实账户、凭据、移动 SDK、设备安装或权限修改。它不是原生桥，也不是可直接上线的后端。测试通过不等于 Siri、Shortcuts、Gemini 或 AppFunctions 已接入。

This is an executable research-design example using synthetic accounts, entities, confirmation handles and receipts in memory. It performs no network calls, credential handling, mobile SDK calls, installation or permission changes. It is neither a native bridge nor a deployable backend. Passing tests do not establish Siri, Shortcuts, Gemini or AppFunctions integration.

源码文件 / Source files: [model](protocol-model.mjs), [tests](protocol-model.test.mjs), [negative controls](mutation-check.mjs).

## 复现 / Reproduce

从仓库根目录执行 / From the repository root:

```sh
node --test research_domains/apple_google_app_actions/protocol_tests/protocol-model.test.mjs
node research_domains/apple_google_app_actions/protocol_tests/mutation-check.mjs
```

只依赖 Node.js 内置模块。本阶段运行环境为 Node.js v24.19.0；其他版本需自行验证兼容性。所有输入都是代码内明确标为 synthetic 的假数据。测试不读取环境变量、用户文件或外部服务。

Only Node.js built-ins are used. This stage was run with Node.js v24.19.0; compatibility with other versions is not asserted. Inputs are explicitly synthetic fixtures in source. Tests do not read environment variables, user files or external services.

## 验证的合同 / Contracts exercised

- M01–M03：固定动作、版本和 schema；拒绝未知字段及不合法参数。M04：展示的是规范化后的最终参数。
- M05–M11：拒绝、参数/目标变更、目标版本漂移、过期、账户切换、权限撤回均阻止新的副作用。
- M12–M14：幂等键绑定主体、组织、动作和请求；同一规范化输入回放原回执，不同输入冲突，新请求需新确认。
- M15–M20：提交前取消无副作用；提交后取消或响应丢失先保留 unknown，再查询真实回执；查不到或不可达不能证明未执行。

- M01–M03 pin action/version/schema and reject unknown fields or invalid parameters. M04 displays normalized effective parameters.
- M05–M11 reject declined, changed, stale or expired confirmation and deny changed/revoked account access before a new effect.
- M12–M14 scope idempotency to principal, organization, action and request; normalized replays return the original receipt, changed inputs conflict, and a new request needs new confirmation.
- M15–M20 distinguish cancellation before and after commit, preserve unknown after a lost response, and recover receipts without blindly creating a new request. Missing or unreachable receipts do not establish that no effect occurred.

三个负对照依次故意移除版本围栏、确认绑定和正确的提交后取消状态。相同测试必须产生断言失败；语法错误、崩溃或超时不算检出。临时副本只在系统临时目录创建并删除，不改仓库源文件。

Three negative controls deliberately disable the version fence, confirmation binding and correct post-commit cancellation status. The same tests must fail assertions; syntax errors, crashes or timeouts do not count as detection. Mutants are created and removed only in a temporary directory, without editing repository sources.

## 本阶段的新结论 / Design implications

1. 确认应绑定规范化后的参数、目标版本、主体和请求ID；单独一个 approved=true 不能表达这些约束。
2. 取消是观察到的客户端状态与后端副作用状态的组合。停止等待后，已提交动作仍须显示 committed；不能统一转换成 cancelled。
3. receipt not_found 只说明本次查询没找到，不能证明未执行。回执不可达或缺失时继续显示 outcome_unknown，并保留原请求身份。

1. Confirmation must bind normalized parameters, target version, principal and request ID; a generic approved=true flag cannot express those constraints.
2. Client cancellation and backend effect state are separate. A committed action remains committed after the caller stops waiting.
3. A missing receipt proves only that the query did not find one. Preserve outcome_unknown and the original request identity when receipt evidence is unavailable.

## 不能由此推出 / What this does not prove

- 这20项是模型断言，不是R2的12项设备验收。原生设备通过数仍为0/12。
- 内存 Set 模拟已认证会话；确认句柄不是签名令牌；schemaDigest 是固定示例标签，不是生产 schema 哈希算法。
- 同步临界区只枚举提交前后顺序，不模拟真实线程竞争、数据库原子性、崩溃持久化、网络传输、安全时钟或真实授权。
- 不能据此宣称 exactly-once、跨设备一致性、操作可撤回、平台准入或SDK兼容。
- 下一步是将这些输入/期望输出作为真实 bridge 的合同测试向量，再独立测试持久事务、重启恢复、SDK声明和设备行为。

- These 20 model assertions do not replace the 12 R2 device acceptance cases. Native/device passes remain 0/12.
- An in-memory Set stands in for an authenticated session; confirmation handles are not signed tokens; schemaDigest is a fixture label, not a production schema-hashing algorithm.
- A synchronous critical section enumerates before/after-commit orderings. It does not simulate real concurrent workers, database atomicity, crash durability, networking, trusted clocks or real authorization.
- No exactly-once, cross-device consistency, undo, platform eligibility or SDK compatibility claim follows from this model.
- Next, reuse the inputs and expected outputs as contract-test vectors for a real bridge, then separately validate durable transactions, restart recovery, SDK declarations and device behavior.

返回专题 / Back to topic: [Apple × Google App actions](../workbench.html)