@mobileaidev/ai-app-bridge 0.2.15 → 0.3.0-rc.2

package/docs/EVIDENCE_ARCHIVE.md

@@ -0,0 +1,214 @@
+# Record, export and verify execution evidence
+
+Discover the public MCP command with `capabilities {"command":"evidence"}`.
+It works for both Intent operation IDs and Script execution IDs, including
+records retained after the execution runtime has restarted. CLI and MCP use the
+same operation IDs and export command. Export does not require a
+connected phone or a live worker.
+
+```json
+{
+  "command": "evidence",
+  "arguments": {
+    "operation": "export",
+    "namespace": "intent",
+    "operationId": "intent-from-your-response",
+    "outputDir": "/absolute/existing-parent/new-archive"
+  }
+}
+```
+
+Use `namespace: "script"` for a Script operation. Export reads the current
+execution runtime's configured FactStore (`AI_APP_BRIDGE_FACT_STORE_DIR`), drains its
+queued writes, and freezes the retained records for exactly that namespace
+and operation. The parent directory must exist; the output directory must
+not exist. No existing directory is replaced.
+
+The response includes `archiveDir`, `manifestPath`, `manifestSha256`,
+`recordCount`, `targets`, and `coverage`. Save the returned manifest SHA256
+separately when handing the archive to an author or reviewer.
+
+Without `includeRecordedPayloads`, the directory contains two files:
+
+- `records.json`: the original ordered Facts, including their globalSeq,
+  outer source binding, full evidence envelopes, raw trees where stored,
+  checksums, and original device/app identities.
+- `manifest.json`: schema `aab.evidence-archive/v1`, namespace/operation,
+  source store ID and sequence watermark, partition retention metadata,
+  file size/SHA256, record counts, target inventory, and coverage.
+
+The sequence can have gaps because unrelated operations share the store.
+An expired cursor, unreadable page, checksum error, mismatched binding, or
+snapshot change fails export. An unknown operation returns
+`operation_not_found`. Limits are 10,000 records and 128 MiB of record JSON;
+the manifest is limited to 2 MiB. Exceeding a limit fails rather than
+truncating. The manifest is written last; a directory left by an interrupted
+write is not a successfully verified archive.
+
+## Verify without the source store or phone
+
+Move or copy the directory as a unit, then call:
+
+```json
+{
+  "command": "evidence",
+  "arguments": {
+    "operation": "verify",
+    "archiveDir": "/absolute/moved-archive",
+    "manifestSha256": "<the 64 lowercase hex characters saved from export>"
+  }
+}
+```
+
+Verification opens only the archive's ordinary files. It does not open a
+FactStore, initialize an operation, or contact a phone. It verifies the
+externally supplied manifest hash, records hash/size, each evidence checksum,
+namespace/operation/source binding, IDs, sequence, internal reference order
+and binding, and recalculated coverage and target inventory. Archive files cannot be symlinks, and the manifest
+cannot redirect the verifier to another file. A missing or changed file
+fails verification. Source paths embedded in evidence are data and are never
+opened or executed.
+
+Success returns `ok: true` and `integrity: "verified"`. The hash establishes
+that the supplied archive matches the frozen export; it is not a signature
+authenticating the producer. Obtain the expected hash from the export
+response, not by hashing an untrusted archive and treating that as approval.
+
+## What this archive establishes
+
+`coverage.scope` is `retained-host-records`. `priorHistoryComplete` remains
+`unknown`: a store can already have evicted older records before export.
+Partition retention metadata describes the entire partition, not proof that
+this particular operation lost records.
+
+`referenceClosure` is `complete` when the included records' checked internal
+references are present, or `partial` with `missingReferences`. This is
+separate from whole-history completeness. Exporting a partial retained set
+can succeed as a diagnostic archive; it does not fill its missing evidence.
+Contradictory references fail: a reference to a future record, a summary with
+a different observation revision, a receipt preceding its dispatch marker,
+or duplicate observation/decision/action identities cannot become a complete
+reference set merely because the IDs exist.
+
+The archive preserves already persisted, sanitized values byte-for-value as
+JSON values. It does not change recorded serials or infer missing targets
+from the currently connected phone. `owner` retains the declared context,
+`observed` retains each observation's declared device/App identity, and `foreground`
+retains explicit Intent route data. Script marker targets use `dispatch`
+and can contain explicit target overrides, including another serial when
+the Script supplies it. These roles preserve the current execution contract;
+the archive does not apply a new device allowlist or infer an absent target.
+
+New execution envelopes declare `schemaVersion: "aab.execution-evidence/v1"`.
+Their targets use an explicit platform discriminator; observations carry both
+`target` and `observedTarget` when the latter was actually observed. A pure
+Script call can have a null target. Archive verification also understands the
+original unversioned record format already frozen in archive v1/v2. It checks
+those original fields and hashes without adding a platform or rewriting bytes.
+New execution writes do not accept an old observation in place of a platform target.
+
+Currently persisted Intent content includes observations with raw trees,
+summaries, decisions, dispatch markers, and action receipts. Script content
+includes durable checkpoints, dispatch markers, and action receipts.
+Completed Scripts also persist their final JSON as a `result` record, with a
+terminal checkpoint `resultRef` binding its evidence ID, canonical byte count,
+persisted SHA256, original SHA256 and `original-json`/`redacted-json`
+representation. Export includes this retained record without requiring
+`includeRecordedPayloads`; it is independent of progress-event retention.
+Verification checks the checkpoint's binding to that result. An evicted result
+leaves partial reference closure rather than a reconstructed value. For a direct
+checked read, use `script {operation:"result",operationId:"…"}`.
+
+Without recorded payload inclusion, `externalPayloads` is `not-included`. External screenshot files, phone
+logs/network capture items, individual Script call results/assertions, and in-memory
+events are outside this archive. Existing external references are listed
+but not downloaded or dereferenced. Preserve those artifacts separately
+when the intended check requires them.
+
+`executionStatus` is `not-inferred` and `businessVerdict` is `not-evaluated`.
+The caller can inspect recorded terminal decisions/checkpoints, including a
+persisted cancellation. Export verification does not infer missing lifecycle
+state or reconstruct evicted records.
+Archive integrity alone does not establish a passed business assertion.
+
+## Explicit recording for one execution
+
+Add `recordingDir: "/absolute/existing-parent/new-recording"` to the
+**arguments of `script start` or `intent start`**, alongside `script` or
+`goal`/`target`. The parent must exist and the directory must be new.
+This is opt-in file output for this execution; ordinary live calls do not
+copy mobile payloads to a Host history database.
+
+Script records each returned Host call envelope (command, arguments, actual
+result, call/action/observation IDs, source hash, window, coverage, refs and
+capture metadata), plus each assertion input and Host verdict. The Host
+copies referenced screenshot PNG bytes immediately, checking the issued
+SHA256 before an original path can be reused. It awaits the attachment's
+FactStore receipt before replying to the child. This does not depend on the
+child writing files or on retaining the bounded event log.
+
+Intent records the complete capture pages already fetched by its `require`
+streams, including items. Each attachment references its persisted raw-tree
+observation. Recording itself does not query extra streams or take Intent
+screenshots. With no `require` streams, Intent has no mobile payload to record.
+
+The existing Host FactStore stores small `attachment` records containing
+file hashes and execution bindings; the payload files remain in the explicit
+output directory. The live mobile query path never consults those files.
+Script recording currently requires `restartPolicy: "none"`; a checkpoint
+restart request with recording is rejected as `recording_restart_unsupported`.
+Live pause/resume can continue the same recording. No recording is silently
+reopened after Host or child loss.
+
+Limits are 10,000 attachments, 16 MiB per JSON/PNG file and 256 MiB per
+recording. A write, checksum or persistence failure stops further successful
+recording: Script receives an explicit error and blocks further calls;
+Intent stops exposing the new observation. Previously committed material
+can still be exported. Unreferenced files left by a failed write are not
+included. Existing output directories are never replaced or cleaned up.
+
+JSON uses the existing FactStore credential redaction. `representation`
+distinguishes `original-json` from `redacted-json`. Original and archived
+data hashes are stored separately; a redacted payload is never presented as
+the original `source.payloadSha256` bytes. PNGs retain their original bytes.
+
+## Include recorded files in the portable archive
+
+Use the same public export call with `includeRecordedPayloads: true`:
+
+```json
+{
+  "command": "evidence",
+  "arguments": {
+    "operation": "export",
+    "namespace": "script",
+    "operationId": "script-from-your-response",
+    "outputDir": "/absolute/existing-parent/new-archive",
+    "includeRecordedPayloads": true
+  }
+}
+```
+
+This produces `aab.evidence-archive/v2`: records, manifest and flat
+`payload-<sha256>.json/png` files. All retained attachment references must
+resolve with the expected size/hash. Export never re-fetches mobile facts
+or substitutes another screenshot. Keep the recording directory in place
+until export; after export, move the archive as a unit and use the same
+`verify` operation and separately saved manifest hash. Offline verification
+never opens the old recording directory or screenshot paths.
+
+`recordedPayloads` reports included calls, Host assertion verdict counts,
+screenshots, mobile pages/items and checked item/ref associations. Item IDs,
+timestamps, stream, target and explicitly filtered epoch must agree. A
+connected-history page's current epoch is not substituted for an older
+fact's own epoch. Coverage, query window, pagination and store generation
+remain the values returned by the source. Uncommitted items remain visible
+without being counted as bound mobile facts.
+
+This remains an archive of **retained recorded payloads**, not proof of a
+complete run. Unqueried facts, calls made without recording, evicted
+attachment references, in-memory progress and late/in-flight calls outside
+the export watermark are not reconstructed. Assertion verdicts are retained
+Host judgments of the supplied condition/evidence, not an independent
+recalculation of business expectations. Integrity verification does not
+turn a failed or inconclusive assertion into a pass.

