diff --git a/docs/architecture/phone-app.md b/docs/architecture/phone-app.md index 845e91bf..2823c206 100644 --- a/docs/architecture/phone-app.md +++ b/docs/architecture/phone-app.md @@ -30,6 +30,9 @@ JS `coreHome()` returns `beans-v2/core` or `beans-dev-v2/core` without mkdir; co - **Group details**: Group Info edits Name and Description; Description pushes a full editor and saves through `chats.set_description`. Every member reads the shared description in its system prompt. A DM uses its bot's description instead; see [DMs and groups](bots.md#the-lead-bot). - **Memory services** (`app/chat-info/memory/`, `app/settings/memory/`, `src/core/memoryService.ts`): DM Details › Memory opens the bot's recall/capture draft, explicit save/search/inspect/reflect, delivery queue, fenced deletion and capability-driven backend panels. The page links account connections and embedding profiles. The focused native wrapper uses the same public `beans-core.request` transport as `engine.ts`; service operations route to the assigned Runner, while local asset setup names a selected paired Runner. The phone contains no vector SDK or ONNX runtime. Stored keys/endpoints/options stay masked; secret edits distinguish keep, replace and clear. OpenViking binds exact bot IDs to USER keys or an explicitly trusted gateway. Capture starts off, covers future eligible turns only, and group text has separate approval; unattended capture stays unavailable without enforceable downstream spending policy. Service, reflect and advanced operations require explicit action approval with plaintext/cost disclosure, never render-time requests or automatic retries. Pgvector setup displays the actual target and full SQL; Lance binding/export/import displays private Runner-local paths, namespace and vector-space fingerprint. Local runtime/model/tokenizer setup previews exact sources, licenses, bytes and hashes on the selected Runner. Apply sends only the frozen one-use token/digest and affirmative confirmation, not changed paths or SQL. The independent local MEMORY.md editor retains hash-based conflict protection. Save/Cancel and system dismissal share draft guards; busy work blocks removal and failed requests retain drafts. Phone fixture tests cover consent, masking, exact approvals and failure states without live service calls. +Basic memory actions remain visible with a reason when their capability is absent. Advanced panels require both a negotiated feature and an exact permitted verb and are omitted when unavailable. All service actions use the existing native request adapter; capability checks also reject unsupported dispatch before transport. + + Memory deletion invalidates its confirmation at attempt start and refreshes preferences in `finally`, including failed and pending remote results. A failed refresh disables document/bank deletion until an explicit refresh succeeds; cleanup confirmation uses the refreshed deletion epoch. OpenViking connection edits patch only named bot IDs: omitted bindings keep their private identity/key, and explicitly confirmed `null` removes only that bot’s binding. Keep key requires the exact saved bot/mode/account/user identity, enforced by core. Changing identity, changing key action or removing/reopening a draft discards entered replacement bytes. Metadata-only saves omit options; the phone never sends whole-map replacement flags or reads saved keys back. Advanced panels intersect their concrete adapter-defined forms with the negotiated `advanced_actions` map for the exact feature and verb. Missing or empty permissions hide feature links, action selectors, fields and Run controls; feature-level support alone never authorizes a verb. The request helper rechecks exact permission and plaintext approval before dispatch. Document deletion is excluded from advanced actions and uses only the confirmed revision/epoch-fenced `memory.service.delete` path. diff --git a/docs/assessments/phone-memory.md b/docs/assessments/phone-memory.md new file mode 100644 index 00000000..0af52e9c --- /dev/null +++ b/docs/assessments/phone-memory.md @@ -0,0 +1,32 @@ +# Phone memory control assessment + +Issue [#103](https://github.com/bloodf/beans/issues/103), PR [#356](https://github.com/bloodf/beans/pull/356). Source baseline is main `f3f793d49f40e66f416084c512aba2738a3f867e`, integrated into the reserved PR without rewriting phone pages. This is a source and fixture contract, dated 2026-11-07. Satisfied means the source implements the control; it does not mean device acceptance passed. + +## AppKit checklist mapping + +The acceptance list in [#101](https://github.com/bloodf/beans/issues/101) is the comparison contract. References below name current definitions or page controls so they remain searchable as line numbers change. + +| Control | Assessment | Source evidence and remaining acceptance | +| --- | --- | --- | +| Create connection with keep/replace/clear | satisfied | `mobile/app/settings/memory/connection.tsx` calls `setConnection` with `secretPatch`; `mobile/src/ui/memoryUI.tsx` exposes `MemorySecret`; `mobile/src/core/memoryService.ts` `connectionRequest` preserves omitted fields and strips arbitrary scope. Existing `memoryService.test.ts` covers masked configuration, secret patches and blocked Lance Cloud configuration. Device save/reopen is deferred. | +| Bind bot and enable recall with consent | satisfied | `mobile/app/chat-info/memory/[id].tsx` connection chooser, Approve Exact Recall/Capture Choices and Save use `MemoryPreferencesDraft` and `savePreferences`. Draft defaults disable capture/recall; exact bot/connection/choices approval is required. `memoryService.test.ts` covers approval; `memoryAdvanced.test.ts` covers cap increases and invalid budgets. | +| Changing connection clears approvals | satisfied | `MemoryPreferencesDraft.connectionID` clears plaintext/group approvals and invalidates saved consent, including switching back. Existing consent fixture in `memoryService.test.ts` exercises connection changes. | +| Missing capability disables rather than hides | partial | `[id].tsx` `reason` supplies disabled reasons to `MemoryAction` for basic controls. `memoryUI.tsx` removes `onPress` when a reason exists. Advanced panels use `advanced.filter` and `advancedForms`, so absent feature/verb hides them. This is an explicit difference from #101, consistent with the current shared advanced-action contract in `docs/architecture/memory-ui.md`. No new issue or page rewrite is proposed without a product decision to change that contract. `phoneMemoryContract.test.ts` proves each basic action rejects absent/false capability before dispatch and sends the exact payload only when enabled. `memoryAdvanced.test.ts` covers absent maps and sibling verbs. | +| Health, delivery_unknown and deletion pending are distinct | satisfied | `[id].tsx` displays Service state, Readiness reason, Deletion pending, each operation state and the queue deletion state separately. `readMemoryHealth` and `readMemoryOperations` retain these states. Only completed means stored; pending never means verified erasure. Existing service and deletion fixtures cover parsing and deletion refresh locks. Device presentation remains deferred. | +| Every control has an accessible name | missing | `mobile/src/ui/forms.tsx` `ToggleRow` and `FieldRow` do not attach their sibling title/label to Switch/TextInput in this baseline. Already assigned [#329](https://github.com/bloodf/beans/issues/329), PR #362. No duplicate issue or shared-form edit here. VoiceOver/TalkBack acceptance is NOT_RUN. | + +## Other shared controls + +| Control | Assessment | Source evidence and boundary | +| --- | --- | --- | +| Embedding profiles | satisfied | `mobile/app/settings/memory/embedding.tsx` supplies full API/local profile edits; `embeddingRequest` validates vector space, preserves prefixes and excludes local Runner paths. `memoryAdvanced.test.ts` covers that boundary. Saving does not perform inference or reindexing. | +| English and Simplified Chinese | missing | Memory page text and `memoryUI.tsx` disclosures are English literals at this baseline. Already assigned [#330](https://github.com/bloodf/beans/issues/330), PR #365. This assessment does not edit localization. | +| Explicit service action and no automatic remote work | satisfied | `[id].tsx` opens with listConnections/getPreferences only. Health/retain/reflect use explicit confirmations. `memoryServiceNative.ts` passes the existing public native `request` to the adapter. Fixture dispatch proves adapter behavior, not native transport delivery or mounted UI behavior. | +| Fenced deletion and setup | satisfied | `memoryTask.ts` `MemoryDeletionState` locks and refreshes authoritative preferences after deletion. `memoryDeletion.test.ts` tests failure and epoch handling. `memoryService.ts` setup approval objects bind target/revision/expiry and are consumed once; `memoryAdvanced.test.ts` tests stale, expired and reused approvals. No remote erasure or DDL is executed by these fixtures. | +| Local MEMORY.md | satisfied | `mobile/app/chat-info/memory/local.tsx` uses the separate local editor with expected hash; `memoryAdvanced.test.ts` tests stale-hash refusal. This is independent of service capture. | + +## Verification and acceptance boundary + +Run the existing mobile Vitest configuration with `src/core/phoneMemoryContract.test.ts`, `src/core/memoryService.test.ts`, `src/core/memoryAdvanced.test.ts` and `src/ui/memoryDeletion.test.ts`. Run `pnpm run check:docs` and the existing mobile typecheck through the assigned executor. There is no mobile lint script in this baseline. This change adds fixtures and documentation only; it changes no native build input or production mechanism. + +Manual device, hardware, browser, E2E and full-suite acceptance are NOT_RUN/deferred. In particular #103's manual scenario remains open. #329/#330 completion must be reconciled at their actual merged heads, followed by device acceptance; draft ownership is not evidence that either gap is fixed. No additional confirmed missing implementation outside those existing assignments was found in this bounded assessment. diff --git a/mobile/src/core/phoneMemoryContract.test.ts b/mobile/src/core/phoneMemoryContract.test.ts new file mode 100644 index 00000000..570bbf7f --- /dev/null +++ b/mobile/src/core/phoneMemoryContract.test.ts @@ -0,0 +1,33 @@ +import { expect, test } from 'vitest'; +import { MemoryServiceAPI, type MemoryCapabilities } from './memoryService'; + +// The existing phone controls share this adapter with the native request wrapper. +const revision = { counter: 7, device_id: 'fixture' }; +const controls = [ + { capability: 'recall', method: 'memory.service.recall', params: { bot_id: 'bot', query: 'query' }, run: (api: MemoryServiceAPI, caps: MemoryCapabilities) => api.recall('bot', 'query', caps, true) }, + { capability: 'reflect', method: 'memory.service.reflect', params: { bot_id: 'bot', query: 'query' }, run: (api: MemoryServiceAPI, caps: MemoryCapabilities) => api.reflect('bot', 'query', caps, true) }, + { capability: 'inspect', method: 'memory.service.inspect', params: { bot_id: 'bot', document_id: 'doc' }, run: (api: MemoryServiceAPI, caps: MemoryCapabilities) => api.inspect('bot', 'doc', caps) }, + { capability: 'retain', method: 'memory.service.retain', params: { bot_id: 'bot', text: 'note', request_id: 'request' }, run: (api: MemoryServiceAPI, caps: MemoryCapabilities) => api.retain('bot', 'note', 'request', caps, true) }, + { capability: 'operation_status', method: 'memory.operations.status', params: { bot_id: 'bot', id: 'op' }, run: (api: MemoryServiceAPI, caps: MemoryCapabilities) => api.operation('bot', 'op', 'status', caps, true) }, + { capability: 'cancel_operation', method: 'memory.operations.cancel', params: { bot_id: 'bot', id: 'op' }, run: (api: MemoryServiceAPI, caps: MemoryCapabilities) => api.operation('bot', 'op', 'cancel', caps, true) }, + { capability: 'delete_document', method: 'memory.service.delete', params: { bot_id: 'bot', document_id: 'doc', connection_revision: revision, deletion_epoch: 4, confirm: true }, run: (api: MemoryServiceAPI, caps: MemoryCapabilities) => api.delete('bot', 'doc', revision, 4, caps, true) }, + { capability: 'clear', method: 'memory.service.delete', params: { bot_id: 'bot', connection_revision: revision, deletion_epoch: 4, confirm: true }, run: (api: MemoryServiceAPI, caps: MemoryCapabilities) => api.delete('bot', undefined, revision, 4, caps, true) }, +] as const; + +for (const control of controls) { + test(`${control.capability} requires its negotiated capability before transport`, async () => { + const calls: { method: string; params: unknown }[] = []; + const api = new MemoryServiceAPI(async (method, params) => { + calls.push({ method, params }); + if (method === 'memory.service.delete') return { pending: true, deletion_epoch: 5, operation_id: 'remote' }; + if (method === 'memory.service.retain' || method.startsWith('memory.operations.')) + return { id: 'op', document_id: 'doc', state: 'delivery_unknown', operation_id: 'remote', error_code: null }; + return { evidence: [], document: null, operation: null, data: {} }; + }); + await expect(control.run(api, {})).rejects.toThrow('unsupported_operation'); + await expect(control.run(api, { [control.capability]: false })).rejects.toThrow('unsupported_operation'); + expect(calls).toEqual([]); + await control.run(api, { [control.capability]: true }); + expect(calls).toEqual([{ method: control.method, params: control.params }]); + }); +}