@eco-incorp/sauce 0.99.4 → 0.99.6

package/docs/guides/protocols-and-tokens.md

@@ -2,7 +2,8 @@
 
 [Documentation](../README.md) · [Quick start](quick-start.md) · [Coverage](../api/coverage.md)
 
-Within an EVM route, token symbols and protocol names resolve against the destination chain:
+Inside an EVM route body, token symbols and protocol contracts are names the compiler resolves
+against the destination chain — so a program reads like the operation it performs:
 
 ```js
 USDC.approve(Uniswap.UniversalRouter, 1_000_000n);
@@ -42,7 +43,9 @@ const baseTokens = routes.knownTokenSymbols(routes.chain("base").chain);
 console.log(protocol, descriptors.length, router.available, baseTokens);
 ```
 
-Contract accessors expose `address`, `available`, `chains`, `abi`, `methods`, and `coverage`. A namespace's presence does not establish deployment on every chain. A call to a registered contract with no deployment on the selected chain fails during construction or compilation.
+Contract accessors expose `address`, `available`, `chains`, `abi`, `methods` and `coverage`. A name
+existing does not mean the contract is deployed on your chain — calling one that is not fails when
+you build or compile, which is the point at which you can still do something about it.
 
 Versioned names are explicit: `UniswapV2.Factory` and `UniswapV3.Factory` select different descriptors. A family alias only resolves a contract name when it identifies one descriptor; `Uniswap.Factory` is ambiguous and fails. A protocol with a single default contract also permits the shorter `Protocol.method(...)` form.
 
@@ -61,7 +64,27 @@ For a token absent from the registry, use `Token(address)`:
 Token(0x1111111111111111111111111111111111111111n).approve(Uniswap.UniversalRouter, 1_000_000n);
 ```
 
-Replace that illustrative address with your ERC-20. The wrapper accepts a literal, a local variable, or a compile-time define. The token member syntax supports `transfer`, `approve`, and `balanceOf`. Use an explicit ABI binding for additional ERC-20 methods. The shorthand `self.USDC` reads the executing contract's balance; `USDC.balanceOf(self)` makes the same intent explicit. `self` refers to the executing contract, which is the Pot in the EVM route path.
+Replace that illustrative address with your ERC-20. The wrapper accepts a literal, a local variable, or a compile-time define. It can also be bound once and called, `const t = Token(address); t.approve(spender, amount);`, as long as `t` is never reassigned or used other than as `t.<method>(...)`. The token member syntax supports `transfer`, `approve`, `transferFrom`, and `balanceOf`. Use an explicit ABI binding for additional ERC-20 methods. The shorthand `self.USDC` reads the executing contract's balance; `USDC.balanceOf(self)` makes the same intent explicit. `self` refers to the executing contract, which is the Pot in the EVM route path.
+
+### Writes follow SafeERC20
+
+`transfer`, `approve` and `transferFrom` have OpenZeppelin `SafeERC20` semantics however you spell
+them: `USDC.transfer(to, amount)`, `Token(address).transfer(to, amount)`, a bound `t.transfer(...)`,
+or the `@sauce/token` function `transfer(token, to, amount)`. The first three compile to exactly the
+fourth, so they are one implementation, not four. A token that returns nothing, such as USDT, is
+accepted when it has code. A `false` return, a malformed return, or an address with no code reverts
+the program. `approve` resets a non-zero allowance to zero before setting the new one, as
+`forceApprove` does, because USDT refuses to change one non-zero allowance to another.
+
+A write returns nothing: it succeeds or reverts the program, so there is no `bool` to read, and
+`const ok = USDC.transfer(...)` does not compile. Each write lowers to `@sauce/token` imported under
+a reserved `__sauce_<method>` name, so a program's own `transfer` or `approve` function keeps its
+name.
+
+An explicit `IERC20.at(address).transfer(...)`, with the ABI imported yourself, is **not** SafeERC20.
+It is the raw ABI call: it decodes the declared `bool`, so it reverts on a token that returns nothing
+and accepts one that returns `false`. Use it only when that is the behavior you want; otherwise use
+one of the spellings above.
 
 Use `tokenDefines` on an intent to add or override symbols, or `tokens` on `compileSauceRoute`'s compile options. Overrides merge per symbol with the registry. These maps contain **addresses**; `IntentOptions.tokens` instead declares the **token amounts** a solver must deliver for the route.
 
@@ -86,11 +109,16 @@ Custom symbol names work in source strings. The package's generated TypeScript d
 
 ## Route source and host JavaScript
 
-Importing the package installs real chain globals such as `Base` and `Solana`, plus the host `Token` builder. The package also supplies TypeScript declarations for bare route names such as `USDC` and `Uniswap`. Those bare names are **route syntax**: there is no host JavaScript `USDC` or `Uniswap` object to execute.
+Two different mechanisms share the look of a bare name, and the difference is what you import.
+
+Chain accessors such as `Base` and `Solana`, the `chain(ref)` front door, and the host `Token` builder are **named exports**: `import { Base, Solana, Token } from "@eco-incorp/sauce"`. They are ordinary JavaScript values, and importing the package installs nothing on `globalThis`.
+
+Bare route names such as `USDC` and `Uniswap` are **route syntax**, resolved by the compiler against the destination chain. The package supplies TypeScript declarations for them so a typed callback checks, but there is no host JavaScript `USDC` or `Uniswap` object to import or execute.
 
-Use a side-effect import, `import "@eco-incorp/sauce"`, when relying on installed globals. A type-only import does not install them, and TypeScript can erase a named import used only for types.
+A host that wants the chain names as runtime globals anyway can opt in with `installRouteGlobals()`, which defines them on `globalThis` (or any target you pass) and never overwrites a name already there. It installs values only; declare the names yourself.
 
-Outside a route, `Base.UniswapV4.UniversalRouter` or `contracts.on("base").UniswapV4.UniversalRouter` is a real host accessor. Its methods return inert `ContractCall` objects. A call can provide encoded `data`, `.toCall()` for `{ target, data, value }`, or `.toSauceScript()` for source and import paths. Host accessor methods currently have the static type `unknown`; use an explicit signature when invoking one in TypeScript:
+Outside a route, `Base.UniswapV4.UniversalRouter` or `contracts.on("base").UniswapV4.UniversalRouter` is a real host accessor. Its methods return inert `ContractCall` objects. A call can provide encoded `data`, `.toCall()` for `{ target, data, value }`, or `.toSauceScript()` for source and import paths. A host accessor's methods are typed `unknown`, because their signatures come from an ABI the type
+system has not seen. Narrow one before calling it:
 
 ```ts
 import { contracts } from "@eco-incorp/sauce";