package/docs/INTENT_FOREGROUND.md

@@ -0,0 +1,71 @@
+# Android Intent foreground routing
+
+An Intent can keep its original business target while navigating through explicitly listed Android system apps. Supply `target.foregroundPackages` to enable this mode. Without that field, the existing explicit provider contract is unchanged.
+
+```json
+{
+  "command": "intent",
+  "arguments": {
+    "operation": "start",
+    "goal": "Export a backup, choose its file in the system picker, and return to the notes app",
+    "provider": "native",
+    "target": {
+      "serial": "DEVICE_SERIAL",
+      "packageName": "io.github.mobileaidev.notallyx.sample",
+      "foregroundPackages": ["com.coloros.filemanager"]
+    }
+  }
+}
+```
+
+Use packages actually resolved on the device for the requested flow. `foregroundPackages` is an explicit array of additional package names; an empty array restricts the operation to its original app. It does not discover or grant access to unrelated apps.
+
+Each observation checks the foreground component before and after acquiring a fresh tree. In the original app it uses the selected primary provider (`native`, `flutter`, or `uia`); in a listed external package it uses UIA. Provider failures remain errors, and never trigger a substitute tree. A UIA dump must identify the same foreground package.
+
+`uia_tree_changed` means the tree changed during traversal; that read supplies no
+complete tree. A caller may make another explicit read within its observation
+budget, retaining the failed read. It must obtain a complete current tree before
+choosing any action. The Host does not retry the read or substitute a provider.
+
+The summary contains `provider` and `foreground` (`packageName`, `activity`, `component`, probe source and timestamps). Observation, decision, dispatch marker and receipt records preserve that route. The original `target` continues to identify the business operation and its app capture streams. System UIA observations do not imply that system-app network/state/event capture is available.
+
+Actions inherit the provider of their committed observation. An explicit conflicting provider is rejected. Before dispatch, the adapter checks the foreground component again; a changed component returns `reobserve_required` without dispatching a tap. Exact UIA taps use the API 33+ phone node runtime. Its `uia-node` execution receipt binds the Intent action ID, original request hash, runtime epoch, node/window attributes and original callback. The selected node is revalidated on the same automation connection before dispatch. A callback still requires a fresh observation and business checks; it does not create system-app SDK events.
+
+Device-scoped physical taps remain managed Android shell input. Cancellation
+and recovery follow the selected executor's admission and completion contract.
+If a dispatched action's terminal receipt is unavailable, durable device
+ownership blocks later mutations until `device-ownership reconcile` verifies
+that original receipt.
+Intent records retain both the original unknown result and any separate recovery
+history. A completed tap still requires a fresh observation and business checks.
+
+For exact UIA taps, use one of these selectors:
+
+```json
+{ "action": "tap", "selector": { "text": "NotallyX Backup 2026-09-07 \n15-44.zip" } }
+{ "action": "tap", "selector": { "resourceName": "com.coloros.filemanager:id/action_file_operate" } }
+{ "action": "tap", "selector": { "contentDescription": "返回" } }
+```
+
+The selector must identify exactly one enabled node in the observed package. Duplicate matches, unsupported selector fields and unavailable bounds fail before input. UIA lookup, compact trees and Intent summaries share the same XML attribute decoder, including decimal/hexadecimal character references. Decoding happens once: `
` stays literal `
`, while `
` becomes a newline. Invalid XML character references fail explicitly.
+
+If the foreground changes during observation, the operation enters `waiting_for_observation`. Call `operation: "observe"` with the same `operationId`; the operation returns to `waiting_for_decision` only after a new observation commits. Acting or completing from `waiting_for_observation` is rejected. Existing evidence-store failures retain their separate blocked state.
+
+Flutter taps accept one exact selector: `{ "text": "Settings" }` or
+`{ "nodeId": "15" }`. Put the identity inside `action.selector`.
+Text must identify one actionable node. Repeated
+labels such as three settings rows displaying "System" return
+`flutter_selector_not_unique` without dispatch. Select the intended row's
+`nodeId` from the current committed observation instead. IDs are local to that
+observation; a new tree requires a new lookup. A node must supply valid
+`tap.bounds`; the Host does not invent tap bounds for text-only nodes. Flutter
+coordinates remain logical pixels. Material `NavigationDestination` nodes
+expose their public labels and individual destination bounds.
+
+The operable tree traverses live Elements, including framework-owned pages
+such as `LicensePage`. It is separate from the diagnostic inspector summary.
+Repeated text for the same action region is emitted once; distinct settings
+rows keep distinct targets. Each emitted label needs its own visible bounds.
+The traversal reports truncation when its 512-level depth limit is reached.
+
+This brackets foreground identity; it is not an atomic OS screenshot/action transaction. Animations and layout changes within the same Activity still require fresh stable observations and post-action verification. This change does not add arbitrary UIA Unicode input or attachment/backup business assertions.

