@eco-incorp/sauce 0.99.3 → 0.99.5

package/dev-tools/src/svm-local.ts

@@ -30,15 +30,15 @@ import {
   derivePotPda,
   deriveProgramDataPda,
   MAX_POT_LEN,
+} from "@eco-incorp/sauce-source/svm";
+import type { AccountResolution, SignedExecuteTransaction } from "@eco-incorp/sauce-source/svm";
+import {
   svmEnginePath,
   svmKitchenIdlPath,
   svmKitchenPath,
-} from "@eco-incorp/sauce-source/svm";
-import type {
-  AccountResolution,
-  EngineCluster,
-  SignedExecuteTransaction,
-} from "@eco-incorp/sauce-source/svm";
+  type EngineCluster,
+  type SvmEngineArtifactPaths,
+} from "@eco-incorp/sauce-source/svm/engine-artifacts";
 import type { AccountManifest } from "sauce-compiler";
 
 /** Slot every local run sits at (must exceed a fabricated ALT's last_extended_slot 0). */
@@ -65,8 +65,10 @@ export interface RunResult {
 }
 
 /** The kitchen's declared program id, read from the release IDL (a hardcoded id rotted once before). */
-const kitchenProgramId = (): Address =>
-  address((JSON.parse(readFileSync(svmKitchenIdlPath(), "utf8")) as { address: string }).address);
+const kitchenProgramId = (idlPath?: string): Address =>
+  address(
+    (JSON.parse(readFileSync(svmKitchenIdlPath(idlPath), "utf8")) as { address: string }).address,
+  );
 
 /**
  * Makes `authority` the kitchen's upgrade authority so the fee config can be initialized. LiteSVM
@@ -139,11 +141,13 @@ const mustSucceed = (result: RunResult, what: string): void => {
 /**
  * Boots LiteSVM with the packaged engine + kitchen, a funded payer, a priced-then-freed execution
  * fee, and a Pot — the full gated set. `unixTimestamp` pins the cluster clock (venue fragments read
- * ctx.timestamp()); `cluster` picks which packaged engine `.so` to load.
+ * ctx.timestamp()); `cluster` picks which packaged engine `.so` to load; `artifacts` names binaries
+ * to load instead of the packaged ones (an unreleased engine build, say).
  */
 export const bootLocalEngine = async (
   unixTimestamp = 1_700_000_000n,
   cluster: EngineCluster = "devnet",
+  artifacts: SvmEngineArtifactPaths = {},
 ): Promise<LocalEngine> => {
   const svm = new LiteSVM()
     .withFeatureSet(FeatureSet.allEnabled())
@@ -153,10 +157,10 @@ export const bootLocalEngine = async (
     .withDefaultPrograms();
 
   const programId = (await generateKeyPairSigner()).address;
-  svm.addProgramFromFile(programId, svmEnginePath(cluster));
+  svm.addProgramFromFile(programId, svmEnginePath(cluster, artifacts.engineSo));
 
-  const kitchen = kitchenProgramId();
-  svm.addProgram(kitchen, new Uint8Array(readFileSync(svmKitchenPath())));
+  const kitchen = kitchenProgramId(artifacts.kitchenIdlJson);
+  svm.addProgram(kitchen, new Uint8Array(readFileSync(svmKitchenPath(artifacts.kitchenSo))));
 
   svm.warpToSlot(LOCAL_SLOT);
   svm.setClock(new Clock(LOCAL_SLOT, 0n, 0n, 0n, unixTimestamp));
@@ -257,6 +261,8 @@ export interface RunProgramOptions {
   cluster?: EngineCluster;
   /** Cluster clock, unix seconds (default 1_700_000_000). */
   unixTimestamp?: bigint;
+  /** Engine/kitchen binaries to load instead of the packaged ones. */
+  artifacts?: SvmEngineArtifactPaths;
 }
 
 /**
@@ -276,7 +282,11 @@ export const runSvmProgramLocally = async (
   manifest: AccountManifest,
   options: RunProgramOptions = {},
 ): Promise<{ err: string | null; logs: string[] }> => {
-  const engine = await bootLocalEngine(options.unixTimestamp ?? 1_700_000_000n, options.cluster);
+  const engine = await bootLocalEngine(
+    options.unixTimestamp ?? 1_700_000_000n,
+    options.cluster,
+    options.artifacts,
+  );
   return withLiteSvmRpc(engine, async () => {
     const client = await createSauceSvmClient({
       kitchen: engine.kitchen,

package/docs/README.md

@@ -1,39 +1,50 @@
 # Sauce documentation
 
-Build programmable EVM and Solana transactions with `@eco-incorp/sauce`, and compose EVM
-executions into Eco intents. Solana execution uses the direct Kitchen client; the
-[legacy SVM intent helper](guides/solana.md#svm-destinations-in-eco-intents) is incompatible
-with the released engine.
-
-**New here?** Follow the [quick start](guides/quick-start.md), explore
-[token and protocol globals](guides/protocols-and-tokens.md), then
-[create and fund an intent](guides/intents.md). Complete programs live in the
-[examples](examples/README.md).
+Sauce is a programmable-transaction runtime. A Sauce program compiles to bytecode that an on-chain
+engine executes atomically inside one transaction — every step lands or none does. `@eco-incorp/sauce`
+is the package you build those programs with. One install carries the compiler and the chains,
+tokens and protocols a program calls by name; you write the program, not a contract of your own.
+
+**Routes** are the layer above: a route packages a program as an Eco intent, so it can be executed
+on another chain in exchange for a reward escrowed on this one. Everything cross-chain lives there.
+
+## First program in five minutes
+
+1. [Install](guides/quick-start.md) the package. The compiler is inside it.
+2. [Build your first intent](guides/quick-start.md#build-your-first-intent) by copying one
+   example. It runs offline.
+3. Put your own calls in its body, naming [tokens and protocols](guides/protocols-and-tokens.md).
+4. [Create an intent from inside the program](guides/intents.md#create-an-intent-from-inside-a-program)
+   when the amount is only known on chain.
+5. [Submit the source reward](guides/intents.md#submit-the-source-reward) with the requests the SDK
+   prepares. A solver then decides whether to fill it.
+
+Complete programs live in the [examples](examples/README.md).
+
+## By task
+
+| You want to                                                     | Guide                                                  |
+| --------------------------------------------------------------- | ------------------------------------------------------ |
+| Call tokens and protocols by name inside a program              | [Protocols and tokens](guides/protocols-and-tokens.md) |
+| Construct, fund, submit and inspect an intent                   | [Create an intent](guides/intents.md)                  |
+| Chain intents — statically, or from an amount measured on chain | [Nested intents](guides/nested-intents.md)             |
+| Compile a standalone program and pass it runtime arguments      | [Compiling programs](guides/compiling.md)              |
+| Generate programs from structured data                          | [Builders](guides/builders-and-actions.md)             |
+| Write protocol actions as JSON, then run them or make an intent | [Actions](guides/actions.md)                           |
+| Plan accounts, stage code and execute on Solana                 | [Solana](guides/solana.md)                             |
+| Check what a settlement payload contains                        | [Verification](guides/verification.md)                 |
 
 ## Concepts
 
-| Read                                     | Learn                                                                                   |
-| ---------------------------------------- | --------------------------------------------------------------------------------------- |
-| [Architecture](concepts/architecture.md) | How the SDK, compiler package, on-chain engine, and Eco intents fit together            |
-| [SauceScript](concepts/saucescript.md)   | Execution model, source closures, supported language constructs, and target differences |
-
-## Guides
-
-| Task                                                  | Guide                                                  |
-| ----------------------------------------------------- | ------------------------------------------------------ |
-| Install and build your first intent                   | [Quick start](guides/quick-start.md)                   |
-| Use `USDC`, `Token(address)`, and protocol namespaces | [Protocols and tokens](guides/protocols-and-tokens.md) |
-| Construct, fund, and inspect an intent                | [Eco intents](guides/intents.md)                       |
-| Compose multiple intent executions                    | [Nested intents](guides/nested-intents.md)             |
-| Compile directly and encode runtime arguments         | [Compiling programs](guides/compiling.md)              |
-| Generate programs from structured inputs              | [Builders and actions](guides/builders-and-actions.md) |
-| Plan accounts, stage code, and execute on SVM         | [Solana](guides/solana.md)                             |
-| Check a settlement payload                            | [Verification](guides/verification.md)                 |
-
-## Reference and examples
-
-- [API entry points](api/README.md): published imports and where to find each feature.
-- [Compiler API](api/compiler.md): compiler options, output metadata, and argument encoding.
-- [Routes API](api/routes.md): execution options, intent builders, and Portal helpers.
-- [Registry coverage](api/coverage.md): protocols, source globals, tokens, and chain registries.
-- [Examples](examples/README.md): complete examples and how they are validated.
+| Read                                     | To understand                                                                     |
+| ---------------------------------------- | --------------------------------------------------------------------------------- |
+| [Architecture](concepts/architecture.md) | How the package, the compiler and the on-chain engine divide the work             |
+| [SauceScript](concepts/saucescript.md)   | The language: what runs on chain, what the compiler accepts, what values reach it |
+
+## Reference
+
+- [API entry points](api/README.md) — every published import and what it contains.
+- [Routes](api/routes.md) — chain entry points, intent options, built intents, nesting.
+- [Compiler](api/compiler.md) — `compile()` options and result, and the compact argument codec.
+- [Coverage](api/coverage.md) — which protocols, tokens and chains are actually registered.
+- [Examples](examples/README.md) — complete programs, and how they are kept working.

package/docs/api/README.md

@@ -3,24 +3,24 @@
 Install `@eco-incorp/sauce` and import through the package's public entry points. All paths below
 are suffixes of that package name; `.` means `@eco-incorp/sauce` itself.
 
-| Import                         | Contents                                                                                                                  |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
-| `.`                            | `routes`, `token`, `swap`, `deposit`, `contracts`, `svmVenues`; protocol and chain queries; installation of chain globals |
-| `/compiler`                    | `compile`, compiler types, `encodeCompactArguments`, and `decodeCompactArguments`                                         |
-| `/actions`                     | Action primitives and `actionsToSauce` composition                                                                        |
-| `/protocols/*`                 | One protocol's `protocolInfo`, `deployments`, ABI exports, and named SauceScript templates                                |
-| `/chains`                      | Canonical chain identities and EVM chain metadata                                                                         |
-| `/deployments`                 | Sauce engine/Kitchen addresses, Pot derivation inputs, and recorded deployment coverage                                   |
-| `/recipes`                     | EVM settlement source and CCTP/plain-transfer recipe builders and sources                                                 |
-| `/recipes/settle.sauce.ts`     | EVM settlement source asset                                                                                               |
-| `/svm`                         | SVM clients, account plans, resolution, staging, Kitchen instructions, recipes, and transactions                          |
-| `/svm/engine`                  | SVM engine wire format and instruction builders                                                                           |
-| `/svm/engine-artifacts`        | Node helpers locating packaged SVM engine/Kitchen binaries and IDL                                                        |
-| `/svm/verify`                  | SVM program and gated engine CPI verification; separate Kitchen decoding is required                                      |
-| `/svm/recipes/settle.sauce.ts` | SVM settlement source asset                                                                                               |
-| `/evm/engine`                  | EVM Pot and Kitchen ABIs and call encoders (`v12PotAbi`, `v12KitchenAbi`, `v12Pot`, `v12Kitchen`)                         |
-| `/verify`                      | EVM settlement encoding, structural decoding, and validation against the pinned program                                   |
-| `/skills`                      | Protocol Markdown index and skill-file loaders                                                                            |
+| Import                         | Contents                                                                                                                                   |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `.`                            | Chain accessors (`Base`, `Solana`, …); `routes`, `token`, `swap`, `deposit`, `contracts`, `svmVenues`; protocol and chain queries; `ready` |
+| `/compiler`                    | `compile`, `ready`, compiler types, the compact codec, and `resolveSdkModule`/`resolveSdkPackage`                                          |
+| `/actions`                     | JSON action programs: validation, compilation and intents; the JSON Schema is `/actions/action-program.schema.json`                        |
+| `/protocols/*`                 | One protocol's `protocolInfo`, `deployments`, ABI exports, and named SauceScript templates                                                 |
+| `/chains`                      | Canonical chain identities and EVM chain metadata                                                                                          |
+| `/deployments`                 | Sauce engine/Kitchen addresses, Pot derivation inputs, and recorded deployment coverage                                                    |
+| `/recipes`                     | EVM settlement source and CCTP/plain-transfer recipe builders and sources                                                                  |
+| `/recipes/settle.sauce.ts`     | EVM settlement source asset                                                                                                                |
+| `/svm`                         | SVM clients, account plans, resolution, staging, Kitchen instructions, recipes, and transactions                                           |
+| `/svm/engine`                  | SVM engine wire format and instruction builders                                                                                            |
+| `/svm/engine-artifacts`        | Node-only helpers locating packaged SVM engine/Kitchen binaries and IDL                                                                    |
+| `/svm/verify`                  | SVM program and gated engine CPI verification; separate Kitchen decoding is required                                                       |
+| `/svm/recipes/settle.sauce.ts` | SVM settlement source asset                                                                                                                |
+| `/evm/engine`                  | EVM Pot and Kitchen ABIs and call encoders (`v12PotAbi`, `v12KitchenAbi`, `v12Pot`, `v12Kitchen`)                                          |
+| `/verify`                      | EVM settlement encoding, structural decoding, and validation against the pinned program                                                    |
+| `/skills`                      | Protocol Markdown index and skill-file loaders                                                                                             |
 
 The [`exports` map](../../package.json) defines this list. There is no `/routes`, `/token`,
 `/swap`, `/deposit`, or `/contracts` subpath; import these namespaces from the root:
@@ -30,9 +30,12 @@ import { routes, token, contracts } from "@eco-incorp/sauce";
 import { compile } from "@eco-incorp/sauce/compiler";
 ```
 
-`Base`, `Solana`, `chain`, and `Token` are installed globals, rather than named root exports.
-Bare protocol and token globals such as `Uniswap` and `USDC` describe compiled route source and
-have no corresponding host JavaScript objects. See
+Every chain is a **named export** of the root: `import { Base, Solana } from "@eco-incorp/sauce"`.
+Importing the package puts nothing on `globalThis`. `chain(ref)` and the host `Token` builder are
+named exports too.
+
+Bare names such as `USDC` and `Uniswap` are different: they are _program syntax_, resolved by the
+compiler inside a route body, with no host JavaScript object behind them. See
 [protocols and tokens](../guides/protocols-and-tokens.md).
 
 ## Detailed references
@@ -41,7 +44,7 @@ have no corresponding host JavaScript objects. See
 - [Routes](routes.md): compile options, intent construction, nested execution, and submission helpers.
 - [Coverage](coverage.md): distinguish catalog entries, callable descriptors, and available deployments.
 
-For structured program creation, see [builders and actions](../guides/builders-and-actions.md).
+For programs assembled from data rather than written, see [builders](../guides/builders-and-actions.md).
 For account-based execution and settlement checks, see the [Solana](../guides/solana.md) and
 [verification](../guides/verification.md) guides.
 
@@ -60,12 +63,17 @@ const aaveMarkdown = getProtocolSkill("aave-v3");
 const availableSkills = listSkillSlugs();
 ```
 
-Skill resources are documentation strings; loading one performs no protocol operation.
-`getProtocolSkill` throws for a slug absent from `listSkillSlugs()`.
+Skill files are Markdown written for AI coding assistants; loading one reads a document and
+performs no protocol operation. `getProtocolSkill` throws for a slug absent from `listSkillSlugs()`.
+
+## Where each import runs
 
-## Runtime requirements
+Every import runs in Node **24 or newer** and in a browser, with one exception:
+`/svm/engine-artifacts` returns filesystem paths to the packaged engine binaries for a local
+LiteSVM harness, and is Node-only.
 
-The root SDK, its route compiler integration, recipe source loaders, skill loaders, and artifact
-resolvers use Node.js APIs. `/verify` has a `viem`-only dependency closure and can validate EVM
-settlement payloads in a browser without loading the compiler. See the
-[compiler reference](compiler.md) for the compiler dependency's separate browser entry point.
+Anything that compiles — `/compiler`, route compilation, the builders, the recipes, `/actions`,
+`/svm/verify` — needs one `await ready()` first in a browser, while the compiler's WebAssembly
+loads; the [compiler reference](compiler.md#in-a-browser) covers it. In Node nothing needs it.
+`/verify` never loads the compiler: its dependency closure is `viem` alone, so an EVM settlement
+payload can be validated in a browser or an edge runtime without it.

package/docs/api/compiler.md

@@ -2,21 +2,28 @@
 
 [Documentation](../README.md) · [Compiling programs](../guides/compiling.md)
 
-`@eco-incorp/sauce/compiler` exposes the published Rust/WASM compiler to Node
-consumers and supplies the SDK's compact argument codec.
+`@eco-incorp/sauce/compiler` is the SauceScript compiler and the codec for its compact
+argument format. Both ship with the SDK; there is nothing extra to install. It runs in
+Node and in a browser; in a browser, [`await ready()`](#in-a-browser) first.
 
 ```ts
 import {
   compile,
+  ready,
   encodeCompactArguments,
   decodeCompactArguments,
+  resolveSdkModule,
+  resolveSdkPackage,
   type CompileOptions,
   type CompileResult,
 } from "@eco-incorp/sauce/compiler";
 ```
 
-The compiler is installed with the SDK. This reference and its examples are
-validated with `@eco-incorp/sauce-compiler` **2.3.0**.
+This SDK pins compiler **2.4.0**, EVM engine and Kitchen **1.1.0**, SVM engine **1.3.0**,
+and SVM Kitchen **1.0.0**. Release addresses identify this compatible set; they do not
+confirm it has been deployed on a chain. Check deployment readiness before using it live.
+
+Every example here is checked against the compiler version this package ships.
 
 ## `compile(options): CompileResult`
 
@@ -36,7 +43,7 @@ const artifact = compile({
   resolve: (path) => (path === "main.ts" ? source : undefined),
 });
 
-console.log(artifact.bytecode, artifact.isaRevision, artifact.entryEncoding);
+console.log(artifact.bytecode.length, artifact.entryEncoding);
 ```
 
 ### Options
@@ -55,8 +62,8 @@ console.log(artifact.bytecode, artifact.isaRevision, artifact.entryEncoding);
 | `compactArgs`     | `boolean`                                              | Use compact-v1 entry arguments; default `false`                        |
 | `cache`           | `boolean`                                              | Enable the per-function lowering cache; default `true`                 |
 
-`optimize: false` disables optimizations such as constant folding, loop unrolling,
-common-subexpression elimination, and helper inlining. Validation still runs.
+`optimize: false` turns the optimizer off. Every check the compiler performs still
+runs; you get a larger, more literal program.
 
 `defines` accepts decimal or `0x` integer strings, with supported literal
 separators and an optional trailing `n`. Use strings so the JavaScript host does
@@ -86,6 +93,30 @@ For a package with a neutral entry such as `token.js`, resolution can probe
 `token.evm.js` or `token.svm.js` according to the target. Supply the neutral
 specifier and let the compiler select the arm.
 
+### The SDK's own modules
+
+`resolveSdkModule(path)` and `resolveSdkPackage(specifier)` serve the files the SDK
+ships, from memory, with the contracts above: the `@sauce/token` library, the
+`./artifacts/IERC20.json` and `./artifacts/ISauceRouter.json` ABIs, and every protocol
+ABI as `./protocols/<slug>/<Export>.json`. Fall back to them from your own resolver
+to compile a program the SDK's builders emit, or one that imports `@sauce/token`:
+
+```ts
+const entry = new TextEncoder().encode(`
+  import { balanceOf } from "@sauce/token";
+  function main(token: Address, account: Account): Uint256 {
+    return balanceOf(token, account);
+  }
+`);
+
+const artifact = compile({
+  target: "evm",
+  entry: "main.ts",
+  resolve: (path) => (path === "main.ts" ? entry : resolveSdkModule(path)),
+  resolvePackage: resolveSdkPackage,
+});
+```
+
 ### Result
 
 ```ts
@@ -100,20 +131,21 @@ interface CompileResult {
 
 - `bytecode` is one reusable program. Per-execution argument values have not been
   appended.
-- `isaRevision` identifies the compiler's instruction-set contract. It does not
-  check which runtime is deployed at an address.
+- `isaRevision` labels the instruction set this artifact was built for. Record it
+  with the artifact and run the program on an engine built for the same one; it is
+  a label, not a check against any deployed address.
 - `entryEncoding` selects the argument encoder: ordinary ABI arguments by
   default, compact arguments when `compactArgs: true`. It does not describe
-  [program return encoding](../guides/compiling.md#encode-evm-return-values).
+  [program return encoding](../guides/compiling.md#return-values-an-abi-decoder-can-read).
 - `entrySchema` describes compact argument structure. Pass this exact schema to
   the compact codec; do not infer or rebuild it from example bytes.
 - `manifest` is present for SVM and describes attached accounts. It is absent
   for EVM.
 
-Compilation and resolution failures throw a JavaScript `Error`. Source diagnostics
-include a location and span; option, resolver, and target-capability errors may
-have neither. A resolver callback's thrown message is preserved. There is no
-success-with-error result or warning array in this API.
+Compilation and resolution failures throw. A source diagnostic carries a location
+and span; an error about an option, a resolver or a feature the target lacks has
+nothing to point at. A message thrown by your own resolver is preserved. There is
+no success-with-warnings result to inspect — if `compile()` returns, it worked.
 
 ### SVM account manifest
 
@@ -142,12 +174,16 @@ The subpath also exports `AccountEntry`, `AccountManifest`, `AccountRole`,
 ## Compact argument codec
 
 ```ts
-encodeCompactArguments(schema: Uint8Array, value: CompactValue): Uint8Array;
+encodeCompactArguments(
+  schema: Uint8Array,
+  value: CompactValue,
+  options?: { scalarWidth?: number },
+): Uint8Array;
 
 decodeCompactArguments(
   schema: Uint8Array,
   data: Uint8Array,
-  options?: { maxValues?: number },
+  options?: { maxValues?: number; scalarWidth?: number },
 ): CompactValue;
 ```
 
@@ -163,22 +199,26 @@ attached separately; EVM `Account` parameters are encoded as scalars. For
 addresses/public keys are integers or hexadecimal integers; base58 public-key
 text is not a scalar encoding.
 
-The encoder emits compact-v1 data beginning with `53 41 01 00`, minimum-width
-256-bit scalars, canonical booleans, unpadded bytes, and big-endian collection
-lengths. Negative integers preserve their 256-bit two's-complement bit pattern.
-The decoder returns scalar words as unsigned `bigint`, booleans as `boolean`,
-bytes as `Uint8Array`, and collections as arrays. It does not recover a signed
-application type from a scalar word.
+A negative integer keeps its 256-bit two's-complement pattern, and the decoder
+returns every scalar as an unsigned `bigint` — it has no way to know you meant a
+signed type, so convert at your own boundary.
+
+Encoding is canonical: one value, one byte string. The decoder enforces that, and
+rejects a padded scalar, a non-canonical boolean, a malformed length or trailing
+data. `maxValues` bounds the decoded object graph and defaults to `1_000_000`.
+A schema may be at most 65,535 bytes and 32 levels deep.
 
-The decoder rejects non-minimal scalars, non-canonical booleans, malformed or
-truncated lengths, and trailing data. `maxValues` bounds its decoded value graph
-and defaults to `1_000_000`. Schemas are limited to 65,535 bytes and 32 nested
-levels. The engine applies its own heap and execution limits as well; successful
-host encoding does not establish that a payload fits a transaction or runtime.
+`scalarWidth` fixes every scalar at a declared width of 1–32 bytes instead of the
+smallest that fits. The payload stays canonical — still exactly one encoding per
+value — but its **length stops depending on the values**, which is what lets a
+caller write a number into an already-built payload at a known offset. Pass the
+same width to both functions; a decode without it rejects the padded form, and a
+decode with it rejects the minimal one. A value too wide for the declared width is
+rejected rather than truncated.
 
-Compact-v1 changes **program entry arguments**. EVM contract calls made by the
-program still use their contract ABIs. The SDK's canonical EVM settlement verifier
-currently expects its pinned ABI-v1 settlement payload, not a compact recompile.
+Encoding successfully says nothing about whether the payload fits a transaction or
+the engine's own execution limits. And compact-v1 is about **entry arguments only**:
+contract calls the program makes still use their contract ABIs.
 
 ## Raw compiler versus route compilation
 
@@ -196,39 +236,60 @@ rewrites and call encoding. Its result is:
 
 There is one compiled segment and one route call. `source` is the SDK-rewritten
 program; the internal compiler adapter can additionally annotate a falling-through
-`main` as `void`. `warnings` is currently empty: compilation failures throw.
+`main` as `void`. `warnings` is always empty — a compilation failure throws.
 
-The route adapter does not return the raw compiler's ISA metadata, entry schema,
-or SVM manifest, and its options do not expose `compactArgs`, `cache`, or
-`optimize`. Use raw `compile()` when you need those fields, explicit runtime
-parameters, or the compiler's full resolver control. Route `target: "v1"` is a
-compatibility spelling mapped to the same EVM backend as `"v12"`.
+The route adapter keeps neither the entry schema nor the SVM manifest, and its
+options do not expose `compactArgs`, `cache` or `optimize`. Use raw `compile()`
+when you need any of those, runtime entry parameters, or full resolver control.
+Route `target: "v1"` and `"v12"` both select the EVM backend.
 
 See [routes](routes.md) for the route-specific API.
 
-## Node, browsers, and compiler-only features
+## In a browser
 
-The SDK requires Node **24 or newer**. Its `/compiler` export loads the compiler
-through Node's `createRequire`; SDK route compilation also uses filesystem and
-path APIs. These integrations are Node APIs.
-
-The underlying compiler package separately supplies Node and browser builds.
-For a browser application, install `@eco-incorp/sauce-compiler` directly and use
-its initialization API:
+The SDK compiles in a browser exactly as it does in Node: raw `compile()`, route
+compilation (`Base(...)`, `.reward(...)`, `compileSauceRoute`), the builders, the
+recipes and `/actions` produce the same bytes in both. The difference is start-up.
+Node instantiates the compiler's WebAssembly as the package loads; a browser has to
+fetch it, which cannot happen synchronously. Call `ready()` once, before the first
+compile:
 
 ```ts
-import { ready } from "@eco-incorp/sauce-compiler/ready";
+import { ready } from "@eco-incorp/sauce/compiler"; // also exported by "@eco-incorp/sauce"
 
-const { compile } = await ready();
-// Supply source/dependencies through synchronous in-memory resolvers.
+await ready();
+// compile(), compileSauceRoute(), Base(...).reward(...) and compileProgram() are now
+// synchronous, as in Node.
 ```
 
-`ready()` initializes the browser WASM build and is a no-op for the already
-initialized Node build. Arrange for the compiler's WASM asset and dependency
-bytes to be available before compiling. This does not provide the SDK's route
-rewrites or registry resolver in a browser.
+Until `ready()` resolves, every compile throws an error saying to await it. In Node
+it resolves at once and no compile needs it, so code shared by both can always call
+it. Calling it again is harmless, and a failed attempt is not remembered: calling
+again retries.
+
+With no argument, `ready()` loads the compiler package's `web/sauce_wasm_bg.wasm`
+through `new URL("sauce_wasm_bg.wasm", import.meta.url)`, relative to the compiler's
+own module. A bundler that rewrites `new URL(…, import.meta.url)` asset references
+emits the file and points the URL at it. With one that does not — esbuild, for
+example — copy the file next to your bundle, or tell `ready()` where it is: a URL,
+or the bytes themselves.
+
+```ts
+await ready(new URL("/assets/sauce_wasm_bg.wasm", location.href));
+// or
+await ready(await (await fetch("/assets/sauce_wasm_bg.wasm")).arrayBuffer());
+```
+
+The first `source` that succeeds is the one used; the compiler warns if a later call
+passes a different one.
+
+Every subpath works in a browser except `/svm/engine-artifacts`. It returns filesystem
+paths to the packaged engine binaries for a local LiteSVM harness, and is Node-only.
+In Node, the SDK requires Node **24 or newer**.
+
+## Compiler-only features
 
-The compiler package also exports `clearFunctionCache()` and
-`functionCacheStats()`. The SDK `/compiler` barrel does not re-export them or
-`ready()`. Applications using these compiler-only exports should declare the
-compiler as a direct dependency and import from its published package name.
+The compiler package also exports `clearFunctionCache()` and `functionCacheStats()`
+for inspecting its internal lowering cache. The SDK's `/compiler` export does not
+re-export those; an application that wants them declares the compiler as a direct
+dependency and imports from its own package name.