@stelis/say-ur-intent 0.0.0

package/docs/FRONTEND_POLICY.md

@@ -0,0 +1,234 @@
+# Frontend Policy
+
+Say Ur Intent frontend pages are local review and wallet-context surfaces. They
+exist to show server-validated facts, capture explicit wallet gestures, and
+keep AI reasoning separate from wallet authority.
+
+The current release ships the wallet identity page, local settings page, and a
+blocked or non-signable review page that can display server-computed review state.
+The review server may build local unsigned DeepBook swap transaction material
+during account-bound review, but the frontend does not receive transaction
+bytes outside the digest-gated handoff. The review page offers a sign action
+only on a `ready_for_wallet_review` state whose wallet account matches the
+reviewed account; it never builds transactions in the frontend.
+
+## Role
+
+Current release frontend surfaces may capture wallet identity, display review
+state, and request refresh when allowed. They do not submit wallet signatures or
+execution results.
+
+It is not a trading dashboard, AI chat, portfolio app, alert surface, analytics screen, or safety oracle.
+
+## Display Priority
+
+Show the minimum facts needed for the user's decision first:
+
+1. What is happening?
+2. Can the user proceed?
+3. What happens if the user proceeds?
+4. What is the next action?
+
+Technical details belong behind compact details controls. Raw protocol data must not dominate the primary screen.
+
+## Information Source
+
+Primary UI may render only server-validated structured data. AI-generated interpretation must not appear as trusted review fact.
+
+The frontend must not compute quote truth, readiness, blocked status, safety, or
+final execution truth. In the current release, it may render state, connect a
+wallet, ask the server to refresh, and revoke wallet identity when that action
+exists. Wallet or signing result submission is not a current-release frontend
+capability.
+
+## Wallet Identity
+
+Wallet identity is the product path for active-account reads and account-bound review. Manual address entry is not a product path for the review UI or wallet identity flow. MCP explicit-address inputs for public coin balance snapshots are separate read-only tool inputs and do not create active account context.
+
+Sender-independent DeepBook market reads do not require wallet identity. Wallet identity capture is not signing authorization.
+
+The user must be able to see the active wallet account when connected.
+
+Reusable identity sessions may set an ambient read context after the user connects a wallet. This read context remains until the user clears it or replaces it with another wallet identity. It must be presented as active account context, not login, signing authorization, custody, or permission for transactions.
+
+When a wallet exposes multiple accounts, Say Ur Intent captures the account returned by the wallet connection result. The UI must display that account clearly. Choosing a different account requires replacing the active account context with another wallet identity connection.
+
+## Review Surface
+
+Each action review is a separate ceremony. The review screen prioritizes asset flow over protocol internals.
+
+Required primary facts:
+
+- action summary
+- send amount
+- expected receive or minimum receive
+- current review status
+- next action
+
+When a user can spend more than the displayed send amount, the top-level asset flow must show the spend limit with explicit language such as `up to`. Do not hide max spend in secondary details when it changes the user's decision.
+
+`assetFlowPreview` entries with `amountKind: "display_intent"` are display-only proposal facts. They are different from review-time `assetFlowActual`, simulation summaries, and balance changes, and the frontend must not use them as signing input, minimum receive, or transaction-building input.
+
+When a plan includes `reviewModel`, the review page must show the external
+proposal source, proposed action, asset flow, recipient or target, freshness,
+missing evidence, required user choices, unsupported claims, blocking checks,
+and `nonSignableReason`. These fields are review annotations only. They are not
+transaction material. They are not route selection or settlement-token
+selection. They are not wallet readiness, signing readiness, or execution
+safety.
+
+In the current release, the review page may create a wallet identity session, reload the active account context, and request account-bound review computation.
+
+It renders server-returned review checks for the resolved direct pool, raw quote evidence, quote freshness, derived raw min-out policy, DEEP fee raw evidence, and internal digest commitment.
+It may also render a server-returned check that local unsigned DeepBook swap
+transaction material was built and kept internal to the review server.
+It may render `reviewState.humanReadableReview` when the server returns it. That
+summary is displayable review evidence projected from server-verified private
+review artifacts. The frontend must not recompute its quote truth, object
+ownership, freshness, blocked status, or readiness.
+It may render `reviewState.simulation` when the server returns it. That summary
+is a redacted projection from private review-time simulation evidence for stored
+local transaction material. The frontend must not recompute simulation truth.
+The frontend must not extract transaction bytes or a public digest from it.
+The frontend must not treat it as wallet readiness or signing readiness.
+The frontend must not treat it as execution readiness or proof of wallet
+submission.
+
+It must keep those checks as review evidence only.
+It must not treat them as public transaction bytes, wallet readiness, signing readiness, route quality, or execution safety.
+
+Compact secondary facts:
+
+- venue or protocol
+- quote timestamp
+- gas estimate when available
+- max spend when available
+
+Details:
+
+- pool ID
+- package ID
+- object changes
+- balance changes
+- simulation summary
+- Review checks
+
+Review checks are generally details. Failed checks and warning checks that determine the current `blocked` or `refresh_required` status must be elevated next to the status banner so the user can understand the reason without opening details.
+
+If the server returns a `PtbVisualizationArtifact`, the frontend may render only
+Mermaid flowchart text plus diagnostics. The panel must show the generated time,
+source, diagnostics, and unsupported-use boundary when those fields are present.
+It must not store or render executable transaction material, wallet signature
+requests, private-key material, or arbitrary Move calls. A PTB graph is not a
+sign action, not a transaction-building action, not a wallet readiness signal,
+not a signing readiness signal, not a payment execution readiness signal, not a
+route-quality signal, and not an execution-safety signal.
+
+## Current Release State Rules
+
+The review page is a state wizard with three displayed steps (Review, Sign,
+Result) over nine page states. Every state keeps the same constant layout: the
+step indicator, a one-line state headline, the constant Transaction card
+(plan-level values that fill in with reviewed values), the state-specific
+block, and a collapsed Raw evidence card (audit record with a
+copy-as-Markdown action). Only the current state's actions are rendered;
+out-of-state buttons are removed, not disabled.
+
+The sign action appears only on `ready_for_wallet_review` with an emitted
+wallet review contract, a connected wallet whose account equals the reviewed
+account, and a successful digest-gated handoff. The signing wallet list offers
+only the wallet recorded for the active account; other detected wallets are
+not offered. While a handoff is outstanding the server locks the session
+(state recomputes are refused) and the page shows a signing-in-progress state
+whose only action is cancel. Other states render:
+
+- `refresh_required` and an expired quote: hide the sign action and show the
+  refresh action with the safe-funds copy.
+- `blocked`: hide the sign action and show a human-readable reason plus the
+  retry action.
+- recorded execution result: show the receipt card (status, digest, failure
+  reason) with no review or sign actions; the session is finished.
+- `expired`: show expiration and a concrete restart path. The default restart path is to return to the AI client and request a new wallet identity or review session.
+
+External proposal review sessions are non-signable. Their primary action is to
+inspect the review facts and return to the AI client with any remaining user
+choices.
+
+## Actions
+
+Each state should expose at most one primary action.
+
+The review page may show an account-bound review action when an active account is present and no review state has been recorded for the selected plan.
+
+It may also show that action when the server status requires refreshed account-bound evidence.
+
+That action asks the local review server to compute review state.
+It is not a sign action, frontend transaction-building action, wallet readiness signal, signing readiness signal, or route-quality signal.
+
+Do not show a quote/evidence refresh button unless the quote expired, the
+status is `refresh_required`, or no review state has been recorded yet.
+
+Do not automatically close tabs after terminal results. Do not silently renew identity sessions. Do not edit amount, slippage, target asset, or venue on the frontend; revisions go back through AI and MCP.
+
+Loading and waiting states must use plain status copy. For wallet identity, use copy such as `Finish or cancel the request in your wallet popup`. For signing, keep the user's attention on the wallet popup and do not add extra choices.
+
+If a terminal or unrecoverable frontend error occurs, show one clear message and one recovery route. Examples: invalid token, missing session, expired session, unsupported chain, or no compatible wallet.
+
+## Language
+
+Use short, direct, non-promotional copy.
+
+Do not say:
+
+- safe
+- recommended
+- best
+- guaranteed
+- approved by AI
+
+Prefer:
+
+- ready for wallet review
+- refresh required
+- blocked
+- expected receive
+- minimum receive
+- checked at
+
+Source fields may keep protocol-facing names such as `fetchedAt`. Frontend labels should map them to user-facing copy such as `checked at`.
+
+Frontend labels stay in English. Localization must preserve protocol names, token symbols, object IDs, package IDs, and reason enums without translation.
+
+## Security
+
+Tokens must not be accepted in query strings. Wallet addresses must not be written to local event logs in plaintext. Private keys, signatures, transaction bytes, and arbitrary Move calls must not appear in frontend state.
+
+CSP should prefer external assets and avoid inline script or inline style. Host, Origin, and session token validation are mandatory for state-changing APIs.
+
+Wallet and review screens must be keyboard reachable and screen-reader labeled. Status and error changes must be exposed as text, not color alone.
+
+Native push notifications are out of scope. A frontend may use low-authority browser affordances such as document title changes for off-tab terminal results, but only after server status changes.
+
+Each session URL represents one independent tab surface. Cross-tab state sharing is out of scope unless a shared local store is explicitly designed.
+
+## Out Of Scope
+
+The frontend must not add:
+
+- price charts
+- candlesticks
+- portfolio dashboards
+- AI chat
+- trading recommendations
+- alerts
+- automatic transaction history dashboard pages
+- multi-wallet comparison
+- saved plans or bookmarks
+- arbitrary strategy controls
+
+The exclusions above target automatic, background-indexed, or
+recommendation-style surfaces. A user-requested local record view — the
+analysis page that shows a wallet asset snapshot at a fetched timestamp and
+summaries of locally stored review and activity records — is a deliberately
+sequenced roadmap surface, not part of these exclusions. That planned view must
+still avoid P&L, valuation, performance, and tax claims, and must not add background indexing.

