@stelis/say-ur-intent 0.0.0

package/docs/SDK_API.md

@@ -0,0 +1,116 @@
+# SDK API Verification
+
+This document records the pinned SDK APIs used by the current runtime. The source of truth is the installed package source in `node_modules`, not memory or external summaries.
+
+## Package Versions
+
+- `@mysten/sui`: `2.16.2`
+- `@mysten/deepbook-v3`: `1.3.6`
+- `@mysten/dapp-kit-core`: `1.3.2`
+
+## Sui gRPC Client
+
+Verified from `node_modules/@mysten/sui/src/grpc/index.ts`, `client.ts`, `core.ts`, and `node_modules/@mysten/sui/src/client/types.ts`.
+
+- Import path: `@mysten/sui/grpc`
+- Client: `SuiGrpcClient`
+- Constructor input includes:
+  - `network`
+  - `baseUrl`
+  - optional `fetchInit`
+  - or custom `transport`
+- Runtime construction:
+
+```ts
+new SuiGrpcClient({
+  baseUrl: "https://fullnode.mainnet.sui.io:443",
+  network: "mainnet"
+});
+```
+
+Confirmed methods:
+
+| Method | Signature Source | Notes |
+| --- | --- | --- |
+| `client.core.getChainIdentifier()` | `GrpcCoreClient.getChainIdentifier(_options?)` | Returns `{ chainIdentifier: string }`. |
+| `client.core.listBalances(options)` | `GrpcCoreClient.listBalances(options)` | `options.owner` is required; `options.cursor` and `options.limit` are available. Returns `{ balances, hasNextPage, cursor }`. |
+| `client.core.getCoinMetadata(options)` | `GrpcCoreClient.getCoinMetadata(options)` | `options.coinType` is required. Returns `{ coinMetadata }`; metadata can be `null`. The gRPC implementation resolves type through MVR before calling `stateService.getCoinInfo`; the pinned gRPC implementation catches `getCoinInfo` failures and returns `coinMetadata: null`, so callers cannot distinguish those failures from missing metadata through this method alone. |
+| `client.core.simulateTransaction(options)` | `GrpcCoreClient.simulateTransaction(options)` | Accepts `transaction`, optional `include`, optional `checksEnabled`. |
+
+`SimulateTransactionOptions.checksEnabled` defaults to enabled and can be set to `false` for debug/read inspection. Read-only DeepBook SDK methods use simulation internally and must not be presented as signing readiness.
+
+For review-time transaction simulation, use the runtime gRPC `client.core.simulateTransaction(...)` path with validation checks enabled. The required first-route review include set is `effects`, `balanceChanges`, `objectTypes`, and `transaction`: those fields provide status, gas used, changed-object context, raw balance deltas, sender, gas config, inputs, and command shape. Missing required fields must fail closed; do not infer readiness from partial simulation data. Do not request `bcs` for product-facing or stored review evidence, because raw transaction bytes are not an MCP or review-app output. `commandResults` remains scoped to read-only DeepBook raw quote extraction and is not swap review simulation evidence. Failed simulations are blocked pre-signing review facts, not wallet rejection, transaction submission failure, or automatic transient retry evidence. A thrown simulation call is refreshable only when it is classified as a transport, RPC, timeout, or endpoint availability failure; malformed transaction material, request-shape bugs, incomplete SDK results, and adapter defects must remain blocked.
+
+## DeepBook Read Methods
+
+Verified from `node_modules/@mysten/deepbook-v3/src/client.ts` and `node_modules/@mysten/deepbook-v3/src/types/index.ts`.
+
+- Import path: `@mysten/deepbook-v3`
+- Client: `DeepBookClient`
+- Constructor requires:
+  - `client`
+  - `address`
+  - `network`
+- Constructor also accepts optional configured `balanceManagers`; Say Ur Intent uses this only to register a user-supplied `managerAddress` as an ephemeral SDK BalanceManager key for account-bound inventory detail reads.
+
+The `address` is used by the SDK as the transaction simulation sender for read queries. For sender-independent DeepBook orderbook, raw-quantity quote, and display-amount quote reads, Say Ur Intent supplies an internal mainnet placeholder address. This placeholder is not user identity and must not be represented as wallet authorization.
+
+Account-bound DeepBook reads, such as `read.summarize_deepbook_account_inventory`, use the active account address as the simulation sender. The product filters manager detail reads through on-chain `getBalanceManagerIds(owner)` discovery before calling account-bound detail methods; this is active read context, not signing authorization or custody.
+
+Confirmed methods:
+
+| Method | Return Type | Used For |
+| --- | --- | --- |
+| `midPrice(poolKey)` | `Promise<number>` | Orderbook context. |
+| `poolBookParams(poolKey)` | `Promise<PoolBookParams>` | Tick, lot, and min size context. |
+| `getLevel2TicksFromMid(poolKey, ticks)` | `Promise<Level2TicksFromMid>` | Bid/ask levels around mid price. |
+| `deepBook.getQuoteQuantityOut(poolKey, baseQuantity)` | Transaction builder thunk | Base-to-quote quantity quote. Say Ur Intent passes positive raw input quantities that fit the SDK `u64` argument and parses the simulated raw `u64` return values directly. |
+| `deepBook.getBaseQuantityOut(poolKey, quoteQuantity)` | Transaction builder thunk | Quote-to-base quantity quote. Say Ur Intent passes positive raw input quantities that fit the SDK `u64` argument and parses the simulated raw `u64` return values directly. |
+| `getBalanceManagerIds(owner)` | `Promise<string[]>` | Active-account BalanceManager discovery. |
+| `accountExists(poolKey, managerKey)` | `Promise<boolean>` | Gate before account-bound detail reads. |
+| `account(poolKey, managerKey)` | `Promise<AccountInfo>` | Display-like account ledger and rebate inventory. Not raw/signable quantity. |
+| `lockedBalance(poolKey, balanceManagerKey)` | `Promise<LockedBalances>` | Display-like balances tied to open orders. Not withdrawable/spendable readiness. |
+| `accountOpenOrders(poolKey, managerKey)` | `Promise<string[]>` | Open order ID inventory; Say Ur Intent caps returned IDs in its public response. |
+
+Relevant return shapes:
+
+```ts
+type PoolBookParams = {
+  tickSize: number;
+  lotSize: number;
+  minSize: number;
+};
+
+type Level2TicksFromMid = {
+  bid_prices: number[];
+  bid_quantities: number[];
+  ask_prices: number[];
+  ask_quantities: number[];
+};
+
+type QuoteQuantityOut = {
+  baseQuantity: number;
+  baseOut: number;
+  quoteOut: number;
+  deepRequired: number;
+};
+
+type BaseQuantityOut = {
+  quoteQuantity: number;
+  baseOut: number;
+  quoteOut: number;
+  deepRequired: number;
+};
+```
+
+The pinned SDK accepts `number | bigint` quote inputs. Its high-level quote query objects include an input echo field (`baseQuantity` or `quoteQuantity`) produced with `Number(inputRaw)`, plus display quote fields (`baseOut`, `quoteOut`, and `deepRequired`) produced after scalar division and `Number(...)` conversion. Say Ur Intent does not use those high-level query objects as the canonical quote source for adapter preparation. It uses the pinned SDK transaction builder quote functions, requests `client.core.simulateTransaction` command results, and parses raw `u64` return values. The simulated public Move entrypoint is `pool::get_quote_quantity_out` for base-to-quote reads and `pool::get_base_quantity_out` for quote-to-base reads; both delegate to `pool::get_quantity_out`, whose official Move source defines the return order as `base_quantity_out`, `quote_quantity_out`, and `deep_quantity_required`. Public `quote` fields are exact decimal display strings derived from those raw values through pinned DeepBook scalars; `rawQuote` carries the raw evidence. `read.quote_deepbook_action` marks the input as raw `u64`, while `read.quote_deepbook_display_amount` marks the input as a source display amount converted to raw `u64`. Raw quote evidence is not an effective price, price-impact calculation, quote-vs-mid slippage calculation, venue comparison, best-route claim, fiat cash-out estimate, external market lookup, USDC/USD peg assumption, P&L, cost basis, final min-out, signing data, or signing readiness. The account-bound DeepBook review may derive a fresh raw quote policy from this evidence and use that derived policy for local unsigned transaction material build, while keeping bytes internal and wallet signing blocked. When the digest commitment stage completes, it is derived from the locally stored transaction bytes through pinned SDK `Transaction.from(...).getDigest()` and remains an internal binding, not a public signing artifact.
+
+## Runtime Boundary
+
+- JSON-RPC client imports are not used.
+- Sui gRPC and GraphQL endpoints are resolved from local SQLite settings by default. `SUI_GRPC_URL` and `SUI_GRAPHQL_URL` are advanced temporary overrides and do not mutate stored settings.
+- Sui gRPC URLs must include an explicit port and no credentials, path, query string, or fragment.
+- Sui GraphQL URLs must use `https` and must not include credentials, query string, or fragment.
+- The gRPC endpoint is verified during runtime startup. The GraphQL endpoint is verified when saved, imported, or first used by Sui activity tools.
+- `fetchedAt` fields are ISO 8601 UTC strings produced by `new Date().toISOString()`.
+- Read-only tools may inspect mainnet state but must not create signable transaction material.