@@ -103,13 +131,13 @@ const execute = router.execute as (
 ) => contracts.ContractCall;
 ```
 
-That declaration does not build or send a swap. Supply valid Universal Router commands before calling it. For ordinary ERC-20 operations from host code, the typed `token.Token.transfer({ ... })` and `.approve({ ... })` builders are usually more convenient; see [builders and actions](builders-and-actions.md).
+That declaration does not build or send a swap. Supply valid Universal Router commands before calling it. For ordinary ERC-20 operations from host code, the typed `token.Token.transfer({ ... })` and `.approve({ ... })` builders are usually more convenient; see [builders](builders-and-actions.md).
 
 ## Chain selection and ABI bindings
 
 A bare protocol reference uses the enclosing destination. A qualified reference such as `Ethereum.UniswapV4.UniversalRouter` selects an address from Ethereum's registry. It does **not** move execution to Ethereum: the resulting call still executes on the enclosing route's chain. Use separate intents and [nesting](nested-intents.md) for cross-chain execution. Set `compile.accessors.chainScope` to restrict explicitly qualified chain names when needed.
 
-Route rewriting rejects missing methods, ambiguous aliases, missing deployments, and descriptors marked with widened ABI types. A widened ABI can produce a selector different from the deployed contract. Inspect `coverage` and use the exact ABI for that deployment; opting past the check does not repair the ABI.
+Route rewriting rejects missing methods, ambiguous aliases and missing deployments. Every descriptor declares its contract's deployed ABI types, so the selectors it computes are the ones the deployed contract dispatches.
 
 To call a contract outside the descriptor registry, supply an ABI binding through `compile.contracts` or a resolved ABI import, then call `Binding.at(address).method(...)` in source. See [compiler integration](../api/compiler.md). Host `.at(address)` rebinding and SauceScript ABI `.at(address)` are separate APIs; the global protocol rewrite does not provide arbitrary `.at(...)` chains.
 

package/docs/guides/quick-start.md

@@ -1,30 +1,27 @@
 # Quick start
 
-[Documentation](../README.md) · [Protocols and tokens](protocols-and-tokens.md) · [Intents](intents.md)
-
-Use Node.js 24 or newer and install the single public package:
+[Documentation](../README.md) · [Protocols and tokens](protocols-and-tokens.md) · [Create an intent](intents.md)
 
 ```sh
 pnpm add @eco-incorp/sauce
 ```
 
-The Sauce compiler is a dependency of that package. You do not need a compiler checkout or a separate compiler install.
+Node.js **24 or newer**. The SauceScript compiler is a dependency of this package — there is nothing
+else to install and no compiler checkout to keep in sync.
 
-## Compile your first intent
+## Build your first intent
 
-This complete TypeScript example builds an approval intent offline. Addresses and the fee are fixtures; the zero reward demonstrates construction only. Before submission, [read the current Kitchen fee and prepare an Executor-owned Pot](intents.md#prepare-the-destination-pot).
+This is a complete program. It builds an Eco intent offline: the addresses and the fee are fixtures
+and nothing is sent to a chain.
 
 ```ts