package/docs/LOCAL_DB_ARCHITECTURE.md

@@ -0,0 +1,85 @@
+# Local DB Architecture
+
+Say Ur Intent uses a local SQLite database for durable product state that must survive MCP server restarts. The database stores account read context, Say Ur Intent review activity evidence, and user-requested bounded Sui activity facts. It is not a custody store, wallet authorization store, background indexer, complete wallet-history store, or raw transaction archive.
+
+This document is for maintainers and contributors who change local state, import/export behavior, activity queries, or review evidence storage. Product users normally need only the README and `docs/MCP_SETUP.md`.
+
+## Engine
+
+The runtime uses the `better-sqlite3` npm package for normal SQLite file semantics and incremental writes. Users do not install a separate database server.
+
+The package targets Node.js `>=22`. Node 22 or 24 LTS is recommended.
+
+`better-sqlite3` is an npm dependency, not a separate product database installation. The pinned version is `12.9.0`. Standard macOS arm64/x64, Linux arm64/x64, and Windows x64 platforms normally use prebuilt binaries; less common platforms such as Windows arm64 can require a native build toolchain. The release check verifies that the driver can be imported, can create an in-memory database, and also works after installing the packed tarball.
+
+## File Location
+
+On first start, the runtime creates a SQLite file named `say-ur-intent.sqlite` under the operating system's app data directory for Say Ur Intent.
+
+The optional override is:
+
+```bash
+export SAY_UR_INTENT_DATA_DIR="/path/to/local/app-data"
+```
+
+Product docs, MCP responses, and tool outputs must not reveal a user's absolute database path. Use placeholders in documentation.
+
+## Open Policy
+
+Every database connection applies:
+
+```sql
+PRAGMA journal_mode=WAL;
+PRAGMA synchronous=NORMAL;
+PRAGMA foreign_keys=ON;
+```
+
+Writes use SQLite's normal file-backed engine. On startup, the runtime creates the tables listed in [Tables](#tables) when the database file is empty.
+
+Delete the local DB files or set a new `SAY_UR_INTENT_DATA_DIR` when resetting local product data files.
+
+WAL mode can create companion files next to the main database, such as `say-ur-intent.sqlite-wal` and `say-ur-intent.sqlite-shm`. Backups and manual moves should keep those files together with the main database while the MCP server is stopped. Avoid placing `SAY_UR_INTENT_DATA_DIR` in cloud-synchronized folders such as iCloud Drive, Dropbox, or similar sync roots because WAL companion files can be copied out of order.
+
+## Tables
+
+- `accounts`: normalized Sui account addresses and first/last use timestamps.
+- `active_account_context`: a single-row read context. It can point to one active account or be cleared.
+- `review_sessions`: review session header, current status, full action plan JSON, and materialized requested intent JSON when present.
+- `review_state_snapshots`: append-only account-bound `ReviewState` snapshots with status and reason columns for queryability.
+- `review_status_transitions`: append-only review lifecycle timing for funnel and review-timing analysis.
+- `review_executions`: Say Ur Intent review execution result evidence, keyed by `review_session_id`.
+- `external_activity_scans`: user-requested digest lookups, bounded account scans, or sent-function scans, including request window, endpoint host, chain identifier, continuation metadata, coverage signals, and internal scan-kind provenance.
+- `external_activity_transactions`: normalized Sui transaction facts linked to a known local account and the first/last scan that observed them. The optional detail JSON stores typed facts such as capped Move call targets, raw balance changes, object changes, event summaries, gas raw cost fields, execution errors, and truncation flags when GraphQL returns them. Each stored detail JSON value is capped at 64 KiB.
+- `local_settings`: allowlisted local settings. The current key set is `suiGrpcUrl` and `suiGraphqlUrl`, stored as JSON-encoded text and applied after restart.
+- `coin_metadata_cache`: account-independent positive cache for Sui coin metadata used only to format wallet balance display amounts. Rows are keyed by normalized coin type and verified mainnet chain identifier, expire after 24 hours, and are excluded from local data export/import. Read or write failures for this cache block affected wallet unit reads with `metadata_cache_unavailable`; they are not reported as unavailable token decimals.
+
+Database columns use snake_case. MCP and HTTP JSON fields use camelCase, so the database `review_session_id` column stores the same review-session identity exposed as `reviewSessionId` in API responses.
+
+Table relationships:
+
+- `active_account_context.account_id` and `review_sessions.account_id` point to `accounts.id` when an account is present.
+- `review_state_snapshots`, `review_status_transitions`, and `review_executions` point to `review_sessions.id` through `review_session_id` and can also point to `accounts.id` through `account_id`.
+- `external_activity_scans.account_id` points to `accounts.id`. It records which known local account the user-requested lookup or scan was scoped to.
+- `external_activity_transactions.account_id` points to `accounts.id`, and `first_scan_id` / `last_scan_id` point to `external_activity_scans.scan_id`. `known_sender_account_id` points to `accounts.id` only when the sender is also a known local account. Non-known party account addresses are not stored; normalized detail JSON keeps account-owner and event-sender fields only when they match the known local account.
+- `coin_metadata_cache` is account-independent and is keyed by coin type plus chain identifier.
+- `local_settings` is independent local configuration and does not point to account or review rows.
+
+The database does not create background transaction indexing tables. Complete external transaction history, raw GraphQL payloads, transaction bytes, signatures, BCS payloads, non-known party account addresses, and arbitrary transaction payloads are not product surfaces of this database.
+
+Schema version 4 adds the `external_activity_scans.kind = 'function_scan'` provenance value. The startup migration rebuilds `external_activity_scans` with foreign keys temporarily disabled, copies rows unchanged, recreates indexes, runs `PRAGMA foreign_key_check`, and updates `user_version` only after the transaction succeeds. Existing rows are not backfilled from `account_scan` to `function_scan` because earlier scan rows do not store the function target needed for safe identification. Local-data backups containing `function_scan` provenance can be imported by version 4 runtimes; older runtimes reject them through their scan-kind validator rather than partially importing unsupported provenance.
+
+Logical local data reset is the local settings page action that clears stored product state through the runtime without requiring manual database-file deletion. Replace-only import is the settings page import path that replaces local product state from a validated backup. Both logical local data reset and replace-only import clear `coin_metadata_cache`. Clearing active account context does not clear it because coin metadata is account-independent.
+
+Non-terminal review session expiry is recorded lazily when the session is read or mutated after its TTL. There is no background expiry worker.
+
+## Boundaries
+
+The active account is a read context only. It is not signing authorization, login, authentication for transactions, custody, permission for transactions, or proof of ownership. It stores at most one address per database file; setting a new active account replaces the previous one without revoking anything onchain.
+
+NDJSON event logs remain optional audit/debug logs. They are not the product activity source of truth. User-facing activity summaries read from SQLite. Event log write failures do not fail product session transitions or SQLite evidence writes.
+
+Session tokens, token hashes, and URL fragment tokens are never stored in SQLite. The activity-store evidence input types do not accept session token material, and review evidence JSON is checked with the same forbidden-field-name policy used for MCP output. Transaction bytes, signatures, serialized signing material, token-hash/session-token-like fields, seeds, mnemonics, and private-key-like field names are rejected before write. External proposal ingestion also rejects recognized Sui private-key strings, valid English BIP39 mnemonic phrases, obvious sensitive markers, and suspicious raw secret-like payloads before storing the sanitized requested intent. Generic asset metadata such as token symbols remains allowed.
+
+The local settings table is not a secret store. It stores only allowlisted local preferences such as the Sui mainnet gRPC and GraphQL endpoints. It must not store database paths, tokens, credentials, private keys, mnemonics, seeds, or arbitrary API keys. Environment overrides such as `SUI_GRPC_URL` and `SUI_GRAPHQL_URL` can temporarily supersede stored endpoints without mutating the database.
+
+Review intent capture follows one adapter convention: if an adapter wants the original requested intent materialized for activity queries, it must place that object at `ActionPlan.adapterData.requestedIntent`. The full `plan_json` remains the canonical action plan, and `intent_json` is only the query-friendly copy of that adapter-supplied intent.