From 5a13922cba118fa3d0f0c005e6b25db85643e0dc Mon Sep 17 00:00:00 2001 From: Callum Flack Date: Fri, 9 Oct 2026 09:42:30 +1000 Subject: [PATCH 1/2] docs: add CLI and Unity surface research and product glossary --- GLOSSARY.md | 43 +++ ...cli-unity-surfaces-discrepancy-research.md | 258 ++++++++++++++++++ 2 files changed, 301 insertions(+) create mode 100644 GLOSSARY.md create mode 100644 research/261009-cli-unity-surfaces-discrepancy-research.md diff --git a/GLOSSARY.md b/GLOSSARY.md new file mode 100644 index 0000000..b0a7816 --- /dev/null +++ b/GLOSSARY.md @@ -0,0 +1,43 @@ +# Vana product glossary + +The language used to distinguish a person's own data from an app's permission +to use that data. + +## Language + +**Vana account**: +The identity under which a person owns their data in Vana. + +**Owner**: +The person whose data is held under their Vana account. + +**Account data**: +The owner's data collected under their Vana account, regardless of whether +Desktop, Web or CLI collected it. +_Avoid_: Desktop data, CLI data when referring to ownership + +**App identity**: +The identity of an app or agent requesting permission to use an owner's data. +It is distinct from the owner's account, even when the same person controls both. + +**Grant**: +An owner's approval for a particular app identity to access specified data. + +**Personal Server**: +The service that holds an owner's data and makes it available through +authorized access. +_Avoid_: Desktop when referring to the server + +**Vana Storage**: +Vana's cloud storage service for synced account data. + +**Local export**: +A copy of collected data saved on a person's machine. +It is distinct from the full set of their account data. + +**Owner access**: +An owner's access to their own account data using their account identity. + +**App access**: +An app or agent's access to an owner's data under a grant to its app identity. +The owner and app remain distinct roles even when one person controls both. diff --git a/research/261009-cli-unity-surfaces-discrepancy-research.md b/research/261009-cli-unity-surfaces-discrepancy-research.md new file mode 100644 index 0000000..6fb5a7b --- /dev/null +++ b/research/261009-cli-unity-surfaces-discrepancy-research.md @@ -0,0 +1,258 @@ +# CLI and all Unity surfaces: duplication and contract discrepancies + +Date: 2026-10-09, Australia/Brisbane. Status: dated source baseline, not an accepted migration plan. + +Owner: this cross-repository research note in `vana-cli/research`. Revisit after changes to the producer/consumer contracts identified below; the owning source and current tests take precedence over this baseline. Existing Unity doctrine and upstream consolidation candidates remain at their current owners. + +## Finding + +The CLI and Unity are not two frontends over one complete implementation. They are several partly connected Vana journeys: owner collection, owner storage, builder consent and consumption, Account identity/signing, and product-specific access. There is real duplication of collection and protocol policy, legitimate host adaptation, and missing integration. Calling every personal-data function a duplicate loses those distinctions. + +The highest-priority discrepancies are at usable journey boundaries: a published handoff produces inputs the current Account route rejects; a newer Personal Server produces an approval link the current Web does not implement; derived questions are unavailable on Web's enclave delivery lane; and collection completion has different meanings across hosts. Extracting a common collector alone would leave these problems intact. + +## Scope and proof + +Inspected current sources, callers, package declarations, selected tests, app instructions and owner contracts in: + +- CLI: `/Users/callumflack/Repos/vana-com/vana-cli`, HEAD `f99bec8b235c2c5fdb2bd11875051fb0632f7bfb`. +- Unity: `/Users/callumflack/Repos/vana-com/unity-surfaces`, HEAD `da0c48be65a45468575b6142783c93ea65521985`, with existing unrelated Desktop document/UI changes. This is a working-source comparison, not a clean-commit audit. + +Coverage includes every directory in Unity `apps/`: eight packaged apps plus static `open-app`, and the shared packages that own relevant contracts. Read-only research used global/project research skills and the existing data-connection verification/source-capability guidance. No app was driven; no provider collection, login, grant, signing, payment, remote mutation, or runtime test was performed. Tests cited below were inspected, not run. + +CLI `node_modules` and the expected local SDK source checkout were unavailable. Unity's installed SDK 4.1.0 could be inspected; the CLI's declared SDK 4.3.1 internals could not. Findings requiring that SDK's outgoing request behavior are explicitly conditional. A source mismatch is not proof that the deployed revisions currently fail. + +## Every surface and its relationship to the CLI + +| Surface | Actual responsibility | Relationship to CLI | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| **Account** | OAuth/OIDC issuer, owner identity, signing/trust policy, developer app attribution and funding, access review. Its separate data-access-request API is still mock/fixture infrastructure. | CLI already calls this authority for login and local-server setup. Account is not another connector executor. | +| **Web** | Public/light Data Pipe collection; owner storage/read adapters; Direct data-connection-request approval, scope readiness and Desktop/Mobile continuation; remote MCP setup/approval. | CLI builder requests depend on the approval/handoff system. Web has a different acquisition and storage path from local CLI collection. | +| **Desktop** | Native local collection host, legacy Playwright and PDPP execution, native dialogs, Personal Server sidecar, ingest and recovery. | Substantial overlapping collection responsibilities; Node/Rust and terminal/native adapters differ. | +| **Mobile** | Hosted Next UI, connector manifests/scripts, source workflow, scope/time policy, export projection and owner-data signing/writes. | Overlapping product and data policy, but it does not run the phone's provider WebView itself. | +| **Mobile shell** | Flutter/native auth, provider WebViews, PageShim transport, owner-isolated storage, snapshots/checkpoints and OS/DCR handoff. Active code still supports PS Lite and enclave rollout lanes. | A third native collection host, with necessary phone-specific execution and isolation. | +| **Community** | First-party Account client for tasks, XP, auctions and deliveries; owner-written `vana.profile`, a Foundation grant and task verification. | Another real personal-data producer/consumer, but not a browser connector copy. Its shipping payments are distinct from CLI read escrow. | +| **Metrics** | Reads aggregate Account/Web database and Amplitude analytics and exposes aggregate account counts. | Observer of journeys, not a collector. Analytics vocabulary is another compatibility surface. | +| **UI** | Deterministic component workbench, including inert Account presentation specimens. | No live collection, wallet or authority implementation. | +| **Open app** | Static `/continue` ticket handoff and `/connect/:sourceId` app-link, QR and installation fallback. | Missing from a package-only inventory. It connects Web to Mobile; it is not a collector or consent authority. | + +Evidence: [Account policy](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/account/src/lib/signing/client-intent-policy.ts#L29), [Web source runner](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/web/src/features/sources/source-runner.ts#L23), [Desktop executor](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/desktop/src/lib/data-refresh/connector-request-executor.ts#L321), [Mobile driver](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/mobile/src/workflows/connect-flow/drivers/runtime-connect-flow-driver.ts#L322), [shell composition](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/mobile-shell/lib/ui/shell_page.dart#L227), [Community profile write](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/community/src/features/profile/owner-write.ts#L191), [Metrics queries](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/metrics/src/lib/db.ts#L24), [UI fixture boundary](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/ui/README.md#L13), [Open app handoff](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/open-app/index.html#L230) and [source-link fallback](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/open-app/connect.html#L193). + +```text +Identity and constrained owner signing: Account + clients: CLI / Desktop / Web / Mobile shell / Community + +Data acquisition: + CLI → local Node connector host + Desktop → native Rust + Node connector hosts + Mobile UI → Mobile shell's WebView/PageShim host + Web → hosted Data Pipe for public/light sources + Community → owner-entered profile answers + +Owner storage: + CLI/Desktop → native Personal Server ingest + Web/Mobile → rollout-selected PS Lite or registry/storage/enclave path + Community → shared owner-data storage path + +Builder request and consumption: + CLI app → Direct request / Web approval and continuation → grant → read + CLI SDK → older Session Relay / Account connect route (contract gap) + Account DAR → separate mock/fixture exchange (not a real protocol grant) + +Open app links Web ↔ Mobile. Metrics observes. UI demonstrates presentation. +``` + +## Concrete journey discrepancies + +### 1. Published CLI legacy handoff versus current Account `/connect` + +**Direct source mismatch.** CLI's public `vana-cli/server` `connect()` creates a Session Relay session and builds Account `/connect?sessionId=…&secret=…`, without `client_id`. The public React hook also falls back to a session-id URL. Current Account parses an OAuth-style handoff and requires `client_id`; its page shows an invalid state when parsing fails and requires a registered OAuth client. + +Sources: [CLI producer](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/server/connect.ts#L30), [public hook](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/react/useVanaConnect.ts#L84), [Account required fields/parser](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/account/src/app/connect/_lib/handoff-contract.ts#L29), [Account consumer](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/account/src/app/connect/page.tsx#L70). + +Implication: the package's published legacy consent path is source-incompatible with this Account checkout. This does not invalidate the newer `vana app request` Direct path. Owner/next action: CLI public API and Account handoff owners establish actual published consumers and deployed revisions, then deliberately preserve compatibility or migrate callers; these are external exports, not automatically disposable internal code. + +### 2. Personal Server scope-request links have no matching Web surface + +**Producer/consumer gap in current source.** CLI constructs `/mcp/requests/?ps_origin=…` for a remote agent's request for more scopes. Searches of Web/Account routes and Web/shared owner-data source found no matching request route or scope-request approve/deny wiring. Existing `/mcp` pages implement other authorization/setup flows. + +Sources: [CLI URL construction](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/cli/mcp-requests.ts#L67), [existing Web MCP route logic](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/web/src/app/%28app-shell%29/%28with-nav%29/%28main%29/mcp/mcp-approval-route.ts#L1). Search boundary: `apps/web/src/app`, `apps/account/src/app`, `apps/web/src`, `packages/owner-data-client`; patterns `mcp/requests`, `scope-request/approve`, `scope-request/deny`, `request_scope_access`. + +The CLI sidecar is PS 1.32.0; Web/shared PS code is 1.29.2, and CLI's comment dates scope-request answer endpoints to 1.30.0. That supports a version-skew explanation; it does not independently prove a deployed 404. Terminal approval exists. Owner/next action: Web MCP and CLI remedy owners align the route/capability contract and prove a request from the actual server version through owner decision. + +### 3. Derived questions and paid reads depend on the data plane + +**Explicit capability asymmetry.** `vana app ask` offers question approval followed by answer read. Web accepts questions in Direct requests, but approval preparation returns `enclave_questions_unsupported` whenever enclave delivery is selected. Owner-data Web session derivative methods also explicitly require Desktop. Separately, CLI's enclave read uses `maxPrice: 0` and refuses charged enclave reads even when `--pay` is supplied; the paid native-server read path supports escrow, fee caps and receipt replay. + +Sources: [CLI ask](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/cli/app/ask.ts#L109), [Web question restriction](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/web/src/app/%28app-shell%29/%28with-nav%29/%28main%29/data-connection-requests/%5Bid%5D/use-data-connection-request-flow.ts#L741), [Web session capabilities](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/web/src/features/personal-server/web-personal-server-session.ts#L578), [CLI enclave price restriction](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/cli/app/read.ts#L470). + +Implication: approval, compute and paid read are not uniformly available merely because a user has a Personal Server or an Account login. Owner/next action: SDK/CLI, Web approval and Personal Server owners expose and check delivery capabilities before promising the full journey. + +### 4. Grant preservation and DCR completion have unproved joins + +**Conditional integration risks, not exercised failures.** CLI merges a live grant when it can identify the owner. Its comments also rely on the approval page re-reading that owner's live grant and respecting `removeScopes` when local inference is unavailable or wrong. Current Web Direct parsing has no `removeScopes` field, and grant registration signs `dcr.scopes` as supplied; no approving-owner union was found. If SDK 4.3.1 still targets this route, the fallback promise is unsupported. + +CLI treats approved/read-ready status as successful request completion, which is valid for obtaining a grant. Web also needs consumer acknowledgment to finish the entire DCR journey. CLI source has no explicit `acknowledgeRead`/consumer-ack call in its later read path. Web Lite can report fulfilled reads itself, but a corresponding native/enclave link was not established here. Successful CLI command completion must not be presented as proof of Web's completed delivery record. + +Sources: [CLI owner/union plan](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/cli/app/request.ts#L84), [CLI removal payload](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/cli/app/request.ts#L494), [Web Direct parser](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/web/src/app/api/data-connection-requests/route.ts#L369), [Web grant registration](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/web/src/app/%28app-shell%29/%28with-nav%29/%28main%29/data-connection-requests/%5Bid%5D/use-data-connection-request-flow.ts#L1565), [DCR completion store](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/web/src/lib/data-connection-requests/store.ts#L312), [Lite reporter](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/web/src/features/personal-server/web-ps-lite-runtime.ts#L121). + +Owner/next action: SDK Direct/Web DCR owners inspect the exact 4.3.1 payload and fulfillment behavior, then check existing-grant extension/removal and a read through both delivery lanes. External SDK/server behavior remains a proof gap here. + +### 5. Bare app registration and Account claim disagree on metadata + +**Conditional source mismatch.** CLI `app register` signs `appUrl: ""` when no URL is provided and later treats already-registered as success. Account claim fetches the gateway builder and requires a usable HTTP(S) app URL plus public key. If the gateway accepts the blank registration, the advertised subsequent claim/funding journey cannot finish. CLI claim checks registration existence rather than record completeness. + +Sources: [CLI registration defaults](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/cli/app/register.ts#L125), [CLI claim check](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/cli/app/claim.ts#L157), [Account claim requirements](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/account/src/app/api/developers/claim-builder/route.ts#L162), [URL validation](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/account/src/lib/developers/builder-registration.ts#L183). + +Owner/next action: CLI registration and Account developer owners agree the minimum gateway metadata and repair/update path, then verify register → claim → fund. Gateway acceptance was not tested. + +### 6. Account Access is not a complete inventory of CLI grants + +**Distinct access models.** CLI reads real Gateway grants. Account App access reads `account_action_requests` with OAuth attribution, not the DP RPC grant inventory. Its optional legacy-gateway revoke path exists, but that does not establish visibility or revocation of CLI-created grants. Account's separate DAR exchange always fabricates a `vana_grant_` result and mock server URL; the pending browser approval is fixture-gated. Those results are not protocol grants. + +Sources: [CLI grant lookup](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/cli/app/read.ts#L156), [Account inventory](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/account/src/lib/account-access/repo.ts#L160), [optional revoke](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/account/src/lib/account-access/onchain-revoke.ts#L99), [DAR mock creation](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/account/src/lib/data-access-requests/runtime.ts#L170), [mock exchange](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/account/src/lib/data-access-requests/runtime.ts#L315), [fixture browser gate](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/account/src/app/data-access-requests/%5Bid%5D/page.tsx#L63). + +Implication: OAuth client, builder key/address, Account attribution, Web DCR, Account POC result and enforceable grant must remain distinct. Owner/next action: Account access and protocol owners define the authoritative inventory and ID mapping before claiming cross-surface revoke coverage. Account issuer, trust and signing authority already exists and is deliberately shared; it should not be moved into CLI. + +## Collection policy: real duplication and meaningful divergence + +### 7. The same PDPP skip result can mean different completion + +**Substantive duplicated-policy divergence.** CLI excludes skipped streams from record/checkpoint merges and exported completed scopes. An all-skipped successful connector run becomes a runtime error and leaves the prior result/state intact. Desktop uses skipped IDs to control full-refresh reset, but publishes all selected scopes and merges captured records/checkpoints; its run path has no equivalent all-skipped guard. A record/checkpoint emitted before a later skip can therefore affect Desktop durable state while CLI ignores it. + +Sources: [CLI completion/merge](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/pdpp/store.ts#L67), [all-skipped guard](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/pdpp/runtime.ts#L394), [CLI regression cases](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/test/pdpp/runtime.test.ts#L268), [Desktop projection/commit](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/desktop/src-tauri/src/commands/pdpp_runtime.rs#L1277), [Desktop reset selection](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/desktop/src-tauri/src/commands/pdpp_runtime.rs#L1486), [Desktop state merge](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/desktop/src-tauri/src/commands/pdpp_collection_state.rs#L215). + +This is a source-derived expected outcome; no connector fixture was executed. Owner/next action: collection contract owner plus Node/Rust hosts agree skip/retention semantics and exercise identical protocol cases through both real host interfaces. Native UI does not explain this policy difference. + +### 8. Collection, durable export, ingest, sync and request fulfillment are different thresholds + +CLI commits local export and collection state before HTTP ingest, then tracks delivery separately. Desktop publishes an owner-scoped export before renderer ingest and checks all expected PDPP scopes and cloud sync before its synced marker. Mobile source connection succeeds when anything was written, while DCR completion requires the requested scopes; its checkpoint/snapshot commitment follows accepted delivery scopes. Community task verification accepts any live scope under the source prefix, a deliberately weaker task threshold than exact DCR readiness. + +Sources: [CLI local commitment](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/pdpp/runtime.ts#L408), [CLI ingest outcomes](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/personal-server/index.ts#L149), [Desktop delivery](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/desktop/src/hooks/useEvents.ts#L602), [Mobile source verdict](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/mobile-shell/lib/connect/connect_run.dart#L994), [Mobile checkpoint eligibility](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/mobile-shell/lib/connect/pdpp_connector_state_store.dart#L102), [Community evidence threshold](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/community/src/lib/owner-data/gateway.ts#L335), [Web exact readiness](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/web/src/features/data-connection-requests/scope-readiness.ts#L186). + +Some distinctions are legitimate product rules. The discrepancy is that one informal word, “connected,” cannot prove the same outcome across these apps. The common contract should preserve separate facts: requested, completed, retained, locally durable, ingested, synced, granted and consumed. This does not require every app to have the same success UI. + +### 9. Same source name does not mean the same collector or dataset + +- CLI legacy collection is pinned to an upstream commit; its signed PDPP admission is WHOOP 0.1.0 only, plus explicit local connector extensions. +- Current Desktop PDPP admission is Strava 1.0.1 and WHOOP 0.1.0. Its separately pinned legacy bundle supports other sources. +- Mobile has hosted host-v1 ChatGPT/Anthropic/Strava-browser/GitHub-browser and experimental Oura-browser artifacts, plus curated legacy compatibility. Its generation workflow draws admission from a separate `pdpp-connector-cutover` branch, not the two-pin active Desktop host. +- Web public/light acquisition delegates GitHub, Instagram, LinkedIn, Spotify and YouTube to Data Pipe; Instagram posts are a separate best-effort run. It does not execute CLI connectors. + +Sources: [CLI registry pin](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/connectors/registry.ts#L19), [CLI PDPP pins](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/pdpp/pins.ts#L21), [Desktop pins](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/desktop/src-tauri/src/commands/pdpp_runtime.rs#L36), [Mobile catalog](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/mobile/public/connectors/host-v1/index.json#L4), [Mobile release selection](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/.github/workflows/mobile-connector-catalog.yml#L33), [Web source authority](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/web/src/features/sources/source-scope-authority.ts#L23). + +Scope and history policy differs too: CLI normalizes generic scope names and wraps non-object payloads; Desktop preserves dotted names/bodies; Mobile uses Unity's legacy-scope projection and provider-specific history windows after a full-history run. These are not interchangeable payload contracts. Sources: [CLI resolver](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/personal-server/scope-resolver.ts#L27), [Desktop ingest](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/desktop/src/services/personalServerIngest.ts#L13), [Mobile projection/write checks](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/mobile/src/features/personal-server/owner-data-ingest.ts#L430), [Mobile history policy](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/mobile/src/workflows/connect-flow/drivers/connector-run-input.ts#L54). + +Owner/next action: upstream connector/catalog owners and each surface's capability policy make source + exact scope + runtime + payload/history guarantee explicit. Do not replace proven admission with “listed somewhere” or create another competing public scope catalog. + +### 10. Scheduling and account isolation also differ + +CLI schedules `collect --all --no-input` and can run PDPP with saved sessions. Desktop excludes PDPP from automatic refresh and refuses its non-interactive execution. Mobile's inspected collector workflows are user/DCR-driven; background storage sync is a different job. Sources: [CLI schedule](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/cli/schedule.ts#L24), [CLI PDPP trigger](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/pdpp/runtime.ts#L282), [Desktop exclusion](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/desktop/src/hooks/use-data-refresh-coordinator.ts#L231), [Desktop refusal](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/desktop/src/lib/data-refresh/connector-request-executor.ts#L321). + +Desktop/Mobile explicitly partition provider browser storage by owner. CLI owner-keys collection snapshots, but its host profile root/legacy source profile paths do not supply the same owner binding. The connector may choose an additional partition itself, so this is an isolation-proof gap, not a demonstrated leak. Sources: [Desktop lease ownership](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/desktop/src-tauri/src/commands/pdpp_browser.rs#L61), [Mobile profile](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/mobile-shell/lib/connect/connector_profile.dart#L1), [CLI host input](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/pdpp/runtime.ts#L262), [CLI browser profile](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/runtime/playwright/browser.ts#L447). + +Owner/next action: host owners state supported unattended modes and verify account switching at the provider-profile boundary. Sharing implementation must preserve separate data directories, credentials and native storage authority. + +## Reuse, copied mechanics, and stale maps + +### Existing reuse + +CLI already uses SDK protocol/header/Session Relay primitives. Unity already shares runtime-neutral Personal Server contracts, source vocabulary, legacy-scope projection, Account browser transport and owner-data clients across relevant apps. Connector authoring and Personal Server core remain external. CLI's installer is a vendored upstream copy; Desktop uses the upstream installer through a bridge, at a different pin. They share lineage, not proven byte-identical current revisions. + +Sources: [CLI SDK wrapper](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/server/session-relay.ts#L1), [installer provenance](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/vendor/pdpp-connector-manager/VENDOR.md#L3), [Desktop bridge pin](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/desktop/pdpp-installer-bridge/package.json#L10), [Unity owner-data client](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/packages/owner-data-client/src/owner-data-client.ts#L1), [Unity app runtime](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/packages/app-runtime/package.json#L6). + +### Concrete candidates for consolidation + +CLI's escrow authorization helper explicitly mirrors Account's EIP-3009 fields, beneficiary-nonce construction, domain checks and signature normalization. This is protocol helper duplication; terminal/local app-key funding and Account browser-wallet/ownership guards are legitimate adapters. The shared owner-data client explicitly mirrors Personal Server sync workers' storage/registry write and conflict behavior, while CLI delegates that behavior to its server. Collection skip/merge/completion and scope output are independently governed in Node/Rust/Dart. These are stronger candidates than merely comparing similarly named UI handlers. + +Sources: [CLI mirrored escrow](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/core/escrow-authorization.ts#L1), [Account helper](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/account/src/lib/developers/escrow-authorization.ts#L50), [owner-data worker mirror](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/packages/owner-data-client/src/owner-data-client.ts#L60). + +The CLI's exported runtime is not a full cross-surface engine: it exports legacy managed Playwright, not its internal PDPP host; Unity does not depend on `vana-cli`. Existing March CLI architecture described a thin CLI over reusable orchestration, but current owner orchestration still lives heavily in `src/cli/index.ts`. Sources: [public runtime exports](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/runtime/index.ts#L1), [owner orchestration](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/cli/index.ts#L1797), [historical intended layering](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/docs/CLI-SDK-ARCHITECTURE.md#L42). + +### Version and configuration skew + +| Boundary | CLI | Unity | +| -------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------- | +| SDK declaration | 4.3.1 | Account/Web/Desktop/Mobile/Community 4.1.0 | +| Native/Lite PS declaration | CLI wrapper/core 1.32.0 | Desktop/Web and Mobile Lite 1.29.2 | +| Dev builder gateway | `dp-rpc-dev.vana.org` | Shared Moksha network config uses `dp-rpc.moksha.vana.org` | +| Owner data plane | Local/self-hosted HTTP ingest | Native PS, tab/native Lite, or owner registry/storage/enclave, depending on surface/rollout | + +Sources: [CLI package](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/package.json#L115), [CLI sidecar](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/personal-server/local/runtime-pkg/package.json#L7), [Unity Web package](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/web/package.json#L29), [Mobile Lite package](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/mobile-shell/ps_bundle/package.json#L10), [CLI dev configuration](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/core/network.ts#L74), [Unity network/environment configuration](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/packages/app-runtime/src/personal-server/environment.ts#L127). + +Different versions/URLs are observations, not proof that either endpoint is wrong. Independent configuration owners and staggered rollout make producer/consumer compatibility checks necessary. + +### Documentation is concealing some of the current shape + +Mobile-shell README says PS Lite is retired; active shell composition still lazily creates `PsService` and an export sink whose Account rollout selects legacy Lite, owner-data/enclave or paused. The hosted Mobile route also selects these lanes. This is active wiring, not simply leftover files; the deployed distribution was not checked. Sources: [retirement claim](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/mobile-shell/README.md#L8), [live composition](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/mobile-shell/lib/ui/shell_page.dart#L227), [live sink routing](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/mobile-shell/lib/connect/export_sink.dart#L518). + +Unity's unification tracker still describes owner-to-server lookup as an on-chain stopgap, while the owning helper now wraps the indexed owner endpoint with health gating. That is a stale gap, not another missing service. Sources: [old tracker entry](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/docs/unification-gaps.md#L7), [current lookup owner](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/packages/vana-account-client/src/personal-server-lookup.ts#L1). + +Metrics reads Amplitude connect-v2 vocabulary, while CLI sends a manually mirrored Context Gateway telemetry contract to the telemetry endpoint. This comparison did not trace the external ingestion/translation service; comparable dashboard coverage is unproved, not proven absent. Sources: [Metrics vocabulary](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/apps/metrics/src/lib/connect-v2.ts#L1), [CLI external contract](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/cli/telemetry-contract.ts#L1), [CLI destination](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/cli/telemetry-contract.ts#L222). + +## What the evidence supports doing next + +These are proposed priorities, not authorization or a newly adopted architecture: + +1. **Repair the usable journey joins first.** Resolve the legacy CLI/Account handoff, Web MCP request route, ask/delivery capability and register/claim metadata contract. Prove each at its actual app/server boundary and deployed revision. +2. **Make the access model explicit.** Map OAuth identity, app key, Account attribution, request IDs and enforceable grant IDs. Establish one authoritative grant inventory/revoke source; keep POC results and audit records separate. +3. **Agree collection semantics before extracting code.** Reuse the real connector/protocol owner for scope output, skips, retention, cursor commitment and completion facts. Run common conformance inputs through Node, Rust and Dart hosts. Different native transports can conform without importing the same Node executable. +4. **Consolidate protocol mechanics at their existing owner.** SDK/protocol owns shared signing/payment/grant mechanics; Account retains identity/signing authority; connectors retain extraction/artifact contracts; Personal Server retains data-plane implementation; Unity and CLI retain their product and host adapters. Review the worker-mirror duplication against those actual owners rather than creating a catch-all Unity or CLI engine. +5. **Reconcile current maps and capability claims.** Source/scope/runtime admission, delivery mode, history policy, versions and deployed support must travel together. Correct stale owner docs as separate scoped work; do not infer feature parity from a source card or the word Personal Server. + +Existing preservation: Unity already owns [SDK consolidation candidates](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/docs/vana-sdk-consolidation-candidates.md#L1) and [Direct app doctrine](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/docs/system/direct-vana-data-app-contract.md#L1). The former's audited SDK 3.15.0 baseline is older than these checkouts; its owner placement remains relevant, but its app-specific status was not re-audited here. This note adds the CLI/all-surface comparison rather than duplicating that tracker or creating new rules. The research is preserved at this project owner; a second KB copy would duplicate already-owned material. + +## Limits remaining + +- Actual SDK 4.3.1 request payload, acknowledgment and external server reporting behavior. +- Deployed Account/Web revisions, rewrites, rollout settings and mobile build distribution. +- Cross-host SKIP, cancellation, partial delivery, replay and account-switch behavior exercised through the real interfaces. +- Gateway acceptance/update behavior for blank builder metadata and a complete claim/fund round trip. +- Complete enforcement-level grant visibility/revocation across native and enclave data planes. +- Translation between CLI telemetry and the Metrics/Amplitude observation contract. + +Those checks have named owners above. They are not performed or claimed by this source research. No implementation, dependency update, commit, push, CI or deployment is part of this result. + +## Architectural direction: one plumbing infrastructure, CLI as executable schematic + +**You’re right about the direction. The CLI makes the existing divergence easier to see—and adds another implementation of parts of it.** Your question is stronger than “how much code is duplicated?” + +I’d tighten your principle to: + +> Each plumbing responsibility has one authoritative owner and contract, with one implementation wherever practical. Every surface—including the CLI—uses that owner through the adapters its runtime requires. Surface code owns the experience, not independent versions of the underlying rules. + +That means **one coherent infrastructure with multiple capabilities**: identity, signing, collection, storage, grants, payments and delivery. Each capability can live in its appropriate package or service. + +For the same operation, all surfaces should agree on: + +- What inputs and authority it requires. +- What it does and which state it changes. +- What success, partial completion, cancellation and failure mean. +- What evidence proves completion. + +Where runtimes permit, they should call the same implementation. Where they don’t, separate adapters should implement the same contract and pass the same behavioral cases. A phone WebView and a Node browser need different execution machinery; they shouldn’t independently invent what a skipped stream means. + +**The qualification is “the same operation.”** Public-profile collection and private-account export may require different providers. Owner reads and builder paid reads require different authority. Those distinctions belong explicitly in the common plumbing rather than emerging accidentally from whichever app implemented them. + +Your CLI idea is good too: **the CLI should be an executable schematic of that infrastructure.** Its commands should expose the underlying capabilities, state transitions and outcomes clearly enough that someone can understand and diagnose the system through it. A CLI command should exercise the same plumbing an app uses. + +That does require separating the CLI’s terminal behavior from the capabilities underneath it. Some browser and mobile handshakes will still require a person or device; the CLI can expose their initiation, status and result without pretending to perform every native step. + +So I’d correct the line of questioning to: + +> **Why do our surfaces independently own rules for the same plumbing operations? What is the canonical owner of each operation, and can every surface consume it—with the CLI providing the clearest executable map of the system?** + +That’s the architectural problem the research supports. The next step is to map those operations and their competing owners, then decide which implementation becomes authoritative. Code extraction follows that decision. + +## Why isn't the CLI part of Unity Surfaces? + +**If we understand the CLI as the schematic for our plumbing, it makes sense in Unity Surfaces.** Nothing in the architecture I found requires it to be separate. I found no documented decision specifically explaining its exclusion. + +The current [Unity boundary](https://github.com/vana-com/unity-surfaces/blob/da0c48be65a45468575b6142783c93ea65521985/docs/adr/0001-app-surface-boundary.md) separates product/account surfaces from the surrounding SDK, connector and Personal Server implementations. The CLI currently combines a terminal surface with SDK and runtime responsibilities, and publishes independently. + +That explains the current arrangement. It doesn’t establish that the arrangement is necessary. The CLI’s own [architecture document](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/docs/CLI-SDK-ARCHITECTURE.md) explicitly says it could live in a monorepo and that the CLI should be thin, with business logic underneath it. + +**Under this model, the CLI belongs alongside Web, Desktop and Mobile as another Vana surface.** It could live at `apps/cli`, keep its npm package, signed binaries and release cadence, and consume the same canonical capabilities through Node adapters. + +The plumbing still needs explicit owners: Account for its authority, Personal Server for its responsibilities, shared packages or services for the other capabilities. Repository membership doesn’t require moving every implementation into Unity. + +So the question is fair: **if the CLI is the schematic for our plumbing, why the fuck isn’t it in Unity Surfaces?** Why is a Vana-owned surface maintained separately while independently implementing overlapping plumbing? The documented boundaries don’t adequately answer that. Moving it into Unity could make shared ownership easier, but the substantive change is making every surface consume those same owners. From 97441dd7bc2ac384a97625ee47338bba7cf5ac92 Mon Sep 17 00:00:00 2001 From: Callum Flack Date: Sat, 10 Oct 2026 16:58:02 +1000 Subject: [PATCH 2/2] docs: recheck CLI and Unity research against latest dev --- ...cli-unity-surfaces-discrepancy-research.md | 2 + .../261010-cli-unity-team-response-review.md | 163 ++++++++++++++++++ 2 files changed, 165 insertions(+) create mode 100644 research/261010-cli-unity-team-response-review.md diff --git a/research/261009-cli-unity-surfaces-discrepancy-research.md b/research/261009-cli-unity-surfaces-discrepancy-research.md index 6fb5a7b..9230b95 100644 --- a/research/261009-cli-unity-surfaces-discrepancy-research.md +++ b/research/261009-cli-unity-surfaces-discrepancy-research.md @@ -2,6 +2,8 @@ Date: 2026-10-09, Australia/Brisbane. Status: dated source baseline, not an accepted migration plan. +**Correction, 2026-10-10:** this comparison used the design branch, not current dev/production. The MCP request page in finding 2 and the approving-owner grant union/removal portion of finding 4 were already in a successful 8 October production deployment before this note was written. Finding 4 also covered delivery acknowledgment, which remains a separate conditional gap. See the [latest-dev recheck and team-response assessment](./261010-cli-unity-team-response-review.md) for deployment evidence, all ten updated findings and the public-source/release tradeoffs around moving CLI into Unity. The dated baseline and verbatim discussion below are retained. + Owner: this cross-repository research note in `vana-cli/research`. Revisit after changes to the producer/consumer contracts identified below; the owning source and current tests take precedence over this baseline. Existing Unity doctrine and upstream consolidation candidates remain at their current owners. ## Finding diff --git a/research/261010-cli-unity-team-response-review.md b/research/261010-cli-unity-team-response-review.md new file mode 100644 index 0000000..f4a0924 --- /dev/null +++ b/research/261010-cli-unity-team-response-review.md @@ -0,0 +1,163 @@ +# CLI and Unity: recheck after the team discussion + +Date: 2026-10-10, Australia/Brisbane. Owner: this follow-up and the [original comparison](./261009-cli-unity-surfaces-discrepancy-research.md) in `vana-cli/research`. This is research and a recommendation, not an accepted migration plan. + +## My take + +Volod supports the central argument: we should stop independently maintaining the same plumbing. His public-source and release concerns are real. They change the recommendation from “move the CLI first” to “give shared plumbing one owner first, while preserving public source and independent CLI delivery.” + +The CLI belongs in the map of Unity surfaces. Its source does not have to live in the Unity repository for that to be true. It can be the executable schematic for the same system by calling the same authorities and implementations. Moving files would not, by itself, remove duplicated rules. Separate repositories do not require separate rules either. + +The discussion mixes four choices: where source lives, whether people can inspect it, who owns common behavior, and how each product releases. Decide them separately. The intended rule remains: one authoritative owner for each responsibility, one shared implementation where practical, and runtime adapters that conform to the same behavior where Node, Rust, Dart and browsers cannot execute the same code. + +## The original note needs two immediate corrections + +Our original Unity baseline was the design branch at `da0c48be65a45468575b6142783c93ea65521985`. It was not current dev or production. That made two current-state claims stale when the note was written on 9 October. This recheck uses latest remote dev `6cefcc41a593dc5f7839a6d31aa115669429cfe7`, reconfirmed at the end of source research; remote main was `433441e1ade8725691522fa627952302d6a1f4ba`. CLI remote main remains `f99bec8b235c2c5fdb2bd11875051fb0632f7bfb`. + +The missing MCP request page in finding 2 is implemented. The approving-owner grant union and explicit removals in finding 4 are implemented. Relevant changes are [MCP request page, PR 1517](https://github.com/vana-com/unity-surfaces/pull/1517), [unsigned request loading, PR 1527](https://github.com/vana-com/unity-surfaces/pull/1527), [grant union, PR 1528](https://github.com/vana-com/unity-surfaces/pull/1528), and [Account owner-request signing policy, PR 1526](https://github.com/vana-com/unity-surfaces/pull/1526). All four commits are ancestors of current dev, current main and the successful production deployment described below. + +GitHub's successful `Production – vana-web-prod` deployment `6933198332` was created at 2026-10-08 10:32:23 UTC, or 8 October 20:32 AEST, at `9735af919528c6096d8b33ccca9eaf97d1f38a87`. The Account production deployment `6933203200` has the same SHA and also succeeded. Evidence: [Web deployment statuses](https://api.github.com/repos/vana-com/unity-surfaces/deployments/6933198332/statuses), [Account deployment statuses](https://api.github.com/repos/vana-com/unity-surfaces/deployments/6933203200/statuses), and [deployed commit](https://github.com/vana-com/unity-surfaces/commit/9735af919528c6096d8b33ccca9eaf97d1f38a87). These are authenticated repository records; their successful status does not prove a completed real consent journey. + +A read-only GET to `https://app.vana.org/mcp/requests/research-check` reaches login with that route preserved in `return_to`, final HTTP 200. This establishes the unauthenticated auth join. It does not exercise a real request, render the authenticated decision page or prove a grant was persisted. + +Volod is therefore right to correct finding 2 and the union/removal part of finding 4. Finding 4 also discussed delivery acknowledgment; that part cannot be marked covered merely because union shipped. + +## What the MCP implementation actually does + +The CLI configures the external Personal Server producer with the Web scope-request URL. The new Web page preserves `ps_origin` through sign-in, takes the owner from the active wallet, and verifies the server owner and active server registration through trusted Gateway origins before reading the request. It supports fragment-token reads and explicit signed loading; the older CLI link without a fragment token still has a supported path. + +Approval signs the exact body and selected offered additions; denial has its own endpoint. The signer is Account, and Web verifies that the returned signature recovers the expected owner. Account's silent-signing policy independently checks first-party origin, claim shape, method/path, body hash, freshness, active owner and registered server; refusal falls back to visible confirmation. These are silent-signing eligibility checks, not mandatory checks for every manually confirmed signature. Approval retains Account confirmation by default; silent approval is an explicit environment option. The server response supplies the resulting grant state. + +Sources: [CLI producer](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/personal-server/local/runtime-pkg/entry.mjs#L196), [Web verification and decision flow](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/web/src/features/mcp-scope-requests/use-mcp-scope-request-flow.ts#L218), [exact-body signed calls](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/web/src/features/mcp-scope-requests/scope-request-client.ts#L235), [Account signing policy](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/account/src/lib/signing/owner-request-silent-policy.ts#L148). + +## “Grant union in three places” needs a precise count + +I found two independent app-grant union implementations in the inspected CLI, Unity and installed SDK sources: SDK and Web. CLI's `src/core/grant-union.ts` reexports the SDK planner. It adds CLI-worded conflict handling and CLI request preparation, not a third merge algorithm. + +| Location | What it owns | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| SDK 4.3.1 | Scope preservation/removal and live-grant lookup primitives. | +| CLI | Calls SDK; owns preliminary owner inference, lookup and fallback before making a request. | +| Web | Independently reads the actual approving owner's grant; plans scopes, expiry and version, then repeats the read before signing. | +| Desktop / Mobile paths inspected | Advance or rebase versions and register supplied scopes. They do not perform the same preservation union. | +| MCP | Extends a server-controlled connection's access; returned-scope unions are a different operation. | + +There may be another implementation in an external repository. The screenshot does not identify it, and this review does not claim a global count across uninspected services. Calling every union-shaped view or every registration call another copy would be misleading. + +The two planners are also not interchangeable without agreement on behavior. Installed SDK 4.3.1 drops unparseable carried scope entries and filters inactive rows before choosing the highest live version. Web preserves string entries and chooses the highest row before treating revoked/expired as inactive. They could disagree if a history includes an older live row and a newer revoked row. Gateway intends one row per owner/app, so this is a conditional difference, not an observed live failure. Web also owns expiry/version output beyond the SDK scope-only union result. + +Unity Web is pinned to SDK 4.1.0, whose installed JS/type distribution contains neither `mergeWithLiveGrant` nor `unionGrantScopes`; CLI is pinned to 4.3.1. Web adopting this helper therefore needs a compatible browser-facing export/version and must retain its authoritative pre-sign owner read, expiry/version handling and failure behavior. Removing Web's file alone would not prove that. + +Sources: [CLI SDK delegation](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/core/grant-union.ts#L14), [CLI preliminary planning](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/cli/app/request.ts#L141), [Web live-grant selection and planner](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/web/src/features/data-connection-requests/grant-union.ts#L85), [Web authoritative pre-sign read](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/web/src/app/%28app-shell%29/%28with-nav%29/%28main%29/data-connection-requests/%5Bid%5D/use-data-connection-request-flow.ts#L307), [Desktop registration](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/desktop/src/pages/grant/use-grant-flow.ts#L414), [Mobile registration](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/mobile-shell/lib/dcr/continuation_coordinator.dart#L553), [Web SDK pin](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/web/package.json#L33), [CLI SDK pin](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/package.json#L115). Installed SDK evidence: `dist/direct/grant-union.js:7–56,79–95`, plus JS/type searches of the installed 4.1.0 distribution. No external SDK source checkout was reviewed. + +## Finding 4 still has a separate delivery join + +Direct requests remain read-ready until consumer acknowledgment or supported Personal Server fulfillment reporting completes them. Web's request store distinguishes approved/read-ready from completed, and the continuation waits for actual completed delivery. SDK 4.3.1's approved-read controller calls consumer-ack after successful reads, though it swallows ack failure; even that return value is not durable completion proof. + +CLI `app read` calls lower-level Personal Server reading, or enclave jobs reading, rather than those approved-read controller methods. Its inspected source contains no consumer-ack call. The lower-level SDK reader has no request ID or acknowledgment operation. + +Working Web PS Lite can report served scopes itself, which can complete a CLI read's underlying request. The store matches owner/grant/scope and credits the newest matching request. Thus “CLI never completes a DCR” would overstate the evidence. The remaining issue is conditional: on a lane without a working server-side receipt producer, the inspected CLI consumer supplies no explicit completion acknowledgment. Current Full/enclave receipt behavior was not established by inspecting these two repositories. + +The needed proof is a multi-scope Direct request, real approval, CLI reads over each supported delivery lane, and observation of the specific DCR and continuation reaching their terminal state. Choosing a grant ID alone is not an unambiguous request identity when several requests can share a grant. + +Sources: [completion and fulfillment rules](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/web/src/lib/data-connection-requests/store.ts#L303), [continuation delivery requirement](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/web/src/lib/data-connection-requests/direct-continuations.ts#L651), [Web Lite receipt producer](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/web/src/features/personal-server/web-ps-lite-runtime.ts#L121), [CLI low-level read](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/cli/app/read.ts#L249), [CLI enclave read](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/cli/app/read.ts#L483). Installed SDK evidence: `dist/direct/controller.js:152–175,223–227`, `access-request-client.js:252–267`, and `personal-server-read.js`. + +## All ten original findings, rechecked + +“Still present” here means source evidence at the stated snapshots. It does not mean each discrepancy has been reproduced in production. + +| Original finding | Current assessment | +| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1. Legacy CLI → Account `/connect` | Still source-incompatible: public CLI handoff supplies session/secret but no required `client_id`. The newer Direct CLI path is separate. | +| 2. Missing Web MCP scope-request page | Resolved in current source; relevant commits are in a successful production deployment. Authenticated approval round trip not exercised. | +| 3. Questions and paid reads | Still explicit capability limits: Web enclave approval refuses questions; CLI enclave reads refuse charged responses despite the native paid-read path. | +| 4. Grant preservation/removal and completion | Union/removal resolved; delivery acknowledgment remains a conditional, separate gap. | +| 5. Bare app registration → Account claim | Still conditional mismatch: CLI permits blank URL; Account claim requires usable URL/key. Gateway acceptance was not tested. | +| 6. Account access → CLI grants | Inventory mismatch remains. Correct the old revoke-host wording: current default is DPv2 `dp-rpc.vana.org`, not the retired gateway. Destination repair does not establish grant inventory or ID mapping. | +| 7. PDPP SKIP and durable merge | Same policy divergence: CLI excludes skipped records/cursors and rejects all-skip success; Desktop filters resets but merges captured records/cursors and publishes selected scopes. | +| 8. Collection/delivery completion | Different thresholds remain. Desktop's COMPLETE→STOPPED settling race is repaired in source. Mobile full-history credit now follows actually imported source IDs. | +| 9. Collector/scope/payload parity | Different admission/artifacts and contracts remain. Mobile now includes Discord/X and mixed projected/raw scope ingest; the older five-artifact inventory needs updating. | +| 10. Scheduling and owner isolation | Different unattended support and provider-profile guarantees remain. CLI owner-keyed state/server dirs do not establish provider-browser partitioning. No cross-account leak was demonstrated. | + +Sources for 1/3/5/6: [legacy producer](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/server/connect.ts#L45), [Account required fields](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/account/src/app/connect/_lib/handoff-contract.ts#L23), [enclave question refusal](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/web/src/app/%28app-shell%29/%28with-nav%29/%28main%29/data-connection-requests/%5Bid%5D/use-data-connection-request-flow.ts#L832), [enclave free-read limit](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/cli/app/read.ts#L496), [blank registration URL](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/cli/app/register.ts#L142), [Account metadata requirement](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/account/src/app/api/developers/claim-builder/route.ts#L162), [Account action-row inventory](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/account/src/lib/account-access/repo.ts#L160), [corrected revoke transport](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/account/src/lib/account-access/onchain-revoke.ts#L99). Account's separate DAR exchange still fabricates mock results: [mock grant exchange](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/account/src/lib/data-access-requests/runtime.ts#L315). + +Sources for 7/8/9/10: [CLI skip/merge contract](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/pdpp/store.ts#L67), [CLI all-skip refusal](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/pdpp/runtime.ts#L394), [Desktop skip/reset inputs](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/desktop/src-tauri/src/commands/pdpp_runtime.rs#L1480), [Desktop record/cursor merge](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/desktop/src-tauri/src/commands/pdpp_collection_state.rs#L215), [Desktop settling repair](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/desktop/src/hooks/useEvents.ts#L1235), [actual-import history credit](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/mobile/src/workflows/connect-flow/drivers/pdpp-full-run.ts#L85), [Discord/X catalog additions](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/mobile/public/connectors/host-v1/index.json#L144), [Mobile mixed ingest](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/mobile/src/features/personal-server/owner-data-ingest.ts#L269), [Desktop interaction requirement](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/desktop/src/lib/data-refresh/connector-request-executor.ts#L342), [CLI browser profile root](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/pdpp/host.ts#L310), [Mobile owner partitions](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/mobile-shell/lib/connect/connector_profile.dart#L63). + +A few important limits prevent overstating these findings: + +- Mobile may retain record-free operation state, such as a pending provider export, after a run certifies it collected no records. That can be valid resumability, distinct from advancing a data cursor beyond delivered records. Normal Mobile checkpoint/snapshot commitment follows accepted scope keys. [record-free state retention](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/mobile-shell/lib/connect/connect_run.dart#L844), [delivered-scope commitment](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/mobile-shell/lib/connect/pdpp_connector_state_store.dart#L102). +- CLI individual connection may show connected while a durable local export awaits ingest. Scheduled `collect --all` checks failed/pending delivery and returns nonzero; it does not blindly inherit that individual-command success. [individual connection outcome](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/cli/index.ts#L2568), [scheduled delivery outcome](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/cli/schedule.ts#L330). +- Mobile source success means some scopes were written; DCR continuation separately requires all requested scopes. Community task verification accepts any live scope under its source prefix. Those product thresholds can legitimately differ, but their underlying facts must remain explicit. [Mobile source verdict](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/mobile-shell/lib/connect/connect_run.dart#L994), [DCR requirement](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/mobile-shell/lib/dcr/continuation_coordinator.dart#L546), [Community task evidence](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/community/src/lib/owner-data/gateway.ts#L335). +- CLI and Desktop WHOOP PDPP export outer shapes agree. Generic ingest normalization and Mobile projection/history can still differ. Mobile skips empty standalone files to preserve old data while Desktop selected-empty projection writes an empty stream body. Do not claim every shared WHOOP payload differs. [CLI projection](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/pdpp/store.ts#L141), [Desktop projection](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/desktop/src-tauri/src/commands/pdpp_export_projection.rs#L52), [Mobile empty retention](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/mobile/src/features/personal-server/owner-data-ingest.ts#L302). +- CLI WHOOP and Desktop WHOOP default PDPP artifacts share the digest, while the host skip policy still differs. Desktop also admits Strava; Mobile admission is broader and depends on required native features. Catalog generation draws from `pdpp-connector-cutover`, not current dev's two Desktop pins. [CLI admission](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/pdpp/pins.ts#L21), [Desktop admission](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/desktop/src-tauri/src/commands/pdpp_runtime.rs#L36), [Mobile catalog branch](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/.github/workflows/mobile-connector-catalog.yml#L33), [native capability gate](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/mobile/src/workflows/connect-flow/drivers/host-connectors.ts#L221). + +## Public source and binary delivery are separate choices + +Kahtaf is technically right that software can be distributed as a binary without public source. Claude Code demonstrates that commercial distribution choice: [official setup](https://code.claude.com/docs/en/setup) and [official license](https://github.com/anthropics/claude-code/blob/main/LICENSE.md). That analogy does not settle Vana's privacy or source-availability decision. + +CLI is currently a public MIT repository; Unity is private. These were checked through GitHub repository metadata. Unity has narrower package licenses: Desktop Apache-2.0 and public MIT `service-auth`; absence of a repository-wide detected license does not mean every package is unlicensed. Public-source scrutiny is a concrete reason to preserve access to maintained CLI code. It helps users inspect handling of their data and keys; it does not itself prove runtime privacy, backend behavior or equivalence of release artifacts. + +CLI is already more than a terminal executable. It publishes npm and seven JS import entry points: root, server, React, core, runtime, connectors and CLI. Its README explicitly recommends runtime/connector imports for app integration. Publishing only standalone binaries must not silently discard those external APIs. Their actual consumers were not inventoried in this review. + +Existing SEA distribution is an executable launcher plus an adjacent emitted-JavaScript/dependency payload. It avoids requiring the user's Node installation; it is not a claim that all implementation is compiled into one opaque artifact. Signing/notarization support establishes an available distribution mechanism, not a source audit or proof that an individually inspected release is signed. + +Sources: [CLI repository metadata](https://api.github.com/repos/vana-com/vana-cli), [Unity repository metadata](https://api.github.com/repos/vana-com/unity-surfaces), [CLI license](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/LICENSE#L1), [Desktop license](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/desktop/LICENSE#L2), [public service-auth package](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/packages/service-auth/package.json#L2), [CLI public exports](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/package.json#L26), [library integration guidance](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/README.md#L293), [SEA payload staging](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/scripts/build-sea.mjs#L216). + +A private monorepo can publish public npm packages: Unity already does. Preserving a publicly inspectable maintained source tree and history is another obligation. If CLI moves into private Unity, the proposal needs an explicit public source path, package licensing and publishing owner rather than assuming a binary or npm tarball preserves the current open-source experience. + +## CI concerns are real, but one repository does not require one pipeline + +Unity already releases Desktop and service-auth independently, with separate tags and workflows. CLI already separates some worker/frpc delivery and publishes npm after the binary release. Physical co-location does not require every CLI change to rebuild or release every app. + +The concern is still concrete in today's configuration. Unity PR CI has no workflow-level path filter and installs/checks Account, Web and Desktop broadly. A naive CLI move would inherit those gates. Mobile already has a dependency-closure change gate, showing that narrower checks are feasible. No CI timings were collected here; “would be slower” is an expectation about those additional jobs, not a measured result. + +There is also real release/toolchain work beyond copying a folder: + +| Boundary | CLI | Unity | +| ------------------------ | ------------------------------------------------- | -------------------------------------------------------------------------------------- | +| Supported/tested Node | Supports ≥20; tests 20/22; SEA packaging uses 25 | Root strict engine ≥24.15 and <25 | +| pnpm | 10.29.2 | 10.32.1 | +| Stable delivery | Main semantic-release; npm plus platform binaries | Dev→main promotion; app/package-specific releases | +| Version mutation | Commits package version back | Tag-only releases; no commit-back | +| Public reusable packages | Published npm exports | Most app-core/runtime/owner-data/Account-client packages are private TS source exports | + +Sources: [Unity CI triggers](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/.github/workflows/ci.yml#L3), [broad app checks](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/.github/workflows/ci.yml#L64), [Mobile dependency gate](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/.github/workflows/ci.yml#L138), [Desktop release workflow](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/.github/workflows/release-desktop.yml#L3), [service-auth release workflow](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/.github/workflows/release-service-auth.yml#L3), [Unity engine policy](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/package.json#L54), [CLI test matrix](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/.github/workflows/ci.yml#L24), [CLI packaging matrix](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/.github/workflows/release.yml#L78), [CLI version commit-back](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/.releaserc.yaml#L16), [Unity delivery policy](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/docs/ci.md#L137). + +Current release isolation also has limits: Desktop's relevant-change gate follows dependency closure, but its push trigger watches Desktop/workflow/root-package/lockfile paths, so a shared-package source-only change may never start the workflow. Unity's CI owner records repo-global version/release-note behavior for mixed promotions as deferred work. Vercel ignored-build configuration lives outside these workflows; source alone cannot establish that CLI-only changes would skip every hosted deployment. These are reasons to scope a relocation deliberately, not evidence that independent releases in one repo are impossible. [Desktop trigger paths](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/.github/workflows/release-desktop.yml#L7), [known versioning limitation](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/docs/ci.md#L157), [external deployment wiring](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/docs/ci.md#L86). + +## What I would agree with, and what I would ask the proposal to cover + +Start with grant union. It is small, already has focused behavior tests, and exposes why “shared” needs an exact contract: owner binding, scope preservation, explicit removal, expiry, version, revoked rows and failed live lookups. Use the existing SDK/protocol owner where that is the correct responsibility. Verify all actual callers before deleting their implementations. Desktop and Mobile also need an explicit decision about whether their supplied-scope registration paths should preserve previous access; importing a helper only into CLI and Web would not decide that. + +Then address collection policy and journey joins. Protocol utilities alone do not govern skipped records, empty data, checkpoint commitment, local durability versus ingest/sync, cancellation, provider-account partitioning, capability admission, register→claim, or read→completed-request. Volod's intention is compatible with covering these; the offered first task does not yet specify their owners or proof. + +| Responsibility | Owner to use or settle | Surface-specific effects remain | +| -------------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------- | +| Identity and constrained owner signing | Account authority and its supported client transport | Browser redirect, embedded wallet, terminal/native handoff | +| Grant/payment/signature protocol rules | Existing SDK/protocol/service owner | Product review UI, CLI remedies, wallet/app-key access | +| Connector artifact and collection guarantees | Connector/protocol contract owner, with common host cases | Node Playwright, Rust/native browser, Dart WebView | +| Data storage, ingest and sync semantics | Personal Server / registry/storage owners; check existing client mirrors | Host lifetime, local persistence and device bridge | +| Request readiness and consumption | Web DCR/service authority with explicit consumer completion | App continuation, reads, UI status | +| Release packaging | Each product's release owner | npm, signed executable, desktop/phone packaging | + +This is a proposed ownership direction, not a new universal library. Unity already has shared app-runtime and owner-data packages, while protocol and Personal Server core have external owners. Check those owners before inventing another layer. The owner-data client explicitly mirrors server sync workers, and CLI escrow helpers explicitly mirror Account; those are concrete consolidation candidates alongside grant planning and host collection policy. [Unity ownership boundary](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/docs/adr/0001-app-surface-boundary.md#L3), [sync-worker mirror](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/packages/owner-data-client/src/owner-data-client.ts#L63), [Account escrow mirror](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/core/escrow-authorization.ts#L13), [existing SDK tracker baseline](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/docs/vana-sdk-consolidation-candidates.md#L24). + +My recommendation is to preserve public CLI source and independent delivery now, consolidate demonstrated shared rules, and keep CLI in the system map as an executable view of the same plumbing. Revisit repository placement when the benefit of atomic cross-surface changes justifies the visibility, packaging, compatibility and CI work. The condition of success is that the surfaces use the same authoritative behavior, not that their folders share a parent. + +## Additional source findings and limits + +A new Desktop cancellation candidate deserves native proof. A legacy connector run is registered before browser detection/possible download; its process is only stored after that await. Stop can find no process/window, remove the run and return OK. The pending start has no cancellation check before spawning. The renderer also marks stopped before native stop acceptance and hides native failure in its returned status. Source suggests an accepted cancel during preparation could still launch collection; no repro was executed. Owner: Desktop native connector lifecycle. Next check: cancel during blocked browser preparation, then observe process/window and run state after preparation resumes. [preparation and later spawn](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/desktop/src-tauri/src/commands/connector.rs#L1533), [run registration](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/desktop/src-tauri/src/commands/connector.rs#L1929), [stop path](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/desktop/src-tauri/src/commands/connector.rs#L2386), [renderer stop acceptance](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/desktop/src/lib/data-refresh/connector-request-executor.ts#L179). + +Stale maps still matter. Mobile-shell says Lite is retired but its active shell composition retains a rollout-selected Lite lane; the on-chain lookup gap tracker conflicts with the active indexed HTTP lookup helper. The SDK consolidation tracker still has an August/3.15.0 audit baseline. Current docs must not stand in for current callers or deployed phone distributions. [Lite retirement statement](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/mobile-shell/README.md#L9), [active Lite composition](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/apps/mobile-shell/lib/ui/shell_page.dart#L227), [old lookup gap](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/docs/unification-gaps.md#L11), [current indexed lookup](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/packages/vana-account-client/src/personal-server-lookup.ts#L1). + +SDK pins remain 4.3.1 versus 4.1.0; PS core/Lite pins remain 1.32.0 versus 1.29.2. CLI dev deployment uses `dp-rpc-dev.vana.org`, while shared Unity Moksha defaults use `dp-rpc.moksha.vana.org`; normal CLI Moksha also uses the latter. These observations do not establish incompatibility. Current Unity runtime docs correctly name one DPv2 gateway. External telemetry translation was not examined, so CLI dashboard coverage remains unproved rather than absent. [CLI dev override](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/core/network.ts#L74), [Unity network defaults](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/packages/app-runtime/src/personal-server/environments.json#L14), [current gateway boundary](https://github.com/vana-com/unity-surfaces/blob/6cefcc41a593dc5f7839a6d31aa115669429cfe7/docs/runtime-boundary.md#L21), [CLI telemetry destination](https://github.com/vana-com/vana-cli/blob/f99bec8b235c2c5fdb2bd11875051fb0632f7bfb/src/cli/telemetry-contract.ts#L222). + +## Proof and capture + +Three delegated source reviews covered Account/Web grant and MCP authority; all remaining app/host findings; and visibility, packaging, CI and ownership. Clean archive snapshots were used without switching the shared Unity checkout or altering its existing Desktop edit. Root separately checked GitHub metadata, fetched current refs, verified production commit ancestry/status, inspected the unauthenticated route join and ran existing focused tests. + +All 35 tests in five files passed against the exact dev snapshot with installed third-party dependencies: Web `grant-union.test.ts`, plus MCP `scope-request-client.test.ts`, `server-verification.test.ts`, `approval-link.test.ts` and `request-read-token.test.ts`. These verify planner rules, signed request construction/owner binding, server verification, link validation and tab-token persistence. They do not prove real Account wallet consent, server persistence, provider collection, native cancellation or CLI delivery completion. No new tests, dependency installation or product-source changes were made for this recheck. + +Further proof remains with the named owners: authenticated MCP grant round trip; DCR completion on each advertised CLI read lane; legacy exported handoff and register/claim deployed contracts; real Node/Rust/Dart skip/cancel/account-switch cases; published API consumer inventory; external services and hosted build settings. The recheck does not mark those journeys tested or repaired. + +The material is preserved at the existing project research owner. A second KB copy would duplicate it, so learning capture stays here. The original note gets a dated correction pointer; its dated evidence and verbatim user sections remain intact. This follow-up changes documentation only.