-import "@eco-incorp/sauce";
+import { Base } from "@eco-incorp/sauce";
 import type { routes } from "@eco-incorp/sauce";
 
-const executionFee = 1_000n; // Fixture: read the destination Kitchen's executionFee() before use.
+const executionFee = 1_000n; // Read the destination Kitchen's executionFee() before a real run.
 const options: routes.IntentOptions = {
-  execution: {
-    pot: "0x1111111111111111111111111111111111111111",
-    engine: "0x2222222222222222222222222222222222222222",
-    value: executionFee,
-  },
+  // The Pot and engine are derived. The Pot must exist before fulfilment; the solver deploys it.
+  execution: { value: executionFee },
   nativeAmount: executionFee,
   portal: "0x3333333333333333333333333333333333333333",
   deadline: 2_000_000_000n,
@@ -43,22 +40,54 @@ const built = Base(() => {
 console.log(built.hash().intentHash);
 ```
 
-Importing the root package installs `Base` and the other chain globals. Inside the callback, the SDK resolves `USDC` and `Uniswap.UniversalRouter` for Base, compiles the body with Sauce, and encodes a Pot `cook(engine, program)` call. `.reward(...)` completes the Eco intent. Nothing is submitted to a chain.
+`Base` names the **destination**, the chain the program runs on; `.reward(...)` names the
+**source**, where the reward is escrowed. That one expression does what an intent otherwise takes
+by hand:
+
+- looks up USDC and the Universal Router on Base, and binds the ERC-20 ABI;
+- compiles the body, so there is no contract to write or deploy;
+- derives the Pot and engine, and encodes the `cook(engine, program)` call on that Pot — the shared
+  one the solver deploys for that Portal;
+- assembles the route and reward, which is all `built.hash()` and the source Portal requests need.
+
+What stays yours: the deadlines, the creator and prover, the Kitchen fee, and a reward that pays a
+solver to fill the intent. The SDK sends nothing, and it does not price the reward.
+
+## The three things that trip people up
 
-For execution, deploy the Pot with the destination `Portal.executor()` as owner and pay the current Kitchen fee on every cook. [Intent setup](intents.md#prepare-the-destination-pot) shows the reads and deployment call. Fund and empty that shared Pot within the fulfillment.
+**The callback is source, not a function.** It is read with `Function.prototype.toString()`, parsed
+and compiled. It never runs as JavaScript, so it captures nothing: a surrounding `const amount` is
+invisible inside it. Pass application values through `defines`, or write the body as a string. If
+your bundler rewrites function bodies, use a string or a source file.
 
-`USDC` and protocol names have generated TypeScript declarations but are source syntax, not JavaScript clients. The router is registered as `UniswapV4.UniversalRouter`, with `Uniswap.UniversalRouter` as a family alias. `UniswapV3.UniversalRouter` is not a registered name. See [coverage](../api/coverage.md) for which protocols expose these namespaces.
+**`USDC` and `Uniswap` are not imports.** They are program syntax the compiler resolves against the
+destination chain. The package ships TypeScript declarations so a typed body checks, but there is no
+JavaScript object to import. `Base`, by contrast, _is_ a named export. The registered spelling of the
+router is `UniswapV4.UniversalRouter`, with `Uniswap.UniversalRouter` as an unambiguous family alias;
+`UniswapV3.UniversalRouter` does not exist. [Coverage](../api/coverage.md) lists what is registered.
 
-The callback captures no outer variables. Pass dynamic scalars through `defines`, or use explicit source strings; see the complete [transfer example](../examples/first-intent.ts). Callbacks must remain recognizable synchronous source after your build tooling transforms them.
+**The Pot is not yours alone.** For a Portal-driven intent the Pot's owner is the destination
+`Portal.executor()`, which every solver can drive. The SDK derives that Pot, so the example names
+none; the solver deploys it before the intent is fulfilled. Deliver assets into it, use them, and
+take the remainder out inside the same fulfillment. Every cook also pays the Kitchen's current fee in native value.
+[The destination Pot](intents.md#the-destination-pot) covers deployment and overrides.
 
 ## Deliver assets and fund the reward
 
-In a transfer intent, the destination assets and source reward are separate. Destination `tokens` reach the Portal Executor. Add a transfer precall to deliver tokens into the Pot before Sauce spends them. Source reward tokens are approved to the source Portal and escrowed through its funding call.
+The destination assets and the source reward are separate things. Destination `tokens` arrive at the
+Portal's Executor, so a program that spends them needs a transfer precall moving them into the Pot
+first. Source reward tokens are approved to the source Portal, which escrows them in the intent vault.
 
-The [first-intent.ts example](../examples/first-intent.ts) constructs both sides and returns source transaction requests. Read [creating intents](intents.md) before submitting those requests, and [nested intents](nested-intents.md) to compose subsequent routes.
+[first-intent.ts](../examples/first-intent.ts) builds both sides and returns the source transaction
+requests. Read [create an intent](intents.md) before submitting them, and
+[nested intents](nested-intents.md) to chain a second execution onto the first.
 
-## Compile a standalone program
+## Compile without an intent
 
-Use `@eco-incorp/sauce/compiler` when you need raw bytecode, entry schemas, or an SVM account manifest. It exposes the published Rust/Wasm compiler through `compile(options)`; it does not install SDK protocol namespaces into arbitrary compiler input.
+Reach for `@eco-incorp/sauce/compiler` when you want raw bytecode, runtime entry arguments or a
+Solana account manifest — a reusable program you supply values to at execution time rather than one
+specialised at compile time.
 
-The [compiler example](../examples/compile-program.ts) compiles a typed SauceScript entry point and appends compact arguments. [Compiling](compiling.md) explains module resolution and the distinction between raw compiler output and the route wrapper.
+[compile-program.ts](../examples/compile-program.ts) compiles a typed entry point and appends compact
+arguments. [Compiling programs](compiling.md) explains module resolution and how the raw compiler
+differs from the route wrapper.

package/docs/guides/solana.md

@@ -2,9 +2,9 @@
 
 [Documentation](../README.md) · [Compiler](../api/compiler.md) · [Coverage](../api/coverage.md)
 
-Solana programs use the `svm` compiler target, explicit account parameters, and a Kitchen that invokes the engine. EVM token/protocol member rewrites such as `USDC.transfer(...)` do not apply to SVM routes.
+Solana execution differs from EVM in one structural way, and everything on this page follows from it: **a Solana program must declare every account it touches, up front.** Those declarations are `Account` parameters on `main`, and the compiler returns them as an account manifest you resolve to real addresses before sending anything.
 
-Use `@eco-incorp/sauce/compiler` to retain the compiler's account manifest. `routes.compileSauceRoute()` returns execution calls and a `compiled.bytecode` segment list, but does not expose that manifest; applications resolving account slots should use the direct compiler result.
+Two consequences. The EVM name rewrites (`USDC.transfer(...)`, protocol members) do not apply here — there is no address to fold in without an account slot to put it in. And you want `@eco-incorp/sauce/compiler` directly: `routes.compileSauceRoute()` returns calls and bytecode but drops the manifest, which is the part you need.
 
 ## Compile an SPL transfer
 
@@ -42,9 +42,9 @@ The account references are names, not addresses. `manifest.accounts` records the
 
 Use `v12SvmEngineProgramId()` and `v12SvmKitchenProgramId()` from
 `@eco-incorp/sauce/deployments` for the released program identities, and confirm
-they are deployed on your cluster. The older `v12SvmProgramId` constant identifies
-a legacy engine. The client derives a Pot owned by its `payer` signer; select it
-with `potSalt` when configuring the client.
+they are deployed on your cluster. `v12SvmProgramId` names an earlier engine
+generation, not these. The client derives a Pot owned by its `payer` signer;
+choose it with `potSalt` when you configure the client.
 
 ```ts
 import {
@@ -71,14 +71,12 @@ After successful simulation, `client.execute(bytecode, manifest, resolution, { c
 
 ### Select the released programs and quote the fee
 
-The pinned SVM engine **1.2.0** is `HB8b1oD5PB2ptkLH6EV56Rr9RHevutEfvG2YdA7an6rK`;
-Kitchen **1.0.0** is `SauceYLdWyabKFwtevSAgsSDoMjCoTKtx1HTb63eJot`.
-These are release addresses; confirm deployment on your cluster before use.
-Engine 1.2.0 adds a code-hash-pinned staged variant of the direct paid calls introduced
-in 1.1.0. The SDK clients use Kitchen-mediated cooks;
-builders for the direct paid instructions are not yet exposed.
-Use the deployment helpers and read the Kitchen's fee configuration on the selected
-cluster. This example checks a caller-selected lamport budget before signing:
+Read the program ids from the deployment helpers rather than pasting them, and
+confirm each is deployed on the cluster you are targeting. The SDK's clients cook
+through the Kitchen; the engine's direct paid instructions have no builder here.
+
+Every cook pays the Kitchen's fee in lamports, and the fee is read from chain, not
+assumed. This example quotes it and refuses to sign past a budget the caller set:
 
 ```ts
 import { createHash } from "node:crypto";
@@ -145,38 +143,38 @@ Staging belongs to the Kitchen. There is no `client.stageBuffer()` convenience m
 
 The low-level instruction builders return instructions; the application groups, signs, submits, and confirms them. The two Kitchen cook paths require `buildHeapFramePrepend()` when assembling transactions yourself. A staged client's first argument is the **code-buffer metadata address**; it derives the associated code account.
 
-`buildCookFromAccountInstruction` supports a `pin` that the Kitchen checks at execution. The client's `expectedSha256` option is currently rejected; it is not a supported substitute for that low-level `pin`. A finalized buffer's digest and an execution-time caller-selected digest are different guarantees.
+`buildCookFromAccountInstruction` takes a `pin` the Kitchen checks at execution time. The client's `expectedSha256` option is rejected — it is not a substitute for that pin. The digest checked when a buffer is finalized and a digest chosen by a caller at execution are different guarantees about different moments; read both before relying on either.
 
 ## SVM destinations in Eco intents
 
-**The SDK's SVM route helpers are incompatible with the released gated engine.**
-For an SVM destination, `Solana(body, { execution, ... }).reward(...)`,
-`routes.compileSauceRoute()`, `buildSauceSvmCall()`, and `buildSauceSvmCalls()` emit
-a legacy `execute_from_account` instruction containing only its 8-byte
-discriminator. Engine 1.2.0 still requires another 65 bytes of Pot derivation material
-and a trailing Pot signer supplied by the Kitchen.
-
-The [SVM Portal fulfillment implementation](https://github.com/eco/eco-routes-svm/blob/5e544b72d368d9d1f0ee5269e2a1a5d2a9f8c2f2/programs/portal/src/instructions/fulfill.rs#L139-L192)
-forwards the route's instruction bytes to its target unchanged. It signs for its
-Executor PDA; it does not construct a Kitchen call or sign for a Sauce Pot.
-Changing only the helper's engine program ID therefore does not make these routes
-executable. Do not distribute them as executable intents against the pinned release.
-
-A Kitchen-targeted Portal integration needs separately constructed cook data and
-accounts, including the owner signature, Pot, fee configuration and payer, engine,
-and staged metadata/code where applicable. The SDK does not currently build or
-validate that complete integration. For standalone execution, use the client or
-Kitchen instruction builders described above.
-
-The legacy route's `execution.code` means the finalized **code account**, not its
-metadata address. The helper neither stages nor checks that code against its newly
-compiled bytes, and it drops the compiler account manifest. Keep the direct
-compilation result when inspecting historical routes. EVM-source Portal helpers
-can encode an SVM destination; they do not provide Solana-origin submission.
+**Build Solana execution with the Kitchen client, not the SVM route helpers.**
+
+`Solana(body, { execution, ... }).reward(...)`, `routes.compileSauceRoute()`,
+`buildSauceSvmCall()` and `buildSauceSvmCalls()` emit an `execute_from_account`
+instruction carrying only its 8-byte discriminator. The engine needs 65 further
+bytes of Pot derivation material and a trailing Pot signer that the Kitchen
+supplies, so that instruction is not one it will run — and pointing the helper at
+a different engine id does not add the missing bytes.
+
+The [SVM Portal's fulfillment](https://github.com/eco/eco-routes-svm/blob/5e544b72d368d9d1f0ee5269e2a1a5d2a9f8c2f2/programs/portal/src/instructions/fulfill.rs#L139-L192)
+forwards a route's instruction bytes to their target unchanged and signs for its
+own Executor PDA. It does not assemble a Kitchen call or sign for a Sauce Pot.
+A Portal integration that reaches the Kitchen therefore needs cook data and
+accounts built separately — the owner signature, the Pot, the fee configuration
+and payer, the engine, and staged metadata and code where they apply. That
+assembly is not in this package.
+
+One detail worth knowing if you are reading routes somebody already built:
+`execution.code` there means the finalized **code account**, not its metadata
+address, and the helper neither stages that code nor checks it against the bytes
+it just compiled. Keep the direct compilation result when you inspect one.
+
+The EVM-source Portal helpers can encode a Solana destination perfectly well.
+That is about encoding, not about submitting from Solana.
 
 ## Venue accessors
 
-The `Solana` global includes the venues registered for runtime access. A venue accessor exposes a program ID, pool configuration loading, quote-source generation, swap CPI construction, and a TypeScript reference quote:
+The `Solana` accessor, imported from the package root, includes the venues registered for runtime access. A venue accessor exposes a program ID, pool configuration loading, quote-source generation, swap CPI construction, and a TypeScript reference quote:
 
 ```ts
 import { venue } from "@eco-incorp/sauce/svm";
@@ -195,6 +193,6 @@ export async function buildRaydiumSwap(
 }
 ```
 
-`Solana.RaydiumCpSwap` exposes the same accessor when globals are installed. `poolConfig` uses the account loader you supply; it does not create an RPC client or discover pools. `quoteSource` returns SauceScript source, and `.swap` returns CPI data plus account references, not a transaction.
+`Solana.RaydiumCpSwap` exposes the same accessor after `import { Solana } from "@eco-incorp/sauce"`. `poolConfig` uses the account loader you supply; it does not create an RPC client or discover pools. `quoteSource` returns SauceScript source, and `.swap` returns CPI data plus account references, not a transaction.
 
 Venue swap builders use a venue-level minimum output of one; the composed program must enforce the user's actual minimum with a post-swap output balance delta. Runtime accessors cover the registered venue set. Other adapters exported from `/svm` do not automatically appear as `Solana.<Venue>`; consult [coverage](../api/coverage.md).

package/docs/guides/verification.md

@@ -2,23 +2,28 @@
 
 [Documentation](../README.md) · [Intents](intents.md) · [Compiler API](../api/compiler.md)
 
-The SDK verifies its canonical settlement programs on EVM and SVM. These helpers
-answer which settlement logic and parameters a payload contains. Applications
-still check the destination, execution target, account identities, and remaining
-intent calls against the operation they intend to authorize.
+Somebody hands you an intent and says it settles a swap to your address. These helpers answer one
+question about it: **is the program inside really the settlement program, and with what parameters?**
 
-| Surface                        | Mechanism                                                                                          | Environment                                                            |
-| ------------------------------ | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| `@eco-incorp/sauce/verify`     | Validate the EVM program hash and decode its canonical runtime argument tail                       | Node, browsers, and edge runtimes; depends on `viem`, not the compiler |
-| `@eco-incorp/sauce/svm/verify` | Recompile SVM settlement with expected parameters, compare bytecode, and inspect attached accounts | Node; loads the compiler                                               |
+That is a narrower question than "is this intent safe to sign", and the gap matters. A genuine
+settlement can sit next to calls that are not, on a chain you did not expect, aimed at a Pot you do
+not control. Verification identifies the program and decodes its arguments. The destination, the
+execution target, the account identities and every other call in the intent remain yours to check.
+
+| Surface                        | Mechanism                                                                                          | Environment                                                                |
+| ------------------------------ | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `@eco-incorp/sauce/verify`     | Validate the EVM program hash and decode its canonical runtime argument tail                       | Node, browsers, and edge runtimes; depends on `viem`, not the compiler     |
+| `@eco-incorp/sauce/svm/verify` | Recompile SVM settlement with expected parameters, compare bytecode, and inspect attached accounts | Node and browsers; loads the compiler (`await ready()` first in a browser) |
 
 ## Settlement behavior
 
-The EVM recipe sweeps the Pot's entire current balance of every listed token to
-one recipient. It checks `minOut` against the balance of `tokens[0]` before the
-first transfer; `minOut: 0n` disables that floor. Existing or donated balances
-count toward the floor and are swept as well. The floor is a balance check, not a
-measurement of the amount produced by an earlier swap.
+The EVM recipe sweeps the Pot's **entire current balance** of every listed token to one recipient.
+Before the first transfer it checks `minOut` against the balance of `tokens[0]`; `minOut: 0n` turns
+that floor off.
+
+Read "current balance" literally. A balance that was already there, or that somebody donated, counts
+toward the floor and is swept along with everything else. The floor tells you what the Pot holds, not
+what the swap before it produced.
 
 The SVM recipe applies the same pattern to escrow token accounts. It takes an
 escrow count and compile-time `minOut`/`splCount`, then attaches token programs,
@@ -49,12 +54,17 @@ console.log(settlement.tokens, settlement.minOut, settlement.recipient);
 console.log(settlement.floorToken, settlement.programHash);
 ```
 
-`validateSettleProgram()` checks the full program hash and the argument encoding.
-The current `SETTLE_WIRE` pin records compiler **2.3.0** and a **356-byte** program.
-Payloads produced before that recompile are 362 bytes under a different hash; verify them by
-passing their historical `{ hash, bytes: 362 }` pin to `validateSettleProgram`.
-Import `SETTLE_WIRE` when code needs those values; avoid copying them into a
-second constant table.
+`validateSettleProgram()` checks the whole program hash and the argument encoding. The pin it checks
+against is `SETTLE_WIRE` — a hash and a byte length, exported so your code can import them instead of
+keeping a second copy that will drift.
+
+Each transfer in the sweep follows OpenZeppelin `SafeERC20`: a token that returns nothing from
+`transfer` (USDT) is swept like any other, while a token that returns `false` or anything else that
+does not decode as a word equal to `1`, a token address with no code, or a reverting transfer reverts
+the whole sweep.
+
+A payload built against an earlier compiler has a different hash and length. To accept one, pass its
+`{ hash, bytes }` record explicitly; see [pins](#compiler-upgrades-and-historical-pins) below.
 
 The tail contains three 32-byte head words—token-array offset, minimum output,
 recipient—followed by the token count and token addresses in source order. The
@@ -77,10 +87,10 @@ existing settlement decoder.
 | `bestEffortDecode(parse)`                                 | Best-effort inspection or `null` when reporting values would be misleading                |
 | `encodeSettleProgram(tokens, minOut, recipient, program)` | Canonical payload construction                                                            |
 
-An arbitrary prefix of the expected length can pass structural decoding. Only a
-hash-pinned validation establishes that it contains the recognized settlement
-program. Validation failures use `SettleDecodeError.code`, including
-`PROGRAM_HASH`, `TOKENS_OFFSET`, `DIRTY_ADDRESS_WORD`, and `ARGS_OVERLONG`.
+Reach for `validateSettleProgram` unless you have a reason not to. Structural decoding will happily
+accept any bytes of the right length — only the hash check establishes that what you have is the
+settlement program. Failures carry a `SettleDecodeError.code` such as `PROGRAM_HASH`,
+`TOKENS_OFFSET`, `DIRTY_ADDRESS_WORD` or `ARGS_OVERLONG`.
 
 ### Extract a settlement from an intent
 
@@ -132,16 +142,45 @@ engine it names.
 program with a different length. Passing an empty list accepts no program; it
 does not fall back to the default pin.
 
-Compiler upgrades can change program bytes. When upgrading the SDK or compiler,
-check which program versions your application produces and accepts. Import the
-SDK's settlement pins rather than copying their values. Keep historical pins only
-for program versions your application explicitly accepts.
+Programs from earlier releases, before the sweep followed `SafeERC20`:
+
+| Released in     | `bytes` | `hash`                                                               |
+| --------------- | ------- | -------------------------------------------------------------------- |
+| 0.99.2 – 0.99.4 | 356     | `0xf9fffd262b32ad0cb07f2748f813626363497e09e4f4da134bed1b8da0c5d5fe` |
+| 0.99.0 – 0.99.1 | 362     | `0x2da5c63da0ed3e934f4bb09985a38723de1f2a8e9a9a97ef3993e526cb649d11` |
+
+An explicit list replaces the default, so include the current pin —
+`{ hash: SETTLE_WIRE.PROGRAM_HASH, bytes: SETTLE_WIRE.PROGRAM_BYTES }` — alongside the historical
+ones you accept.
+
+A compiler change can change program bytes without changing a line of the recipe. So an SDK or
+compiler upgrade is the moment to check two separate things: which program version your application
+now _produces_, and which versions it still _accepts_. Import the SDK's pins rather than copying
+their values, and keep an older pin only for a version you have decided to accept.
 
 The source is available through `settleSource()` from
 `@eco-incorp/sauce/recipes`, and as the
-`@eco-incorp/sauce/recipes/settle.sauce.ts` asset. `SAUCE_BASE_DIRS` locates its ABI
-dependencies for a reproducing resolver. The verifier itself does not load that
-source or recompile it.
+`@eco-incorp/sauce/recipes/settle.sauce.ts` asset. `resolveSdkModule` from
+`@eco-incorp/sauce/compiler` serves its ABI dependency to a reproducing resolver:
+
+```ts
+import { compile, resolveSdkModule } from "@eco-incorp/sauce/compiler";
+import { settleSource } from "@eco-incorp/sauce/recipes";
+import { SETTLE_PROGRAM } from "@eco-incorp/sauce/verify";
+import { bytesToHex } from "viem";
+
+const settle = new TextEncoder().encode(settleSource());
+const { bytecode } = compile({
+  target: "evm",
+  entry: "settle.sauce.ts",
+  resolve: (path) => (path === "settle.sauce.ts" ? settle : resolveSdkModule(path)),
+});
+if (bytesToHex(bytecode) !== SETTLE_PROGRAM.toLowerCase()) {
+  throw new Error("Did not reproduce the settle program");
+}
+```
+
+The verifier itself does not load that source or recompile it.
 
 ## SVM: verify program and accounts
 
@@ -182,7 +221,7 @@ instruction are the ones the application expects.
 
 `decodeSvmSettleExecution({ instructionData, accounts })` resolves accounts
 positionally against the canonical settlement refs. The default `wireFormat: "gated-v1"` accepts raw **engine CPI instructions** produced by Kitchen 1.0.0 for
-engine 1.2.0:
+engine 1.3.0:
 
 | Instruction            | Data                                                               | Full CPI account list                  |
 | ---------------------- | ------------------------------------------------------------------ | -------------------------------------- |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eco-incorp/sauce",
-  "version": "0.99.4",
+  "version": "0.99.6",
   "description": "Sauce protocol tooling: SDK, action primitives, and a local dev environment.",
   "type": "module",
   "repository": {
@@ -29,6 +29,7 @@
       "types": "./actions/dist/index.d.ts",
       "default": "./actions/dist/index.js"
     },
+    "./actions/action-program.schema.json": "./actions/action-program.schema.json",
     "./protocols/*": {
       "types": "./sdk/dist/protocols/*/index.d.ts",
       "default": "./sdk/dist/protocols/*/index.js"
@@ -83,6 +84,7 @@
     "LICENSE.md",
     "sdk/dist",
     "actions/dist",
+    "actions/action-program.schema.json",
     "sdk/src/skills",
     "sdk/src/protocols",
     "dev-tools/scripts",
@@ -102,16 +104,18 @@
     "@solana/kit": "^6.10.0",
     "acorn": "^8.15.0",
     "dotenv": "^17.3.1",
-    "sauce-compiler": "npm:@eco-incorp/sauce-compiler@2.3.0",
+    "sauce-compiler": "npm:@eco-incorp/sauce-compiler@2.4.0",
     "typescript": "^5.7.0",
     "viem": "^2.45.3"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
     "@uniswap/v3-core": "^1.0.1",
+    "esbuild": "0.28.0",
     "eslint": "10.10.0",
     "globals": "16.5.0",
     "hardhat": "^2.22.0",
+    "playwright-core": "1.63.0",
     "prettier": "3.9.6",
     "typescript-eslint": "8.70.0"
   },
@@ -120,6 +124,7 @@
   },
   "scripts": {
     "docs:check": "node docs/scripts/check-docs.mjs",
+    "check:browser": "node sdk/scripts/check-browser-bundles.mjs && node sdk/scripts/check-browser-compile.mjs",
     "build": "pnpm -r --filter './sdk' --filter './actions' build",
     "typecheck": "pnpm -r typecheck",
     "test": "pnpm -r test",