package/docs/INTENT_NATIVE_EDITING.md

@@ -0,0 +1,79 @@
+# Native editing through Intent
+
+Use a current supervised Intent observation. To acquire a newer screen without dispatching an action, call:
+
+```json
+{"operation":"observe","operationId":"your-intent","basedOnRevision":1}
+```
+
+Use the canonical `observe` operation. It reads the provider and persists the observation and summary before exposing revision + 1 while waiting for a decision or observation. Old decisions then require the new revision. It does not sleep, tap, or restart a terminal execution.
+
+Submit an editing decision using the returned revision:
+
+```json
+{"operation":"decide","operationId":"your-intent","decision":{"decisionId":"edit-title-1","agentDecision":"act","basedOnRevision":2,"action":{"action":"inputText","selector":{"resourceName":"io.github.mobileaidev.notallyx.sample:id/EnterTitle"},"value":"Example title"}}}
+```
+
+`tap` uses the same selector shape. Select one identity through `resourceName`, exact `text`, or `contentDescription`; an optional `within` scopes the native match. Native selection requires exactly one enabled, effectively visible node in the topmost observed window and a center inside its viewport. Input additionally requires SDK `editable: true`. Missing or false `editable` always rejects; class-name guesses are not supported. Duplicate, invisible, obscured and noneditable targets fail without dispatch. Before dispatch, the adapter reads the current tree again and checks the window and semantic identity. A replaced, ambiguous or ineligible target rejects without input. Native `scroll` requires the selected container and `direction:"down"` or `"up"`. Flutter scrolling uses the separate `scrollBy` action.
+
+Native summaries preserve `resourceName`, `editable`, `visible`, and `effectiveVisible` when supplied by the SDK, including blank input fields. Missing metadata remains unknown. The top-level `activity` is copied from the current raw tree. Summary visibility does not establish that a node belongs to the foreground window; the adapter separately enforces the topmost observed window. Each summary node retains its `rawTreeId` and `sourceIndex` for evidence lookup.
+
+An exact native accessibility name can use `selector: {"contentDescription":"置于顶部"}`. It is a separate selector from `text`; no substring match or text/description fallback occurs. A native summary `label` derived from the raw `contentDescription` corresponds to this explicit selector. The same unique visible foreground target rules apply.
+
+Native tap and input pass the selector, SDK `targetRef` and Host action ID to the dedicated `/v1/action/tap-target` and `/v1/action/input-target` endpoints. They do not send coordinates. The SDK validates the runtime, original operable window, View instance, observed semantic ancestry, uniqueness and eligibility on the UI thread immediately before the action. Geometry changes on the same View use its current position. Input binds to that exact editor and rechecks after synchronous focus/connection callbacks; a rejection after requesting focus reports that dispatch already began. It never inserts text into a replacement editor.
+
+Script and direct CLI/MCP callers can use the same editor binding through
+`input-text` with `{selector, text}`. Empty text clears the editor. The command
+reobserves and revalidates the selector; an Intent decision additionally names
+the Agent-reviewed revision. Neither entry substitutes coordinates when the
+SDK target reference is unavailable.
+
+Window snapshots distinguish `focused`, `focusable`, `touchable` and nullable `focusOwnerWindowId`. A touchable, non-focusable popup accepts pointer actions only while a window with the same application window token retains focus. The top visible window still owns selection: an overlay never grants access to a background target. Missing metadata, a non-touchable window, or loss of the owning focus rejects explicitly. Native text input still requires the selected window itself to have focus. Tap and gesture events preserve screen-space `rawX/rawY` as well as window-local `x/y`, including cancellation events.
+
+These actions require `targetRef.schemaVersion:"aab.native-target/v1"`. Missing metadata or an unsupported endpoint returns `native_atomic_target_unavailable` without a coordinate/ADB fallback. SDK tasks still queued when their UI wait times out cannot execute later; already-started mutations can have an ambiguous timeout outcome. Native gestures use this reference contract too, with the timed stream described below. Flutter and system UIA do not yet have this SDK execution binding. Host receipts and SDK target validation still require runtime evidence and independent business-state verification.
+
+Unsupported actions/providers fail closed. UIA and Flutter inputText are outside this addition. Unknown actions never become taps. Intent execution completion is separate from business acceptance.
+
+Native `longPress` requires an exact `selector` and integer `durationMs:500..10000`.
+Native `swipe` requires an exact `selector`, numeric `deltaX`/`deltaY`, and integer
+`durationMs:1..10000`. The SDK computes the start from the selected node's current
+center; the endpoint adds those deltas and must remain inside the current window.
+A downward finger gesture has positive `deltaY`.
+
+Native `scroll` uses an explicit container, for example
+`{action:"scroll", selector:{resourceName:"example.app:id/list"}, direction:"down"}`.
+It swipes within that container's visible area (`durationMs` defaults to 400).
+If it cannot scroll in that direction, `native_scroll_boundary` rejects before
+touch. UIA `scroll` remains a separate viewport action with an explicit provider.
+
+The SDK binds the window/View before DOWN and runs real-time touch events through
+the UI handler. Window/focus loss or cancellation sends CANCEL to the original
+window. It does not undo a long-click callback or other App effects. Host waits
+for a bounded cancellation acknowledgement after response loss; missing or
+invalid confirmation remains ambiguous and never triggers a gesture replay.
+Started/terminal phone `ui.interaction` events retain the action ID. Arbitrary
+delayed callbacks are not all causally tagged. Reobserve and verify actual App
+state; a completed touch stream alone does not establish business acceptance.
+
+The same implementation is available to Script and direct commands as
+`native-gesture`, with the action object under `payload`. Script uses
+`ctx.call('native-gesture', {payload:{action:'longPress', selector:{text:'Observed note'}, durationMs:700}})`;
+the Script target supplies serial/packageName, and Host owns action identity.
+See [the command contract](COMMAND_CONTRACT.md) for cancellation and receipt fields.
+
+`action: "back"` sends Android Back. `action: "keyevent", keyCode: 4` expresses
+that key explicitly. Observe the keyboard/page state before deciding what Back
+should accomplish; dismissing a keyboard and leaving a page are different outcomes.
+
+Preserve per-step Intent responses and action receipts. Native observations
+currently do not take a screenshot automatically: `summary.screenshotId` can
+be null. A separate `screenshot` call should retain its artifact hash, timestamp
+and the adjacent observation ID. This association is sequential, not an atomic
+tree/screenshot capture. `status.history` is a bounded execution ledger and
+does not expose the full stored raw tree for each observation.
+
+Use [the public evidence export](EVIDENCE_ARCHIVE.md) with this Intent's
+operationId to freeze retained raw observations, summaries, decisions and
+receipts. A returned manifest hash supports verification after moving the
+archive or restarting MCP. External screenshot files and phone capture bodies
+remain separate; the export reports this coverage explicitly.