package/docs/SIGNABLE_ADAPTER_CONTRACT.md

@@ -0,0 +1,358 @@
+# Signable Adapter and PTB Visualization Contract
+
+This document defines the contract boundary for wallet-review adapters.
+It is a product and implementation contract, not a current feature announcement.
+
+The current release can build local unsigned transaction material for the
+account-bound DeepBook swap review stage and internally bind a Sui transaction
+digest to that stored material. The byte handoff to the same-machine browser
+is gated on recomputed-digest equality, and the review page offers
+user-controlled wallet signing with execution receipts recorded on the
+session. No MCP tool returns
+transaction bytes, signing data, signing readiness, executable transaction
+material, or payment execution readiness.
+
+The source-level schema for this contract lives in
+`src/core/action/signableAdapterContract.ts`.
+
+## Current Status
+
+The contract schema is implemented in TypeScript and Zod, and the runtime
+DeepBook account-bound swap review emits it. When the account-bound review
+completes every evidence stage (local unsigned transaction material, internal
+digest commitment, object ownership, quote/policy provenance, human-readable
+review facts, and review-time simulation), the review layer assembles those
+private artifacts into a schema-validated `WalletReviewAdapterContract` and
+records it on the public review state as `walletReviewAdapterContract` on a
+`ready_for_wallet_review` status. If any required evidence is
+missing or fails contract validation, no contract is emitted and the review
+stays blocked with `blockedReason: "wallet_review_contract_emit_missing"`.
+
+No MCP response or review UI response exposes executable transaction material.
+The emitted contract carries the Sui transaction digest as
+`transactionMaterialCommitment` (a hash only); raw transaction bytes stay
+inside the review-server session and leave it only through the digest-gated
+handoff endpoint for the same-machine browser. After the handoff gate, the
+same-machine browser page requests the user's wallet signature and submits the
+signed transaction; the contract layer itself never signs or executes.
+
+## Final Acceptance Gate
+
+This document defines a contract gate, not a current signing feature. Do not add
+new capability here ahead of a reviewed implementation.
+
+The gate binds three views of the action to one transaction commitment, so a
+user cannot sign something different from what they reviewed:
+
+- The commitment is a digest (hash) of the exact serialized transaction bytes
+  that will be signed, represented as the Sui transaction digest. The commitment
+  is a hash only; raw transaction bytes remain a prohibited output and must never
+  appear in MCP or review responses.
+- `humanReadableReview` must be derived from the transaction identified by that
+  commitment.
+- The review-time `simulation` must have been run against the transaction with
+  that same commitment.
+- Any bytes handed to the wallet must hash to that same commitment.
+
+The acceptance criterion is strict equality: review-commitment equals
+simulation-commitment equals handoff-commitment. If any is missing or differs,
+the contract is invalid and signing stays blocked.
+
+### Transaction byte lifecycle (closes the handoff loophole)
+
+The signable bytes must have exactly one origin and one handoff path, so an
+adapter cannot display a commitment while signing different bytes through a side
+channel:
+
+- Origin: the bytes are produced only inside Say Ur Intent's review layer (the
+  signable adapter), from material Say Ur Intent independently built or verified.
+  They are never accepted from an external MCP or AI-client proposal.
+- Storage: the bytes live only in the local review-server session keyed by
+  `reviewSessionId`. They never appear in an MCP tool response or in the
+  review-API JSON an AI client reads; those surfaces carry the commitment hash
+  only.
+- Handoff channel: the only path that may carry the bytes is the local
+  review-server to same-machine browser to wallet-adapter handoff for that
+  session. There is no other handoff path, and the MCP layer and AI client never
+  receive the bytes.
+- Bind at handoff: before the wallet is asked to sign, the handoff path must
+  recompute the digest of the exact bytes it is about to hand over and require it
+  to equal the commitment that `humanReadableReview` and `simulation` were bound
+  to. If they differ, or if any alternate or side handoff path is used, signing
+  is refused.
+
+Any design that exposes a commitment but routes the signed bytes through a
+different origin or channel violates this gate and is prohibited.
+
+One review session covers exactly one transaction. While a handoff is
+outstanding, the session is locked: state recomputes are refused until the
+wallet result is recorded, the user cancels the handoff, or the handed-off
+material expires (the lock then self-releases). A recorded `success` or
+`failure` execution result is final and deletes the stored material.
+
+DeepBook swap material is built with an explicit fee mode. When the account's
+DEEP balance covers the protocol fee, the swap quotes and builds in DEEP fee
+mode; otherwise it re-quotes through the protocol's input-fee dry run and
+builds with an explicit zero-DEEP coin so the taker fee is paid from the
+source coin at the protocol penalty. The selected fee mode is recorded as
+review evidence and shown as a check. Before building, the producer verifies
+the account holds the source amount plus the explicit gas budget and fails
+closed with the exact required and held amounts.
+
+This gate is enforced at the contract-schema layer. `walletReviewAdapterContractSchema`
+requires a `transactionMaterialCommitment` (the Sui transaction digest of the
+transaction that will be signed, validated with the pinned SDK source of truth
+`isValidTransactionDigest`; a digest only, never raw bytes) and binds
+`humanReadableReview.boundToCommitment` and `simulation.boundToCommitment` to it
+through a `superRefine` invariant (reusing the `requireEqual` cross-field helper)
+that rejects any contract whose three commitments are missing, malformed, or
+unequal (`src/core/action/signableAdapterContract.ts`,
+`test/signableAdapterContract.test.ts`).
+
+The runtime bind-at-handoff step is implemented at the session-store boundary:
+`prepareWalletHandoff` recomputes the digest of the exact stored bytes and
+refuses the handoff unless it equals the reviewed
+`transactionMaterialCommitment`. The handoff endpoint
+(`POST /api/review/:id/handoff`) is the only channel that carries the bytes,
+and it serves the same-machine browser only. After the gate passes, the
+review page requests the wallet signature; the signature, execution, and
+receipt stay user-controlled and never flow through the MCP layer.
+
+The current release builds local unsigned DeepBook swap transaction material
+inside account-bound review, binds a Sui transaction digest to the stored
+material, hands the digest-verified bytes to the same-machine browser, and
+lets the user sign and execute in their wallet with the receipt recorded on
+the review session. The MCP layer never requests signatures or executes.
+
+## Adapter Contract
+
+A wallet-review adapter that returns this contract must regenerate or
+independently verify action material inside Say Ur Intent before any wallet
+handoff exists. External MCP or AI-client proposals remain untrusted structured
+input and cannot become transaction-building authority.
+
+The adapter contract requires these fields:
+
+- `inputProvenance`: where the request came from, when it was captured, and why
+  it remains untrusted until the local review layer regenerates and verifies it.
+- `sourceOfTruth`: source metadata for pinned SDK registries, verified mainnet
+  onchain metadata, wallet reads, quote evidence, simulation, validated request
+  facts, or explicit user choices. A `sourceOfTruth` record is not itself a
+  value-bearing fact. It identifies where a typed evidence claim came from.
+- `evidenceClaims`: typed value-bearing claims for every safety-critical fact
+  used by the payload. Each claim has a `factKind`, a `sourceEvidenceId` pointing
+  to `sourceOfTruth[].id`, and the value fields required for that fact. The
+  schema validates the claim against the safety-critical fact matrix and then
+  validates that payload fields match their referenced claim values.
+- `rawQuantities`: raw integer strings plus normalized Sui coin type, verified
+  decimals, and unit source. `amountClaimId` must point to a
+  `raw_quantity_amount` claim whose role, raw amount, and normalized coin type
+  match the payload. Unit `unitClaimId` must point to a `unit_metadata` claim
+  whose decimals, normalized coin type, and metadata source match the payload.
+  Display amounts remain presentation-only.
+- `gas`: review-time simulation evidence for gas quantities or a concrete
+  unresolved reason. `gasBudgetRaw` and `gasUsedRaw` must point to
+  `raw_quantity_amount` claims with `gas_budget` and `gas_used` roles, the Sui
+  gas coin type, and raw MIST units. An unresolved gas status must point to a
+  `gas_unresolved_status` claim. Gas object ownership must point to
+  `object_ownership` claims whose ownership status is `owned_by_account`.
+- `expiry`: review-time expiry status. `current` and `expired` require
+  `checkedAt`, `expiresAt`, and `evidenceClaimId`; `current` requires
+  `expiresAt` after `checkedAt`, and `expired` requires `expiresAt` at or before
+  `checkedAt`. The referenced `expiry_status` claim must match the payload and
+  must reference a `sourceOfTruth` record with `checkedAt` and `expiresAt`.
+  `not_provided` and `not_applicable` must omit `expiresAt`, include
+  `evidenceClaimId` and `reason`, and reference an `expiry_status` claim backed
+  by `checkedAt` and `expiryStatus`.
+- `slippageOrMinOut`: quote-linked max slippage and minimum-output policy when
+  quote evidence is used. `quoteEvidenceClaimId` must point to a `quote_min_out`
+  claim whose `quoteEvidenceId` and `minOutRaw` match the payload.
+  `policySource: "user_explicit"` requires a separate `policyEvidenceClaimId`
+  pointing to a `slippage_policy` claim backed by `user_explicit_choice` fields
+  including `maxSlippageBps` and `userSelection`.
+  `policySource: "adapter_policy_from_quote_evidence"` requires
+  `policyEvidenceClaimId` pointing to a `slippage_policy` claim backed by quote
+  evidence fields including `maxSlippageBps` and `minOutRaw`. If `minOutRaw` or
+  `maxSlippageBps` appears in the payload, it must have the matching typed claim;
+  stale or missing status does not make an unclaimed scalar safe to use.
+  `minOutRaw` must also match a `rawQuantities[]` entry with role
+  `minimum_output` so the raw integer has normalized coin type and verified
+  decimals.
+- `objectOwnership`: account-bound object ownership or shared-object facts. Each
+  object must point to an `object_ownership` claim whose object id, owner account,
+  and ownership status match the payload.
+- `simulation`: `client.core.simulateTransaction` with validation checks enabled
+  and the required fields `effects`, `balanceChanges`, `objectTypes`, and
+  `transaction`. The simulation payload must point to a `simulation_result`
+  claim whose provider, status, required fields, missing fields, and failure
+  reason match the payload.
+- `humanReadableReview`: the fields a human must see before wallet
+  authorization, matching the review-model concepts already exposed for
+  non-signable proposal review.
+- `outputBoundary`: the MCP and review UI exposure limit. Human-readable review,
+  PTB visualization artifacts, diagnostics, and status checks are allowed.
+  The required prohibited set is executable transaction material, serialized
+  transaction material, wallet signature requests, private-key material, wallet
+  authorization, signing data, signing readiness, and payment execution
+  readiness. Each contract must include the whole prohibited set.
+
+## Safety-Critical Fact Matrix
+
+`SAFETY_CRITICAL_FACT_MATRIX` in `src/core/action/signableAdapterContract.ts`
+is the contract's validation source of truth.
+
+It defines the required source kind and source fields for these fact kinds:
+
+- `raw_quantity_amount`, keyed by role: input, expected output, minimum output,
+  gas budget, gas used, fee, and balance delta;
+- `unit_metadata`, keyed by metadata source;
+- `gas_unresolved_status`;
+- `expiry_status`, keyed by status;
+- `quote_min_out`;
+- `slippage_policy`, keyed by policy source;
+- `object_ownership`;
+- `simulation_result`.
+
+Payload fields do not cite `sourceOfTruth` records directly as proof. They cite
+typed evidence claims, and those claims cite `sourceOfTruth` records. The schema
+rejects payload values that do not match their typed claims.
+
+## Consumer Invariant Matrix
+
+`CONSUMER_INVARIANT_MATRIX` in
+`src/core/action/signableAdapterContract.ts` defines extra requirements for
+payload fields that consume typed claims. It is separate from
+`SAFETY_CRITICAL_FACT_MATRIX`.
+
+`SAFETY_CRITICAL_FACT_MATRIX` answers whether a typed claim has the required
+source kind and source fields. `CONSUMER_INVARIANT_MATRIX` answers whether that
+claim is valid for a specific payload use.
+
+Current consumer invariants are:
+
+- `gas.gasBudgetClaimId` must reference a `raw_quantity_amount` claim with role
+  `gas_budget`, matching raw amount, and Sui gas coin type. The raw unit is MIST.
+- `gas.gasUsedClaimId` must reference a `raw_quantity_amount` claim with role
+  `gas_used`, matching raw amount, and Sui gas coin type. The raw unit is MIST.
+- `gas.gasObjects[].ownershipClaimId` must reference an `object_ownership` claim
+  with matching object id, matching owner account, and
+  `ownership: "owned_by_account"`.
+
+The current contract does not prove that a gas object is a `Coin<SUI>` object
+type because the object-ownership claim does not carry object type evidence.
+An adapter must not use object ownership alone as gas coin type evidence.
+
+## PTB Visualization Artifact
+
+The PTB visualization contract is for explaining a locally generated
+transaction shape before wallet authorization. It is not wallet handoff.
+
+The artifact may contain:
+
+- `generatedAt`;
+- `source`, including adapter id, plan id when available, source kind, renderer
+  name, package name, and version;
+- Mermaid `flowchart` text;
+- diagnostics from the adapter, renderer, schema, or simulation;
+- `unsupportedUse`, including transaction-building input, wallet authorization,
+  signing data, signing readiness, payment execution readiness, and route
+  recommendation;
+- `executableMaterial.included: false`.
+
+The artifact must not contain executable transaction material. Mermaid text and
+diagnostic messages are screened for executable-material terms and long encoded
+payloads.
+
+## PTB Renderer Status
+
+The pinned renderer dependency is `@zktx.io/ptb-model@0.5.0`. The review layer
+converts the stored local transaction material into a Mermaid `flowchart`
+artifact with `rawTransactionToIR` and `transactionIRToMermaid`, only after the
+stored bytes are recomputed to match the bound transaction material commitment;
+a mismatch declines the artifact. The artifact passes
+`ptbVisualizationArtifactSchema` screening before exposure and accompanies the
+emitted wallet review contract as `reviewState.ptbVisualization`. PTB
+visualization stays visualization-only evidence: it is not a runtime
+transaction builder, not wallet handoff, and not a signing-readiness surface.
+
+## Adapter Registration And Stage Vocabulary
+
+Review adapters register through `ReviewAdapterDescriptor` entries in
+`src/adapters/reviewAdapters.ts` (`buildSupportedReviewAdapterDescriptors`).
+A descriptor supplies the adapter id, protocol, action kind, stage catalog id,
+and the evidence computer; action-plan factories live in the adapter module
+and are wired by the MCP layer. The platform keeps the
+safety gates non-delegable: the typed evidence claim matrices, the commitment
+equality gate, the adapter lifecycle validator registry
+(`src/adapters/adapterLifecycleValidators.ts`), and the digest-gated byte
+handoff all run outside adapter code. `src/core` contains no adapter imports;
+a source-policy test enforces that boundary.
+
+Stage vocabulary is a cross-adapter contract. Every stage catalog that reports
+public review evidence must use these stage ids for these concepts, because the
+core review-state schema binds public fields to them:
+
+- `transaction_material_build_or_verify`: local unsigned material exists.
+- `digest_commitment`: the Sui transaction digest is bound to the material.
+- `object_ownership`: object ownership evidence is verified.
+- `human_readable_review`: required before `reviewState.humanReadableReview`.
+- `review_time_simulation`: required before `reviewState.simulation`.
+
+Adapter acceptance gate: a new protocol enters as read-only tools or
+non-signable proposal review first. A signable adapter is accepted only when it
+produces every required evidence stage from independently built or verified
+material, passes `walletReviewAdapterContractSchema` without placeholder
+values, and fails closed when any evidence is missing. Protocol names stay out
+of public docs, runtime guidance, and MCP resources until a concrete
+implementation or support decision exists.
+
+## Verification
+
+Tests must keep this contract in place before any adapter can use it:
+
+- schema tests for required provenance, source-of-truth, raw quantity, gas,
+  expiry, slippage or minimum output, object ownership, simulation, and
+  human-readable review fields;
+- tests that reject duplicate `sourceOfTruth[].id` and `evidenceClaims[].id`
+  values;
+- tests that reject every payload claim reference that does not resolve to a
+  typed `evidenceClaims[].id`;
+- tests that reject every `evidenceClaims[].sourceEvidenceId` that does not
+  resolve to a `sourceOfTruth[].id`;
+- tests that reject safety-critical claims whose source references resolve to the
+  wrong source kind or to records missing the required fields for that claim;
+- tests that reject payload values whose raw amounts, decimals, gas quantities,
+  expiry values, minimum output, slippage policy, object ownership, or simulation
+  status do not match their typed evidence claims;
+- tests that reject metadata-only records as raw amount evidence and reject
+  user-explicit slippage policy claims without explicit user-choice evidence;
+- tests that reject raw signable quantity assets without normalized Sui coin
+  types;
+- tests that reject min-out or slippage scalar fields when they do not have typed
+  evidence claims;
+- tests that reject `minOutRaw` when it does not match a `rawQuantities[]` entry
+  with role `minimum_output`;
+- tests that require `gasBudgetRaw` and `gasUsedRaw` to use
+  `raw_quantity_amount` claims with gas roles, the Sui gas coin type, and raw
+  MIST units, or require unresolved gas status to use a `gas_unresolved_status`
+  claim;
+- tests that reject gas object references backed by object-ownership claims whose
+  ownership status is not `owned_by_account`;
+- tests that require every mandatory prohibited output boundary and every
+  mandatory PTB unsupported-use boundary;
+- tests that reject `current` or `expired` expiry status without timestamp
+  evidence, source evidence, matching source fields, and the required
+  `checkedAt`/`expiresAt` time relationship;
+- tests that reject `not_provided` or `not_applicable` expiry status when it
+  includes an `expiresAt` timestamp or omits the reason and source evidence for
+  why timestamp evidence is unavailable;
+- tests that require failed or unavailable simulation evidence to include a
+  concrete `failureReason`;
+- tests that reject display amounts, exponent notation, or floating-point values
+  as raw quantities;
+- tests that reject PTB visualization artifacts containing executable-material
+  terms or long encoded payloads;
+- MCP/review output tests using the shared forbidden-field-name policy;
+- documentation tests that keep PTB visualization described as visualization
+  only, not transaction material, signing readiness, or payment execution
+  readiness.