package/docs/RELEASE.md

@@ -0,0 +1,59 @@
+# 0.3.0-rc.2 发行与接入交接
+
+本文件记录候选版的依赖关系和出仓库交付入口。封版要求是同一提交的源码、发行包与公开接入合同一致；单个样本的测试进度不改变包版本或发布状态。推送 Git、创建远端标签及发布 npm/pub 包由维护者执行。
+
+## 版本与消费方式
+
+| 交付物 | 候选版本 | 独立消费入口 | 发布依赖 |
+| --- | --- | --- | --- |
+| Android SDK | `0.3.0-rc.2` | JitPack `com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-android:0.3.0-rc.2` | 同名 Git tag，JitPack 对该提交成功构建 |
+| Android Gradle 插件 | `0.3.0-rc.2` | JitPack `ai-app-bridge-gradle-plugin` 模块及插件 ID `io.github.mobileaidev.aiappbridge.android` | 与 SDK 相同的 Git tag；不再使用旧默认 `0.2.8` |
+| 原生 iOS SDK | Git tag `0.3.0-rc.2` | Git URL 的仓库根 `Package.swift`，产品 `AiAppBridgeIOS` | 根清单包含 Swift runtime、C adapter 和 segmented C store，无外部 C 包路径 |
+| Flutter 插件 | `0.3.0-rc.2` | pub `ai_app_bridge_flutter` | Android 固定依赖上述 SDK；iOS Swift/C 源码随插件分发 |
+| Desktop CLI/MCP | `0.3.0-rc.2` | npm `@mobileaidev/ai-app-bridge` | 包含 UIA bundle、WDA 模板和 native store 源码；WDA 上游固定 `14.1.1` |
+| Web SDK | `0.3.0-rc.2` | npm `@mobileaidev/ai-app-bridge-web` | 独立浏览器源码包，无 npm 对 CLI 的安装依赖 |
+| Native store | `0.1.0` | 随 CLI 的 bundled dependency 安装 | 不要求另行发布到 npm；`file:../../native/segmented-fact-store` 是工作区构建入口，最终 tarball 必须包含该依赖源码 |
+
+Flutter 的 podspec 是随 pub 插件消费的本地 podspec，不是独立 CocoaPods trunk 发布包；原生 iOS 使用根 Swift package。Flutter SwiftPM 的 `../FlutterFramework` 由 Flutter 的集成生成，不能当作本仓库的外部私有依赖，也不应将本机 Flutter framework 打包进插件。
+
+Host 支持范围声明为 Node `>=26.3.0 <27`，本轮实际验证基线是 **26.3.0**。共享 runtime 与查询索引依赖 `node:sqlite`，native store 安装需要 node-gyp 所需的 Python 和 C/C++ 编译工具。未对其他 Node 版本或跨主版本兼容作实测声明。Python Script 另需可用的 `python3`，从实际 `script runtime-status` 读取环境能力。
+
+## 发布顺序
+
+1. 完成源码审阅并冻结一个提交，核对以下命令的产物确实来自它；包含当前 untracked 的实际源码、测试和文档，排除本机生成目录。所有候选对外版本使用同一个 `0.3.0-rc.2`，若需要改版本，先同时更新上表涉及的 manifest 与固定依赖。
+2. 维护者推送提交与 `0.3.0-rc.2` 标签，让 JitPack 构建 Android SDK/插件。确认两条公开坐标可解析后，再发布依赖它们的 Flutter 包。本地 Gradle project/path/AAR 替换不能证明 JitPack 坐标可消费。
+3. 原生 iOS 消费相同 Git tag 的根 package；完成根 package 的 iOS 构建，不仅构建 `ios/ai-app-bridge-ios/Package.swift`。Flutter iOS 则检查实际 pub 包内 Swift/C 源码与声明相符。
+4. CLI 与 Web SDK 可分别发布到 npm 的候选 dist-tag。CLI 的 native store 已打包随行，不等待一个不存在的单独 registry 依赖。Flutter 包发布以第 2 步完成为前提。
+5. 从 registry/tag 安装刚发布的确切版本，读取 `capabilities` 和版本，核对来源及支持范围，再按发布策略提升正式 dist-tag。候选发布不自动等于全平台生产验收完成。
+
+候选发布命令需在对应目录由维护者执行，例如 npm 使用 `npm publish --tag next`；pub 使用 `flutter pub publish`。这些命令属于发布动作，不能混入本地验证脚本。
+
+## 本地检查与最终包验证
+
+以下检查不发布版本。路径相对仓库根；输出使用新的、Git 忽略的目录。
+
+```sh
+swift package --package-path . dump-package
+swift package --package-path ios/ai-app-bridge-ios dump-package
+
+cd desktop/ai-app-bridge-cli
+npm pack --dry-run --json --ignore-scripts
+
+cd ../../web/ai-app-bridge-web
+npm pack --dry-run --json --ignore-scripts
+
+cd ../../flutter/ai_app_bridge_flutter
+flutter pub publish --dry-run
+```
+
+`dump-package` 只证明 manifest 可解析及目标声明，不能替代 iOS 编译；`npm pack --dry-run` 只证明拟打包文件清单，不能替代安装；pub dry-run 中的分析/网络检查结果应原样记录。干净安装与 Host 协议验证必须在核心源码冻结、没有运行中修改时执行：
+
+```sh
+cd desktop/ai-app-bridge-cli
+npm ci
+npm run verify:package -- ../../build/ai_app_bridge_artifacts/release-package-NEW
+```
+
+`verify:package` 在仓库外安装实际 tarball，检查 native 安装编译、CLI/MCP 共享运行时、控制接口与随包运行时身份。它使用受控 ADB，不声称完成新真机业务验收。报告、tgz 哈希、安装日志和源码提交身份一起交接；已运行的旧包验证不能代替后来修改过的包。
+
+CLI 的 `files` 已排除旧 `fact-cache.js` 发布载荷及 fake/P9/旧设备 adapter；旧 fact-cache 实现仅保留为 `test-support` 测试夹具，无生产引用。各 npm 包和 Flutter 目录的 `LICENSE`/`NOTICE` 均来自仓库根原文，发行时核对内容一致，不生成替代版权说明。