package/docs/TRANSACTION_ACTIVITY_LOG.md

@@ -0,0 +1,182 @@
+# Transaction Activity Log
+
+This document owns local transaction activity storage boundaries: what is stored, what is not stored, and which MCP tools can return live or stored activity facts.
+
+It does not define setup steps, tool schemas, complete-history support, P&L, route recommendations, transaction-building input, signing data, or signing readiness.
+
+Say Ur Intent stores two kinds of local activity evidence:
+
+- Say Ur Intent review evidence from local review sessions.
+- User-requested bounded Sui activity facts that were looked up through GraphQL and matched a known local wallet.
+
+It does not run a background indexer and does not claim complete wallet history.
+
+## Stored By Default
+
+When Say Ur Intent records an execution result for an account-bound review, the runtime stores a `review_executions` row. That row can include:
+
+- review session id
+- plan id
+- normalized account
+- execution status
+- transaction digest when available
+- explorer URL when available
+- failure reason when the result failed
+- full execution result JSON after forbidden-field validation
+- recorded and updated timestamps
+
+This is review evidence for a Say Ur Intent flow. It is not a complete wallet transaction history.
+
+The runtime also stores local review evidence that cannot be reconstructed from chain data:
+
+- review session header and full action plan JSON
+- materialized requested intent JSON when the adapter provides `ActionPlan.adapterData.requestedIntent`
+- append-only review state snapshots
+- append-only review lifecycle transitions
+
+Lifecycle transition reads mark repeated observations with no stored status change as `isNoOp`. These rows preserve audit detail without changing funnel progress counts.
+
+## Stored When Requested
+
+When the user requests a Sui transaction digest lookup or account activity scan, the runtime can store normalized external activity facts only if the transaction is tied to an address already present in the local `accounts` table.
+
+A returned scan row is tied to a known local account only when the sender or a returned balance-change owner matches that account.
+
+Other provider-returned rows can be used for the current response but are counted as skipped for storage.
+
+Stored scan rows include:
+
+- scan id
+- scan kind: `digest_lookup`, `account_scan`, or `function_scan`
+- known local account
+- relationship: `affected` or `sent`
+- input digest or bounded scan window
+- request and response cursor metadata
+- endpoint host and verified chain identifier
+- fetched timestamp
+- stored/skipped counts
+- `hasMore`, `windowComplete`, and incomplete reason such as `ordering_unverified`
+
+Stored transaction rows include:
+
+- known local account
+- digest
+- relationship
+- checkpoint when returned by the provider
+- timestamp when returned by the provider
+- status: `success`, `failure`, or `unknown`
+- known sender account id only when the sender is also a known local account
+- first and last scan ids
+- first and last fetched timestamps
+- normalized detail facts when returned by GraphQL:
+  - transaction kind
+  - capped Move call targets with package, module, and function
+  - raw coin balance changes in `amountRaw` signed integer strings, with the balance owner stored only when it is the known local account
+  - object changes with object id, change kind, and before/after object type when available
+  - event sequence, package, module, and event type, with the event sender stored only when it is the known local account
+  - gas cost summary raw integer string fields, including derived `netGasCostRaw`
+  - execution error message and structured abort location when available
+  - truncation flags for capped detail lists
+
+`function_scan` is internal provenance for sent-function scans.
+
+It is not a stored function-history query, a function index, or authority to filter stored summaries by function.
+
+Legacy rows stored before this provenance existed can remain `account_scan`. Say Ur Intent does not backfill them because the stored scan row does not contain the function target needed to identify them safely.
+
+Live scan and live-summary rows expose these fields for requested-account raw balance-change facts:
+
+- `requestedAccountTransactionFacts`;
+- `requestedAccount.coinFlows`;
+- `transactions[].requestedAccountEffect`.
+
+Use those fields for wallet-specific asset-flow answers.
+
+`requestedAccountTransactionFacts[]` is a flattened account-scoped row surface for AI client summaries.
+
+It repeats the row digest, status, and sender metadata.
+
+It carries account-scoped fields such as:
+
+- `accountBalanceChangeEvidence`;
+- `accountBalanceChangeAbsenceProven`;
+- `accountBalanceChangeInferencePolicy`;
+- `accountBalanceChanges`;
+- `accountCoinFlows`;
+- `accountEffectLimitations`.
+
+It also includes transaction-level `transactionContext` for calls, events, objects, gas, truncation, and protocol labels.
+
+Live scan and live-summary `transactionContext` intentionally omits transaction-wide balance-change aggregates. This prevents repeated ownerless raw balance-change facts from being mistaken for a requested wallet's balance movement.
+
+A row-level `requestedAccountEffect` has `scope: "requested_account"` plus `role`, `balanceChangeEvidence`, `accountBalanceChangeAbsenceProven`, `accountBalanceChangeInferencePolicy`, `coinFlows`, and `limitations` fields for that transaction.
+
+`incomplete_account_balance_changes` and `account_balance_changes_unavailable` are not zero-balance evidence.
+
+Only `accountBalanceChangeAbsenceProven: true` or `no_account_balance_changes_returned` with complete evidence means the returned details prove no requested-account balance changes in that row.
+
+`accountBalanceChangeInferencePolicy: "do_not_infer_from_transaction_context"` means transaction-level context, visible recipient patterns, current wallet balances, compact counts, or aggregate analysis must not be used to infer the requested account's amount.
+
+Activity `quantitySemantics` marks `amountRaw`, `increaseRaw`, `decreaseRaw`, and `netRaw` fields as raw integer facts that require verified decimals or a returned display amount before display conversion.
+
+If `requestedAccount.balanceChangeCompleteness` or a row-level `requestedAccountEffect.balanceChangeCompleteness` is `truncated` or `unavailable`, say the account-specific balance-change evidence is incomplete instead of presenting the returned rows as complete.
+
+Inspect responses and stored-summary rows can expose a derived `compact` view when full or stored details are available.
+
+Activity summary responses expose `transactionDetailAvailability` for the returned `transactions` rows. `transactions[].transactionContext`, `transactions[].compact`, and `transactions[].details` are listed in `userAnswerUse.answerFields` only when every returned transaction row has details. Mixed rows must be described from `transactionDetailAvailability` and row-specific fields, not as an all-row detail guarantee.
+
+`compact.factScope: "transaction"` and `compact.requestedAccountScoped: false` mean compact balance, object, event, and gas fields summarize the transaction, not the requested wallet.
+
+Repeated identical compact balance-change facts can be aggregated with `count`.
+
+`analysis.coinFlows` is a transaction/page aggregate over returned normalized facts, not wallet-specific evidence.
+
+Gas raw values are MIST.
+
+`compact.gasCost.display` and `analysis.gas.netGasCost.display`, when present, are SUI display facts derived with `@mysten/sui MIST_PER_SUI`.
+
+Protocol matches are computed from normalized detail facts at response time and can include `mvrName`/`packageSource` for package-derived evidence.
+
+They are transaction activity labels only, not stored protocol decoder output, wallet position inventory, P&L, route recommendation, transaction-building input, signing data, or signing readiness.
+
+Live and stored summary tools can also expose deterministic `analysis` over returned normalized facts.
+
+That analysis aggregates raw integer coin flows, gas totals, Move call targets, object/event counts, failure details, and protocol counts keyed by `protocolMatches[].protocolId`.
+
+It is not display conversion, P&L, position inventory, route quality, protocol support, transaction-building input, signing data, or signing readiness.
+
+Use `read.inspect_sui_transaction` when a user needs the full normalized facts for a digest.
+
+The runtime does not store non-known party account addresses inside persisted transaction rows or normalized detail facts. If a digest lookup or explicit-account scan is not related to a known local wallet, the result can be returned for the current request but is not persisted.
+
+## Not Stored
+
+This toolkit does not run automatic scans for any account.
+
+It does not store raw GraphQL payloads, transaction bytes, signatures, BCS payloads, private or session material, balance snapshots, price observations, complete gas history, abandoned-reason logs, quote logs, or protocol decoder outputs.
+
+Complete account transaction history is not a product surface of this data.
+
+AI clients may answer questions only from data the listed read tools return.
+
+`read.summarize_sui_activity_scan` summarizes a live bounded scan without full details or transaction-wide balance-change aggregates in row context.
+
+`read.scan_sui_function_activity` and `read.summarize_sui_function_activity_scan` reuse the same requested-account fact, transaction-context, analysis, and protocol label pipeline for transactions the selected account sent that called one full `package::module::function`.
+
+They do not create a function-specific stored history, global function index, affected-object history, or complete dApp history.
+
+`read.summarize_sui_account_activity` summarizes account-level stored normalized facts only.
+
+It can include rows originally observed by account scans, digest lookups, or sent-function scans, and the scan kind remains provenance rather than a user query filter.
+
+Provider retention and rate-limit behavior are endpoint/operator properties, not guarantees made by Say Ur Intent.
+
+Empty pages, bounded pages, and stored local summaries must not be treated as complete history.
+
+When normalized details are missing or capped, use `transactionDetailAvailability` and the returned digest metadata with `read.inspect_sui_transaction` instead of inventing missing fields.
+
+Inspect responses can include live GraphQL detail fields for the current response.
+
+Live scan and live-summary rows point to that digest path through `detailLookup` instead of returning full `details`.
+
+Stored summaries return sanitized normalized details only, omit non-known party account addresses, and may include `lastScanIncompleteReason` when the last scan that touched a row had incomplete or unverified coverage.