@typesol/cli 0.25.0 → 0.26.0

package/CHANGELOG.md

@@ -6,6 +6,27 @@ codes, and says so here.
 
 ## Unreleased
 
+## 0.26.0 — 2026-10-29
+
+A first-run experience pass, the security model and audit package, and more fuzzing. The compiler's output is the
+same as 0.25.0 for every program.
+
+- New: `typesol doctor` checks Node.js, the platform-tools, the Solana CLI, its keypair, the RPC and the keypair's
+  balance there, and the project, and prints the command that fixes each problem (exit 1 when building is impossible).
+- `typesol init` prints the files it creates relative to where it runs, warns with the install commands when the
+  platform-tools are missing, and lists the next steps.
+- `typesol deploy` checks, before sending anything, that the RPC answers (else: start `solana-test-validator`, or
+  `--url devnet`) and that the payer can pay the rent (else: how much, and the `solana airdrop` command on devnet or a
+  local validator). RPC URLs in these messages show only the host.
+- Docs: [security model](docs/security-model.md) (the guarantees a compiled program can rely on, trust boundaries,
+  what is left to the author) and [audit package](docs/audit.md) (scope, priorities, earlier reviews, evidence);
+  README: deploying on devnet and on a local validator.
+- Tests: `test/verification/fuzz-layout.test.ts`, model-based fuzzing of an account with two growable Vecs and of
+  `loadAccountMut` aliasing through remaining accounts (also in `pnpm fuzz`).
+- Repository: tests grouped by subject under `test/`, the Anchor twins in `test/anchor-twins` (`pnpm build:twins`),
+  the generators and chain tooling in `src/tools/` (the package's import paths are unchanged); Dependabot for npm and
+  GitHub Actions.
+
 ## 0.25.0 — 2026-10-29
 
 Security review (October 2026) fixes, and error codes aligned with Anchor. Some refused transactions now report a

package/README.md

@@ -149,9 +149,20 @@ npx @typesol/cli init my-app --name counter   # typesol.json, programs/counter.t
 cd my-app && npm install
 npm test                                      # builds the program and runs it in LiteSVM, an in-process Solana runtime
 npx typesol build                             # target/counter/{counter.so, counter.json (IDL), counter.client.ts, counter.build.json}
-npx typesol deploy --url http://127.0.0.1:8899 --keypair ~/.config/solana/id.json
 ```
 
+`npx typesol doctor` checks all of this (Node.js, platform-tools, Solana CLI, keypair, RPC) and prints the command
+that fixes anything missing. To deploy, on devnet:
+
+```sh
+solana-keygen new                             # once, if you have no keypair (~/.config/solana/id.json)
+solana airdrop 2 --url devnet                 # test SOL for the rent (rate-limited: https://faucet.solana.com also works)
+npx typesol deploy --url devnet
+```
+
+or on a local validator: `solana-test-validator` in another terminal, `solana airdrop 5 --url localhost`, then
+`npx typesol deploy --url localhost`. `deploy` checks the RPC and the payer's balance before sending anything.
+
 `--template vault` or `--template escrow` starts from a SOL vault or an SPL token escrow instead of the counter, each
 with a passing LiteSVM test.
 
@@ -262,23 +273,28 @@ units are not a safety claim. The differential tests also run the escrow against
 ### On mainnet
 
 The official escrow ([tokens/escrow](https://github.com/solana-developers/program-examples/tree/de090195e4de698e150572c4f886c333323a64a5/tokens/escrow)),
-deployed to Solana mainnet-beta in all four versions on 2026-10-27 and called with the same mints, amounts and accounts,
-one instruction per transaction. Each figure is the compute units of that transaction, linked to Solscan; the lowest per row is in bold. The deployed
-programs match these builds byte for byte (`typesol verify` for TypeSOL), and the TypeSOL program's IDL is published
-on chain with `typesol idl publish`.
+deployed to Solana mainnet-beta in all four versions and called with the same mints, amounts and accounts, one
+instruction per transaction. The TypeSOL program was upgraded in place to 0.25.0 on 2026-10-29; the others are as first
+deployed on 2026-10-27. Each figure is the compute units of that transaction, linked to Solscan; the lowest per row is
+in bold. The deployed programs match these builds byte for byte (`typesol verify` for TypeSOL), and the TypeSOL
+program's IDL is published on chain with `typesol idl publish`.
 
 | Transaction | TypeSOL | Pinocchio | Native Rust | Anchor |
 | --- | ---: | ---: | ---: | ---: |
-| make_offer (offer 1) | [20,304](https://solscan.io/tx/32PVva77dT1rSWrMWX2sHTMPZiwztdEZYtpANaxrsuJxPcd3hnV6pDgJJaV4LkL3bX6ALDoHMNF8fjngtodYHBS1) | [**19,645**](https://solscan.io/tx/528BdMTrnLWauSXVh2vaFfy4XwKFpbyt95hQ6w3fwjtpkT85RPkRhGydunAizNDRqTTLPxcEVMrdcDvRer4H9LRE) | [30,698](https://solscan.io/tx/4MQgt75MvojaAkfxnvrE2yJWabGpE8bsZhNq2CeGJxHZg6uD6A64Kv71JmrsgiGnaEovvv8K34DYL49owLjhs4QJ) | [38,648](https://solscan.io/tx/9T1ZY9JaSMb1GMqv1i22AuZuJQN6B5XcgqeDv5tGqEm5Uox3MBTdXsECt59GwcXkFG9QKgXJyqndTEzpSXhbAVM) |
-| take_offer (offer 1) | [**7,998**](https://solscan.io/tx/49EQwgnKShFdsAs37AEzYmv6tLY8DipcCjmRgqwj4fVTFEgVVWdEXw5AvuEufL5ymJYs4T4hVFdkENW9XK9een5m) | [25,206](https://solscan.io/tx/21MGkXpKRe4c7EeA1hC6JHevsk78xUdbcWmyqG47EbLeCNKSMTzTjkJQqtydnQmV8uHPmr6bJHnvQmmQTSZB7Am2) | [28,612](https://solscan.io/tx/B1hu1EL4Y5vWhBVWdyZEpzRNJb8kd6G9CgN7KtyNNGpQ84o9dfn1sdy9Z1UCHECNtp24Mw8bEH2iYz2YADdEUjx) | [32,835](https://solscan.io/tx/3ZLuQQz7Bx5YdgmFXpVQWHn5kyc8v39jr2BnfofH6sqenzfJpAdVm4h38uYcHwYygnfso92kJe7HRHeASsABoKPQ) |
-| make_offer (offer 2) | [21,804](https://solscan.io/tx/xuu9KXbZvzGDpTEEcDE9LYvBqmPen81y6ty92e6crRxT8m4Mc4XyxhjWHbjVNsr9RE3QY4M1j1Sw9cH7PRMKKuc) | [**19,645**](https://solscan.io/tx/LLzS13AJrqACGoT1VHZN278ij39pNkttb1Z4Wh2AYXknWxwjaiaiMeD7WZomjP6TBv18RHfQHUfogQzApvXr2mC) | [35,198](https://solscan.io/tx/4xiKfzyccVatef1T52tZ3VAJwcx5R7iWgHWezBzZ3p2WpvoLzMp1PSUgr7x3sspE53mDE5JaghaNPKuUohVgPuwc) | [47,648](https://solscan.io/tx/4mxW8D5zpY8t4fL8JRbvhp6ejU6CUvB3iWmFjACipzexW6tZfFeatfnEnDTX3Y97BxsvAftoX9eQauiVu84xrLxh) |
-| refund_offer (offer 2) | [**5,961**](https://solscan.io/tx/4kY7s3y95Lrd2WGCWGPWW3zFBVtEKH6EskdscuYmRCRRgPt2rJTZ1CmZMGUUkHs7aai9AygEiTSUG23EMUrFr7rg) | [13,387](https://solscan.io/tx/QUXWwdbKRcT6WhZvSe4U8nxr4GAMaPNV6pZ1fwrC28kRxdJm7HKXVr2DFRuKD9bEzoS6hFdiA2rLr1mQWyrN3oz) | [17,731](https://solscan.io/tx/5zj7E4c61j1JzUsUPC1fNs9ECFLVmCug9rsdYsVLn7YD1RSxdbAJUQDam1BX3epTzW6ed2uFGwTiNhwaYo7vqdwm) | [23,576](https://solscan.io/tx/5Kjwnq5tN8mzj5s67VGxSry4kRzZk6HLdgXW65FyTvpUeC1D7aQoDGTwzrA7kqyYEvV9y9znnZmLaqU98zFrJJo4) |
+| make_offer (offer 1) | [29,205](https://solscan.io/tx/4AaenpnDGYmT2JXAm8HuN5D9GkEWLYeqyMNxJq6D9aYk6ssunSwNTigFmZoCJtY7MZ3FFBXLsig8jo1YmjUFVTpX) | [**21,145**](https://solscan.io/tx/3tWjcMQxTja6QjEmAvi1MRF9qCsnPBsAmQNPnd5RcNTwnkkJYmk9JFFnZoJbTAc6MEr2QYQd7KtgPGtaNr3inrCG) | [45,698](https://solscan.io/tx/4AgQzePrXL4f4qYrFQBzE65d8cszpmqSiQVt9yVsAotbrYTnartXuM2g2PFg7VhUGaZpbhfH9jzXgwXdRLXwB7tk) | [38,648](https://solscan.io/tx/4Hm62foYd5hoNqmEfLk51HhVVb5VHa5oTr81rjAKNNXyKFYwSrpXZhzFVwbk3WxRzEsiqGxHbn7B4eBop6RC1Sgx) |
+| take_offer (offer 1) | [**9,951**](https://solscan.io/tx/52ej6M3zFt5kgMGKUef9VGZdmZWqJdSoHCvCEB9P3btg7DSbvHkM24uk95W7HXjSX12XHmEmXATC7GLcQQ1U22kK) | [26,706](https://solscan.io/tx/4KLfVqTM2KmwgqF4xECWmNuZWYufsWcocdT5saamWdZQfRYhY7aTsyEyk5pVTxug6LJnngJhWDU7NMiPnZxu9sH2) | [31,628](https://solscan.io/tx/5f2VxEcPUfZbCVHpbYbUntVwfUN4k6ieetxSjdpJVwfck2tDuv2QTGbFFtNcy34Nn8d6bKSp5efzKDSbg7xj5TbJ) | [32,835](https://solscan.io/tx/3sJVTUvGRRtvYisFyqthvYQUZpeLmNN2UtXJq9TsQHW2TLP8YwtiuFGoPvu51w5YoZyJjKc3dM3zF6JXTFRFjc6H) |
+| make_offer (offer 2) | [20,205](https://solscan.io/tx/36mSJoMESxSLoxL5apVkoPzptAgFmUM9z2ZVuKpCadQajxbTF3T6BT93bw2ugHfLX7qSXvcBQ96kd8m22y3DsbTH) | [**19,645**](https://solscan.io/tx/PXPGNGCN3RN15L812K9Ho99Xz5YmUgMDaDy8aXuSg1kFgtdX42Z6foLLJkn8X9XB68xgeQsTBQhoDdUfRPKks2f) | [29,198](https://solscan.io/tx/2n38Urd1FsijNB2kbQy1b2cNHrvU7sXwYe5zH9SeyZUJRhUaD8TXSJGkvjEGYCTy3bdmAvEqqE27Ufgcxg3S3uFe) | [38,648](https://solscan.io/tx/185ZpYg3H1Ku4upHPBoBavrTczwzwxQiz7wjqqYWXd8MmxbimbLz7VvjuQdnqAGaAMy11G8M1QqPzXbrPof8gQb) |
+| refund_offer (offer 2) | [**5,478**](https://solscan.io/tx/55Q7pTfsew4F4N9DPB21BEqeHPANhkgQmUGAYVerFP73D7qMTp4eeo5CPMpYQqU7SLS4e49fuKtLkZ9XowbyoKET) | [13,387](https://solscan.io/tx/2cNkvA4xuFJBQzFcFTnLrxRzDU1q5617T8TCF5sBS7JeNzCPUxCPfzS37uv1RUg7xs9Mqyya6KDV9GSZxGiToevT) | [17,731](https://solscan.io/tx/Nj8RGLqEgbj8SEhd9hLcB2JQJY7YwkP1CnMdeJFBdsFhftntFqm1j1wAD1Mc715wrkPv2pFCWu93AF29oHQUDYr) | [20,576](https://solscan.io/tx/5on9Fxe6mADcbWwVn43yQ5wYtdWyx2u3Ry2hSniLJjRqoj2J55Hbgv4AbZoVZ5CDp2VrrghEkKRBvmXxjv1TynmY) |
+| escrow program's own part, 4 transactions | **28,118** | 36,956 | 93,273 | 102,926 |
 | program | [65ybkcg6…](https://solscan.io/account/65ybkcg6mQa9t5EuHtirRdvf2qAu12qRiK6wYBbGk16P) | [FrQwq3iU…](https://solscan.io/account/FrQwq3iUa8ZkWEne1y27webXTAyLgH4Hj6t986t6VS2G) | [5pnmi1Md…](https://solscan.io/account/5pnmi1MdxzXKmgX7ooRSE212rzZK8rb7nNpRTSMqP8V1) | [EG7M3sLL…](https://solscan.io/account/EG7M3sLLwB7MhmtzwYsaxbhZaFDbshL9hmVK79bQVyVq) |
 
-Most of make_offer is the Associated Token Account program creating the vault (about 13,500 CU in every version); it
-searches for the vault address's bump itself at 1,500 CU a try, which is why TypeSOL's offer 2 cost 1,500 more than
-offer 1 (its own part was 6,719 CU both times). The Pinocchio version takes the offer PDA's bump from the client instead
-of searching for it (its own part: 6,051 CU). Mainnet figures differ from the LiteSVM means above.
+Most of make_offer is the Associated Token Account program creating the vault. It searches for the vault address's
+bump itself at 1,500 CU a try, and every offer has its own vault, so that part varies from offer to offer in every
+version (13,585 to 22,585 CU of the make_offers above); programs that check the vault's address re-derive it, so
+take_offer and refund_offer vary with it too. The escrow program's own part is steadier: TypeSOL's make_offer spent
+6,620 CU of its own on both offers. The Pinocchio version takes the offer PDA's bump from the client instead of
+searching for it. Mainnet figures differ from the LiteSVM means above. Every run, including the one before the
+upgrade, is in [typesol/benchmarks](https://github.com/typesol/benchmarks) (`results/`).
 
 ## How it is tested
 
@@ -316,7 +332,9 @@ change.
 - The compiler, runtime and tooling have been through internal security reviews and are covered by the tests above.
 - They have **not been audited by an independent firm**. Do not put significant value behind programs built with
   TypeSOL until such an audit is published.
-- Audit your own programs as you would any Solana program.
+- Audit your own programs as you would any Solana program. What a compiled program can rely on, and what is left to
+  you, is in [docs/security-model.md](docs/security-model.md); [docs/audit.md](docs/audit.md) is the package for an
+  external audit.
 - Report vulnerabilities as described in [SECURITY.md](SECURITY.md).
 
 Not supported yet: see the end of [docs/language.md](docs/language.md#not-supported-yet).

package/SECURITY.md

@@ -9,6 +9,8 @@ TypeSOL generates programs that hold funds. Treat it accordingly.
   firm.** Do not put significant value behind programs built with it until an external audit of the compiler and
   runtime is published, and audit your own programs as you would any Solana program.
 - Only the latest 0.x release receives security fixes.
+- What a compiled program can rely on is specified in [docs/security-model.md](docs/security-model.md); the package
+  for an external audit is [docs/audit.md](docs/audit.md).
 
 ## Reporting a vulnerability
 

package/dist/cli.js

@@ -7,14 +7,15 @@ import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import ts from "typescript";
 import { build, CompileError, COMPILER_VERSION, generate, SBPF_VERSIONS, verifyBinary } from "./compiler/index.js";
-import { generateCpi } from "./cpigen.js";
-import { generatePort } from "./portgen.js";
-import { generateClient, writeClient } from "./clientgen.js";
+import { generateCpi } from "./tools/cpigen.js";
+import { generatePort } from "./tools/portgen.js";
+import { generateClient, writeClient } from "./tools/clientgen.js";
 import { buildIdl } from "./compiler/idl.js";
 import { decodeAddress, loadOrCreateKeypair, readKeypair } from "./keys.js";
-import { formatProfile, profileLogs } from "./profile.js";
+import { formatProfile, profileLogs } from "./tools/profile.js";
 import { TEMPLATE_NAMES } from "./templates.js";
 import { buildWorkspace, CONFIG, deployArgs, findWorkspace, programAddress, programForEntry, programPaths, scaffold } from "./workspace.js";
+import { clusterUrl, deployPreflight, doctorChecks, formatChecks, INSTALL_AGAVE, solanaConfig as readSolanaConfig, toolchainCheck } from "./tools/doctor.js";
 const ASSETS = fileURLToPath(new URL("../assets/", import.meta.url));
 /** A usage problem: printed with the command's help, exit code 2. */
 class UsageError extends Error {
@@ -65,9 +66,18 @@ const COMMANDS = {
                 .replace(/^_+|_+$/g, "")
                 .toLowerCase();
             const name = v.name ?? (/^[a-z]/.test(derived) ? derived : `p_${derived || "program"}`);
+            const rel = path.relative(process.cwd(), root) || ".";
             for (const f of scaffold(root, name, template))
-                log(`  created ${path.join(root, f)}`);
-            log(`\n  next: cd ${path.relative(process.cwd(), root) || "."} && npm install && npm test`);
+                log(`  created ${path.join(rel, f)}`);
+            const tools = toolchainCheck();
+            if (!tools.ok)
+                log(`\n  ! The Solana platform-tools are not installed yet; npm test compiles with them. Install once:\n` +
+                    (tools.fix ?? []).map((f) => `      ${f}`).join("\n"));
+            log(`\n  next:\n` +
+                (rel === "." ? "" : `    cd ${rel}\n`) +
+                `    npm install\n` +
+                `    npm test             # builds ${name} and runs its test in LiteSVM, a Solana runtime in-process\n` +
+                `    npx typesol doctor   # checks the toolchain, keypair and RPC before a deploy`);
             return 0;
         },
     },
@@ -166,6 +176,20 @@ const COMMANDS = {
             return 0;
         },
     },
+    doctor: {
+        usage: "typesol doctor [--url <rpc>] [--config <solana cli config>]",
+        help: [
+            "Check what building, testing and deploying need: Node.js, the platform-tools, the Solana CLI, its keypair, the RPC",
+            "(and the keypair's balance there) and the project. Each problem comes with the command that fixes it. Exit code 1",
+            "when building is impossible (Node.js or the platform-tools); a missing deploy piece is a warning.",
+        ].join("\n  "),
+        options: { url: { type: "string" }, config: { type: "string" } },
+        async run(v) {
+            const checks = await doctorChecks({ cwd: process.cwd(), url: v.url, config: v.config });
+            log(formatChecks(checks));
+            return checks.some((c) => !c.ok && !c.optional) ? 1 : 0;
+        },
+    },
     deploy: {
         usage: "typesol deploy [<program>…] [--url <rpc>] [--keypair <payer.json>] [--config <solana cli config>] [--sbpf v0|v1|v2] [--dry-run]",
         help: [
@@ -174,9 +198,20 @@ const COMMANDS = {
             "Needs the Agave CLI (`solana`) on PATH.",
         ].join("\n  "),
         options: { url: { type: "string" }, keypair: { type: "string" }, config: { type: "string" }, "dry-run": { type: "boolean" }, sbpf: { type: "string" } },
-        run(v, args) {
+        async run(v, args) {
             const ws = needWorkspace("deploy");
             const built = buildWorkspace(ws, names(ws, args), { sbpf: sbpfOf(v) });
+            if (!v["dry-run"]) {
+                // Before any transaction: the RPC answers and the payer can afford it, with what to do if not.
+                const cfg = solanaConfig(v.config);
+                const url = v.url ?? cfg.url;
+                if (url)
+                    await deployPreflight({
+                        url: clusterUrl(url),
+                        payer: v.keypair ?? cfg.keypair ?? path.join(os.homedir(), ".config/solana/id.json"),
+                        programs: built.map((b) => ({ soPath: b.result.soPath, address: b.address, name: b.paths.name })),
+                    });
+            }
             for (const b of built) {
                 const cliArgs = deployArgs(b.result.soPath, b.paths.keypair, { url: v.url, payer: v.keypair, config: v.config });
                 if (v["dry-run"]) {
@@ -189,7 +224,7 @@ const COMMANDS = {
                 }
                 catch (e) {
                     if (e.code === "ENOENT")
-                        throw new Error("`solana` was not found on PATH. Install the Agave CLI: https://docs.anza.xyz/cli/install");
+                        throw new Error(`\`solana\` was not found on PATH. Install the Agave CLI: ${INSTALL_AGAVE}`);
                     throw new Error(`solana program deploy failed for ${b.paths.name} (see its output above)`);
                 }
             }
@@ -217,7 +252,7 @@ const COMMANDS = {
                 throw new Error(`no signer keypair${keyFile ? ` at ${keyFile}` : ""}: pass --keypair, or set keypair_path in the Solana CLI config`);
             // Loaded only here: the other commands do not need an RPC client.
             const kit = await import("@solana/kit");
-            const { publishIdl, rpcChain } = await import("./idlpublish.js");
+            const { publishIdl, rpcChain } = await import("./tools/idlpublish.js");
             const signer = await kit.createKeyPairSignerFromBytes(readKeypair(keyFile));
             const chain = rpcChain(kit.createSolanaRpc(clusterUrl(rpcUrl)));
             for (const name of names(ws, args)) {
@@ -297,7 +332,7 @@ const COMMANDS = {
                     throw new Error("no RPC: pass --url, or set json_rpc_url in the Solana CLI config");
                 // Loaded only here: the other commands do not need an RPC client.
                 const kit = await import("@solana/kit");
-                const { fetchProgramIdl } = await import("./idlpublish.js");
+                const { fetchProgramIdl } = await import("./tools/idlpublish.js");
                 const found = await fetchProgramIdl(kit.createSolanaRpc(clusterUrl(rpcUrl)), kit.address(v.address));
                 console.error(`  IDL from ${found.source === "anchor" ? "Anchor's IDL account" : "the Program Metadata program"}`);
                 idl = found.idl;
@@ -360,7 +395,7 @@ const COMMANDS = {
                     throw new Error("no RPC: pass --url, or set json_rpc_url in the Solana CLI config");
                 // Loaded only here: the other commands do not need an RPC client.
                 const kit = await import("@solana/kit");
-                const { fetchDeployed } = await import("./onchain.js");
+                const { fetchDeployed } = await import("./tools/onchain.js");
                 const rpc = kit.createSolanaRpc(clusterUrl(rpcUrl));
                 const info = await fetchDeployed(rpc, address);
                 onChain = { address, info, rpc };
@@ -387,8 +422,8 @@ const COMMANDS = {
                 return same ? 0 : 3;
             const { info } = onChain;
             log(`  authority ${info.authority ?? "none: the program is immutable"}${info.slot !== undefined ? `; last deployed in slot ${info.slot}` : ""}`);
-            const { fetchIdl, metadataAddress } = await import("./idlpublish.js");
-            const { canonicalJson } = await import("./onchain.js");
+            const { fetchIdl, metadataAddress } = await import("./tools/idlpublish.js");
+            const { canonicalJson } = await import("./tools/onchain.js");
             // No canonical metadata account means nothing was published; one that cannot be read is an error, not "none".
             const at = await metadataAddress(onChain.address, null);
             const exists = (await onChain.rpc.getAccountInfo(at, { encoding: "base64" }).send()).value !== null;
@@ -492,32 +527,12 @@ function overrideFile(file, text) {
         sys.fileExists = fileExists;
     };
 }
-/** The Solana CLI's cluster monikers, as `solana --url` accepts them; anything else is used as given. */
-function clusterUrl(url) {
-    const monikers = {
-        "mainnet-beta": "https://api.mainnet-beta.solana.com",
-        m: "https://api.mainnet-beta.solana.com",
-        devnet: "https://api.devnet.solana.com",
-        d: "https://api.devnet.solana.com",
-        testnet: "https://api.testnet.solana.com",
-        t: "https://api.testnet.solana.com",
-        localhost: "http://127.0.0.1:8899",
-        l: "http://127.0.0.1:8899",
-    };
-    return monikers[url] ?? url;
-}
 /** json_rpc_url / keypair_path from a Solana CLI config (the given file, or the CLI's default one). */
 function solanaConfig(file) {
-    const configPath = file ?? path.join(os.homedir(), ".config/solana/cli/config.yml");
-    if (!existsSync(configPath)) {
-        if (file)
-            throw new UsageError(`${file} does not exist`);
-        return {};
-    }
-    const text = readFileSync(configPath, "utf8");
-    const get = (k) => new RegExp(`^${k}:\\s*["']?([^"'\\n]+?)["']?\\s*$`, "m").exec(text)?.[1];
-    const expand = (p) => (p?.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p);
-    return { url: get("json_rpc_url"), keypair: expand(get("keypair_path")) };
+    const cfg = readSolanaConfig(file);
+    if (file && !cfg.exists)
+        throw new UsageError(`${file} does not exist`);
+    return { url: cfg.url, keypair: cfg.keypair };
 }
 export async function main(argv) {
     const [cmd, ...rest] = argv;

package/dist/templates.js

@@ -1,6 +1,6 @@
 // Programs and tests that `typesol init --template <name>` writes. Each test runs its program in LiteSVM and covers its
 // main flow and at least one refused call, so a new project starts from something that passes and shows how to test.
-// The programs are copies of examples/ (test/workspace.test.ts checks they still match).
+// The programs are copies of examples/ (test/cli/workspace.test.ts checks they still match).
 export const TEMPLATE_NAMES = ["counter", "vault", "escrow"];
 /** Every test starts the same way: build the project's program into a LiteSVM with `typesol/testing`. */
 const testFile = (name, o) => `// Runs the program in LiteSVM (an in-process Solana runtime): \`npm test\`.

package/dist/testing.d.ts

@@ -19,7 +19,7 @@
 import anchor, { type Idl } from "@anchor-lang/core";
 import { type Address, type Instruction, type KeyPairSigner } from "@solana/kit";
 import { FailedTransactionMetadata, LiteSVM, TransactionMetadata } from "litesvm";
-import { type SvmConnection, svmConnection } from "./svmrpc.js";
+import { type SvmConnection, svmConnection } from "./tools/svmrpc.js";
 export { type SvmConnection, svmConnection };
 declare const BorshCoder: typeof anchor.BorshCoder;
 type BorshCoder = InstanceType<typeof BorshCoder>;

package/dist/testing.js

@@ -22,7 +22,7 @@ import { FailedTransactionMetadata, LiteSVM } from "litesvm";
 import { createHash } from "node:crypto";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { svmConnection } from "./svmrpc.js";
+import { svmConnection } from "./tools/svmrpc.js";
 import { buildWorkspace, findWorkspace } from "./workspace.js";
 export { svmConnection };
 // @anchor-lang/core is CommonJS: Node 22 cannot import its classes by name from an installed ES module.

package/dist/{clientgen.js → tools/clientgen.js}

@@ -18,7 +18,7 @@
  * sanitized comments.
  */
 import { mkdirSync, writeFileSync } from "node:fs";
-import { ANCHOR_ERRORS } from "./compiler/anchor-errors.js";
+import { ANCHOR_ERRORS } from "../compiler/anchor-errors.js";
 import path from "node:path";
 /** An IDL the generator refuses: malformed, unsafe to embed, or older than the 0.30 IDL format. */
 export class ClientIdlError extends Error {

package/dist/tools/doctor.d.ts

@@ -0,0 +1,45 @@
+export declare const INSTALL_AGAVE = "sh -c \"$(curl -sSfL https://release.anza.xyz/stable/install)\"";
+export interface Check {
+    ok: boolean;
+    /** A missing optional piece (the Solana CLI is only needed to deploy). */
+    optional?: boolean;
+    what: string;
+    detail: string;
+    fix?: string[];
+}
+/** The platform-tools the compiler needs: found, or what to run. */
+export declare function toolchainCheck(): Check;
+/** json_rpc_url / keypair_path from a Solana CLI config (the given file, or the CLI's default one). */
+export declare function solanaConfig(file?: string): {
+    url?: string;
+    keypair?: string;
+    file: string;
+    exists: boolean;
+};
+/** The Solana CLI's cluster monikers, as `solana --url` accepts them; anything else is used as given. */
+export declare function clusterUrl(url: string): string;
+/** Only the host: an RPC URL can carry an API key in its path or query, and these messages may be shared. */
+export declare function rpcHost(url: string): string;
+export declare function rpc<T>(url: string, method: string, params?: unknown[]): Promise<T>;
+/** fetch's "fetch failed" says little: the cause's code (ECONNREFUSED, ENOTFOUND, a timeout) says more. */
+export declare const errText: (e: unknown) => string;
+/**
+ * Before `solana program deploy`: the RPC answers, and the payer holds enough for the program's rent (a first deploy
+ * holds about twice the binary's rent while the buffer exists; an upgrade, the buffer's). Throws with what to do.
+ */
+export declare function deployPreflight(opts: {
+    url: string;
+    payer?: string;
+    programs: {
+        soPath: string;
+        address: string;
+        name: string;
+    }[];
+}): Promise<void>;
+/** Everything `typesol doctor` checks, in order. */
+export declare function doctorChecks(opts: {
+    cwd: string;
+    url?: string;
+    config?: string;
+}): Promise<Check[]>;
+export declare function formatChecks(checks: Check[]): string;

package/dist/tools/doctor.js

@@ -0,0 +1,229 @@
+// `typesol doctor` and the checks `init` and `deploy` run before they need something: Node, the platform-tools the
+// compiler builds with, the Solana CLI, its keypair and RPC, the project, and (with an RPC) whether it answers and the
+// payer can afford a deploy. Each problem comes with the command that fixes it.
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { findToolchain } from "../compiler/toolchain.js";
+import { base58, readKeypair } from "../keys.js";
+import { findWorkspace } from "../workspace.js";
+export const INSTALL_AGAVE = 'sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"';
+const MIN_NODE = [22, 12];
+/** The platform-tools the compiler needs: found, or what to run. */
+export function toolchainCheck() {
+    try {
+        const tc = findToolchain();
+        let version = "";
+        try {
+            version = execFileSync(tc.clang, ["--version"], { encoding: "utf8" })
+                .split("\n")[0]
+                .replace(/\s*\(.*$/, "");
+        }
+        catch {
+            /* the path is enough */
+        }
+        return { ok: true, what: "platform-tools", detail: version || tc.sdk };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            what: "platform-tools",
+            detail: e.message.split(". ")[0],
+            fix: [INSTALL_AGAVE, "cargo-build-sbf --version   # once: downloads the platform-tools TypeSOL compiles with"],
+        };
+    }
+}
+/** json_rpc_url / keypair_path from a Solana CLI config (the given file, or the CLI's default one). */
+export function solanaConfig(file) {
+    const configPath = file ?? path.join(os.homedir(), ".config/solana/cli/config.yml");
+    if (!existsSync(configPath))
+        return { file: configPath, exists: false };
+    const text = readFileSync(configPath, "utf8");
+    const get = (k) => new RegExp(`^${k}:\\s*["']?([^"'\\n]+?)["']?\\s*$`, "m").exec(text)?.[1];
+    const expand = (p) => (p?.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p);
+    return { url: get("json_rpc_url"), keypair: expand(get("keypair_path")), file: configPath, exists: true };
+}
+/** The Solana CLI's cluster monikers, as `solana --url` accepts them; anything else is used as given. */
+export function clusterUrl(url) {
+    const monikers = {
+        "mainnet-beta": "https://api.mainnet-beta.solana.com",
+        m: "https://api.mainnet-beta.solana.com",
+        devnet: "https://api.devnet.solana.com",
+        d: "https://api.devnet.solana.com",
+        testnet: "https://api.testnet.solana.com",
+        t: "https://api.testnet.solana.com",
+        localhost: "http://127.0.0.1:8899",
+        l: "http://127.0.0.1:8899",
+    };
+    return monikers[url] ?? url;
+}
+/** Only the host: an RPC URL can carry an API key in its path or query, and these messages may be shared. */
+export function rpcHost(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return "the RPC";
+    }
+}
+/** The cluster an RPC belongs to, for the airdrop hint (mainnet has none). */
+function clusterOf(url) {
+    const host = rpcHost(url);
+    if (/devnet/.test(host))
+        return "devnet";
+    if (/testnet/.test(host))
+        return "testnet";
+    if (/^(127\.0\.0\.1|localhost|0\.0\.0\.0)(:|$)/.test(host))
+        return "localhost";
+    return undefined;
+}
+export async function rpc(url, method, params = []) {
+    const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+        signal: AbortSignal.timeout(10_000),
+    });
+    const body = (await res.json());
+    if (body.error)
+        throw new Error(body.error.message);
+    return body.result;
+}
+/** fetch's "fetch failed" says little: the cause's code (ECONNREFUSED, ENOTFOUND, a timeout) says more. */
+export const errText = (e) => {
+    const err = e;
+    return err.cause?.code ?? err.cause?.message ?? (err.name === "TimeoutError" ? "no answer in 10 s" : err.message);
+};
+const sol = (lamports) => lamports === 0 ? "0 SOL" : lamports < 100_000 ? `${lamports} lamports` : `${(lamports / 1e9).toFixed(lamports < 1e7 ? 4 : 2)} SOL`;
+/** A cost, rounded up so the advice is enough. */
+const solUp = (lamports) => `${(Math.ceil(lamports / 1e7) / 100).toFixed(2)} SOL`;
+/**
+ * Before `solana program deploy`: the RPC answers, and the payer holds enough for the program's rent (a first deploy
+ * holds about twice the binary's rent while the buffer exists; an upgrade, the buffer's). Throws with what to do.
+ */
+export async function deployPreflight(opts) {
+    const host = rpcHost(opts.url);
+    try {
+        await rpc(opts.url, "getVersion");
+    }
+    catch (e) {
+        const local = clusterOf(opts.url) === "localhost";
+        throw new Error(`cannot reach ${host} (${errText(e)}). ` +
+            (local
+                ? "Start a local validator in another terminal: `solana-test-validator`, or deploy to devnet with --url devnet."
+                : "Check --url (or json_rpc_url in the Solana CLI config); for a test deploy use --url devnet or a local `solana-test-validator`."));
+    }
+    if (!opts.payer || !existsSync(opts.payer))
+        return; // the Solana CLI reports a missing keypair itself
+    const payer = base58(readKeypair(opts.payer).subarray(32));
+    let need = 0;
+    for (const p of opts.programs) {
+        const size = statSync(p.soPath).size;
+        const exists = (await rpc(opts.url, "getAccountInfo", [p.address, { encoding: "base64", dataSlice: { offset: 0, length: 0 } }])).value;
+        const rent = await rpc(opts.url, "getMinimumBalanceForRentExemption", [size + 45]);
+        need += exists ? rent : 2 * rent;
+    }
+    need += 5_000_000; // fees for the buffer writes
+    const balance = (await rpc(opts.url, "getBalance", [payer])).value;
+    if (balance >= need)
+        return;
+    const cluster = clusterOf(opts.url);
+    const airdrop = cluster ? ` Get test SOL: \`solana airdrop ${Math.max(2, Math.ceil((need - balance) / 1e9))} ${payer} --url ${cluster}\`.` : "";
+    throw new Error(`the payer ${payer} has ${sol(balance)} on ${host}; deploying needs about ${solUp(need)} (rent, mostly returned when a buffer closes).${airdrop}`);
+}
+/** Everything `typesol doctor` checks, in order. */
+export async function doctorChecks(opts) {
+    const checks = [];
+    const [major, minor] = process.versions.node.split(".").map(Number);
+    const nodeOk = major > MIN_NODE[0] || (major === MIN_NODE[0] && minor >= MIN_NODE[1]);
+    checks.push({
+        ok: nodeOk,
+        what: "Node.js",
+        detail: process.versions.node,
+        fix: nodeOk ? undefined : [`install Node.js ${MIN_NODE.join(".")} or later (https://nodejs.org)`],
+    });
+    checks.push(toolchainCheck());
+    let solanaVersion;
+    try {
+        solanaVersion = execFileSync("solana", ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })
+            .split(" (")[0]
+            .trim();
+    }
+    catch {
+        /* not installed */
+    }
+    checks.push(solanaVersion
+        ? { ok: true, what: "Solana CLI", detail: solanaVersion }
+        : { ok: false, optional: true, what: "Solana CLI", detail: "not on PATH (needed to deploy, not to build or test)", fix: [INSTALL_AGAVE] });
+    const cfg = solanaConfig(opts.config);
+    const keypair = cfg.keypair ?? path.join(os.homedir(), ".config/solana/id.json");
+    if (existsSync(keypair)) {
+        let address = "";
+        try {
+            address = base58(readKeypair(keypair).subarray(32));
+        }
+        catch (e) {
+            checks.push({ ok: false, optional: true, what: "keypair", detail: e.message });
+        }
+        if (address)
+            checks.push({ ok: true, what: "keypair", detail: `${address} (${keypair.replace(os.homedir(), "~")})` });
+    }
+    else
+        checks.push({
+            ok: false,
+            optional: true,
+            what: "keypair",
+            detail: `none at ${keypair.replace(os.homedir(), "~")} (the deploy payer)`,
+            fix: ["solana-keygen new"],
+        });
+    const url = opts.url ? clusterUrl(opts.url) : cfg.url;
+    if (!url)
+        checks.push({ ok: false, optional: true, what: "RPC", detail: "none set (deploy takes --url)", fix: ["solana config set --url devnet"] });
+    else {
+        const cluster = clusterOf(url);
+        try {
+            const v = await rpc(url, "getVersion");
+            checks.push({ ok: true, what: "RPC", detail: `${rpcHost(url)} (solana-core ${v["solana-core"]})` });
+            if (existsSync(keypair)) {
+                const balance = (await rpc(url, "getBalance", [base58(readKeypair(keypair).subarray(32))])).value;
+                checks.push(balance > 0
+                    ? { ok: true, what: "balance", detail: sol(balance) }
+                    : {
+                        ok: false,
+                        optional: true,
+                        what: "balance",
+                        detail: `0 SOL on ${rpcHost(url)}`,
+                        fix: [
+                            cluster && cluster !== "localhost"
+                                ? `solana airdrop 2 --url ${cluster}`
+                                : cluster
+                                    ? "solana airdrop 2 --url localhost"
+                                    : "fund the keypair above",
+                        ],
+                    });
+            }
+        }
+        catch (e) {
+            checks.push({
+                ok: false,
+                optional: true,
+                what: "RPC",
+                detail: `${rpcHost(url)} does not answer (${errText(e)})`,
+                fix: cluster === "localhost" ? ["solana-test-validator   # in another terminal"] : ["pass --url devnet, or fix json_rpc_url in the Solana CLI config"],
+            });
+        }
+    }
+    const ws = findWorkspace(opts.cwd);
+    checks.push(ws
+        ? { ok: true, what: "project", detail: `${path.relative(opts.cwd, ws.file) || ws.file}: ${Object.keys(ws.programs).join(", ")}` }
+        : { ok: true, optional: true, what: "project", detail: "none here (typesol init <dir> creates one)" });
+    return checks;
+}
+export function formatChecks(checks) {
+    const mark = (c) => (c.ok ? "ok " : c.optional ? " ! " : "ERR");
+    const width = Math.max(...checks.map((c) => c.what.length));
+    return checks
+        .map((c) => `  ${mark(c)}  ${c.what.padEnd(width)}  ${c.detail}${(c.fix ?? []).map((f) => `\n${" ".repeat(width + 9)}${f}`).join("")}`)
+        .join("\n");
+}

package/dist/{portgen.js → tools/portgen.js}

@@ -9,7 +9,7 @@
  * data enum, a COption) it says so in a note and a comment.
  */
 import { createHash } from "node:crypto";
-import { cNameProblem } from "./compiler/analyze.js";
+import { cNameProblem } from "../compiler/analyze.js";
 const RESERVED = new Set("break case catch class const continue debugger default delete do else enum export extends false finally for function if import in instanceof new null return super switch this throw true try typeof var void while with yield let static implements interface package private protected public await".split(" "));
 const camel = (s) => s.replace(/[_-]+([a-zA-Z0-9])/g, (_, c) => c.toUpperCase()).replace(/^[A-Z]/, (c) => c.toLowerCase());
 const pascal = (s) => camel(s).replace(/^[a-z]/, (c) => c.toUpperCase());

package/dist/workspace.js

@@ -13,7 +13,7 @@
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
-import { writeClient } from "./clientgen.js";
+import { writeClient } from "./tools/clientgen.js";
 import { build, COMPILER_VERSION, SBPF_VERSIONS } from "./compiler/index.js";
 import { loadOrCreateKeypair } from "./keys.js";
 import { TEMPLATES } from "./templates.js";

package/docs/architecture.md

@@ -26,13 +26,13 @@ program.so + program.build.json (manifest: versions, sha256 of sources and binar
 
 | Path | Contents |
 | --- | --- |
-| `src/` | The compiler (`src/compiler/`) and the tools around it: CLI, workspace, client, CPI and port generators, testing, IDL publishing (source map below) |
+| `src/` | The compiler (`src/compiler/`); the CLI, projects, init templates and `typesol/testing` at the top; generators and chain tooling in `src/tools/` (client, CPI and port generators, IDL publishing, on-chain reads, profiling, the LiteSVM RPC). Source map below |
 | `runtime/` | `typesol_rt.h`, the C runtime every program includes ([runtime.md](runtime.md)) |
 | `lib/` | `typesol.d.ts`, the language surface programs typecheck against |
 | `ts-plugin/` | The editor plugin (`typesol/ts-plugin`) |
 | `examples/` | Example programs; the `typesol init` templates are copies of three of them |
-| `test/` | The test suite: `fixtures/` (programs the tests compile), `ports/` (TypeSOL rewrites of solana-developers/program-examples), `golden/` (pinned generated clients), `programs/` (third-party program binaries, see its SOURCES.md) |
-| `bench/anchor/` | Anchor twins of the counter, vault and escrow examples, for the differential tests (`pnpm bench:anchor`) and the zero-copy client test; the benchmarks themselves are in [typesol/benchmarks](https://github.com/typesol/benchmarks) |
+| `test/` | The test suite, by subject: `language/`, `security/`, `examples/`, `integrations/` (token, Metaplex, oracle and other CPIs), `client/`, `cli/`, `porting/`, `verification/` (differential and fuzz tests). Shared: `harness.ts` and the `*-helpers.ts`, `fixtures/` (programs the tests compile), `ports/` (TypeSOL rewrites of solana-developers/program-examples), `golden/` (pinned generated C and clients), `programs/` (third-party program binaries, see its SOURCES.md), `anchor-twins/` (below) |
+| `test/anchor-twins/` | Anchor twins of the counter, vault and escrow examples, for the differential tests (`pnpm build:twins`) and the zero-copy client test; the benchmarks themselves are in [typesol/benchmarks](https://github.com/typesol/benchmarks) |
 | `scripts/` | `smoke.ts` and `localnet.sh` (a local validator run), `fetch-programs.sh` (third-party binaries), `readme-bench.ts` (the README numbers) |
 | `docs/` | User and contributor documentation (also published on typesol.com) |
 | `assets/` | The CLI's logo and the README images (`readme/`, generated) |
@@ -53,17 +53,17 @@ program.so + program.build.json (manifest: versions, sha256 of sources and binar
 | `src/compiler/index.ts` | The compiler's API (`generate`, `build`, `verifyBinary`, the build manifest). |
 | `runtime/typesol_rt.h` | The C runtime: error codes, word-wise memory helpers, the entry point's input parser (`ts_deserialize`), account checks, checked math, Borsh helpers, CPIs (System, Token, Token-2022, ATA, Metaplex), oracles and the heap allocator. Header-only and `static inline`, so unused code is dropped. |
 | `src/workspace.ts` | `typesol.json` projects, program keypairs, `typesol init` templates and deploy arguments. |
-| `src/cpigen.ts` | `typesol cpi`: reads an Anchor IDL and writes typed TypeSOL CPI helpers. |
-| `src/clientgen.ts` | The TypeScript client (`<name>.client.ts`, [client.md](client.md)): reads an IDL, validates it (it may come from anywhere), and writes one `@solana/kit` file. Not part of the compiler core: `workspace.ts` and the CLI write it after `build()`, and `typesol client` writes it for any IDL. |
-| `src/idlpublish.ts` | `typesol idl publish` through the Program Metadata program, and reading a program's IDL back from the chain (Program Metadata or Anchor's IDL account) for `typesol client --address`. |
-| `src/portgen.ts` | `typesol port`: a TypeSOL program skeleton from an Anchor IDL (structs, enums, errors, events, one function per instruction). |
+| `src/tools/cpigen.ts` | `typesol cpi`: reads an Anchor IDL and writes typed TypeSOL CPI helpers. |
+| `src/tools/clientgen.ts` | The TypeScript client (`<name>.client.ts`, [client.md](client.md)): reads an IDL, validates it (it may come from anywhere), and writes one `@solana/kit` file. Not part of the compiler core: `workspace.ts` and the CLI write it after `build()`, and `typesol client` writes it for any IDL. |
+| `src/tools/idlpublish.ts` | `typesol idl publish` through the Program Metadata program, and reading a program's IDL back from the chain (Program Metadata or Anchor's IDL account) for `typesol client --address`. |
+| `src/tools/portgen.ts` | `typesol port`: a TypeSOL program skeleton from an Anchor IDL (structs, enums, errors, events, one function per instruction). |
 | `src/templates.ts` | The programs and tests `typesol init --template` writes (copies of `examples/`; a test checks they match). |
-| `src/svmrpc.ts` | `svmConnection`: a kit RPC and subscriptions pair answered by LiteSVM, so generated clients run in tests (exported by `typesol/testing`). |
+| `src/tools/svmrpc.ts` | `svmConnection`: a kit RPC and subscriptions pair answered by LiteSVM, so generated clients run in tests (exported by `typesol/testing`). |
 | `src/keys.ts` | Base58 and program keypair helpers. |
 | `ts-plugin/index.js` | `typesol/ts-plugin` (CommonJS, loaded by tsserver): runs `typesol check --json --stdin` on program entries and adds the diagnostics. |
 | `src/testing.ts` | `typesol/testing`: LiteSVM test helpers for projects (accounts by name from the IDL, plain values). |
-| `src/onchain.ts` | `typesol verify --address`: a deployed program's ELF, authority and deploy slot under loader v2, v3 or v4. |
-| `src/profile.ts` | Turns `--profile` logs into compute units per source line. |
+| `src/tools/onchain.ts` | `typesol verify --address`: a deployed program's ELF, authority and deploy slot under loader v2, v3 or v4. |
+| `src/tools/profile.ts` | Turns `--profile` logs into compute units per source line. |
 | `src/cli.ts` | Command parsing. Every command has strict options, `--help`, and exit codes 0 (success), 1 (failure), 2 (usage error) and 3 (verify mismatch). |
 
 ## The emitter
@@ -123,7 +123,7 @@ These invariants are easy to break. Each one has tests.
 3. Put any C helper in `runtime/typesol_rt.h` as `static inline`, returning `uint64_t` (`SUCCESS` or an error code)
    so that callers can wrap it in `TS_TRY`.
 4. Add an execution test that compiles a fixture under `test/fixtures/` and runs it in LiteSVM. Add a diagnostics
-   case in `test/diagnostics.test.ts` for each misuse you reject.
+   case in `test/language/diagnostics.test.ts` for each misuse you reject.
 5. Document it in `docs/language.md` and add a line to `CHANGELOG.md`.
 
 ### Add an account constraint
@@ -145,7 +145,7 @@ These invariants are easy to break. Each one has tests.
 ### Change generated C
 
 `test/golden/counter.c` pins the output for the counter example. Run
-`UPDATE_GOLDEN=1 pnpm test test/diagnostics.test.ts`, review the diff, and commit it with the change.
+`UPDATE_GOLDEN=1 pnpm test test/language/diagnostics.test.ts`, review the diff, and commit it with the change.
 
 For refactors that should not change behaviour, compare binaries: build every example and fixture before and after
 the change. The sha256 values in the `*.build.json` manifests must not change.
@@ -154,12 +154,12 @@ the change. The sha256 values in the `*.build.json` manifests must not change.
 
 | Files | What they cover |
 | --- | --- |
-| `test/<feature>.test.ts` | Execution tests. Each compiles fixtures and runs them in LiteSVM through `test/harness.ts`. |
-| `test/diagnostics.test.ts` | Every rejected construct, plus the golden C. |
-| `test/hardening.test.ts`, `test/regressions.test.ts` | Attacks and edge cases that once failed. Keep each as a negative test. |
-| `test/fuzz-*.test.ts`, `test/differential.test.ts` | Randomized checks against BigInt, a TypeScript state model, and the Anchor twins in `bench/anchor`. See [testing.md](testing.md). |
+| `test/<subject>/<feature>.test.ts` | Execution tests. Each compiles fixtures and runs them in LiteSVM through `test/harness.ts`. |
+| `test/language/diagnostics.test.ts` | Every rejected construct, plus the golden C. |
+| `test/security/hardening.test.ts`, `test/security/regressions.test.ts` | Attacks and edge cases that once failed. Keep each as a negative test. |
+| `test/verification/fuzz-*.test.ts`, `test/verification/differential.test.ts` | Randomized checks against BigInt, a TypeScript state model, and the Anchor twins in `test/anchor-twins`. See [testing.md](testing.md). |
 | `scripts/smoke.ts` | End to end against a real `solana-test-validator` (`scripts/localnet.sh`). |
 
 Some tests need optional inputs and are skipped without them:
 - `pnpm fetch:programs` downloads the Metaplex programs, which cannot be redistributed.
-- `pnpm bench:anchor` builds the Anchor twins and needs Rust and Anchor.
+- `pnpm build:twins` builds the Anchor twins and needs Rust and Anchor.

package/docs/audit.md

@@ -0,0 +1,90 @@
+# Audit package
+
+For a security firm reviewing TypeSOL. TypeSOL compiles a subset of TypeScript to C and then to Solana SBF; every
+program it builds includes one C runtime header. The question for an audit is whether a program compiled by TypeSOL
+can be made to do something its source and [the security model](security-model.md) say it cannot. Programs written
+with TypeSOL are out of scope; their authors audit them.
+
+## Scope
+
+In order of priority. Line counts at 0.25.0.
+
+| Priority | Component | Files | Lines | Why |
+| --- | --- | --- | ---: | --- |
+| 1 | C runtime | `runtime/typesol_rt.h` | 1,740 | In every program: input parsing, account checks, checked arithmetic, PDAs, system and token CPIs, account creation, resizing and closing, oracles, signature checks, the heap |
+| 1 | Instruction prologue and constraints | `src/compiler/emit/function.ts` | 584 | Which checks each account parameter gets, and their order |
+| 1 | Account data, Vecs and assignment | `src/compiler/emit/storage.ts`, `statements.ts`, `base.ts` | 2,296 | Reads and writes of account data, growable Vec layout and resizing, references and aliasing, closure and helper expansion |
+| 1 | Calls and CPIs | `src/compiler/emit/calls.ts`, `cpi.ts` | 4,276 | Built-ins, remaining accounts, `invoke` and its account flags, signer seeds, token and Metaplex CPIs, account creation |
+| 1 | Expressions | `src/compiler/emit/expressions.ts`, `shared.ts`, `borsh.ts` | 1,512 | Checked arithmetic and casts, Borsh encoding of arguments and `@layout borsh` accounts |
+| 2 | Front end | `src/compiler/analyze.ts`, `model.ts` | 2,202 | What the language accepts; constraints and account types as parsed from the source |
+| 2 | Interface | `src/compiler/idl.ts`, `src/tools/clientgen.ts` | 2,211 | The IDL and the generated client must describe the program exactly (a mismatch can make clients sign the wrong thing) |
+| 3 | Build and tooling | `src/compiler/toolchain.ts`, `src/cli.ts`, `src/workspace.ts`, `src/tools/` | | Build flags, deploy and verification commands |
+
+The language surface is `lib/typesol.d.ts` (1,711 lines): every type and built-in a program can use, with its
+documented behavior. [docs/language.md](language.md) is the reference; [docs/architecture.md](architecture.md) maps
+the code, [docs/runtime.md](runtime.md) the runtime's conventions.
+
+Out of scope: the Solana runtime, platform-tools (clang, lld), the TypeScript compiler, and programs written with
+TypeSOL.
+
+## What to check
+
+The guarantees in [security-model.md](security-model.md), each of which should hold for every program the compiler
+accepts. Areas where a bug would be most damaging, and where earlier internal reviews found the issues listed below:
+
+- **Account checks**: every parameter type and constraint, also when an account only reaches a helper, a closure or a
+  CPI; optional accounts; the duplicate-writable check.
+- **Aliasing**: two views of one account (parameters, remaining accounts, references held across a call), writes
+  through a place the right side moved.
+- **Account data layout**: growable Vecs after the fixed fields, their lengths against the account size, resizing and
+  the Vecs that follow, `@layout borsh` accounts.
+- **Arithmetic**: every operator and cast at every width, compound assignment, `mulDiv`, rent.
+- **CPIs and signing**: signer-seed arrays (including their reuse across statements), account flags in `invoke`,
+  account creation on pre-funded addresses, closing.
+- **The runtime's parsing**: instruction data, the serialized accounts, Token-2022 extension data, oracle accounts and
+  the instructions sysvar.
+
+## Earlier reviews
+
+Internal reviews, by the maintainers, in October 2026. Their findings and fixes are in the CHANGELOG:
+
+- **0.25.0** (runtime and emitted checks): two Medium issues fixed, a remaining account loaded mutably twice through
+  the same slot, and a Vec element written after its right side resized the Vec; plus a token program ambiguity,
+  `mint::token_program`, oracle options and documentation of `requirePda`, Merkle leaves and `createIfNeeded`.
+- **0.24.0** (compiler review): helper and closure expansion scoped to their own module, stale struct references
+  across Vec moves refused, account-shadowing parameters refused; client SDK hardening.
+- Earlier releases: see `test/security/regressions.test.ts` and `test/security/hardening.test.ts`, which keep every
+  attack that once worked as a failing transaction.
+
+## Evidence
+
+- **Tests**: 570, by subject under `test/` (`docs/architecture.md`). `test/security/` holds the attacks.
+- **Differential tests**: the same transactions to TypeSOL and to Anchor twins (`test/anchor-twins`), comparing
+  outcomes, account contents and balances after every step.
+- **Model-based fuzzing** (`test/verification/`): arithmetic against BigInt at every width; honest and hostile action
+  sequences against state models with value conservation; account layout with two growable Vecs and aliasing through
+  remaining accounts. Each run prints its seed (`FUZZ_SEED`), `pnpm fuzz` runs them wide.
+- **Ported programs**: all 46 programs of solana-developers/program-examples, run through their original tests' flows
+  and failure paths ([test/ports/README.md](../test/ports/README.md)).
+- **Four-way comparison**: [typesol/benchmarks](https://github.com/typesol/benchmarks) runs 17 of those programs in
+  TypeSOL, Anchor, native Rust and Pinocchio, requires the same outcome, and records how each refuses the hostile calls
+  and with which error.
+
+## Running it
+
+```sh
+git clone https://github.com/typesol/typesol && cd typesol
+pnpm install && pnpm build
+pnpm fetch:programs        # Metaplex binaries for the token-metadata, Core and Bubblegum tests
+pnpm build:twins           # the Anchor twins (Rust + Anchor 1.0.2)
+pnpm test                  # everything; CI runs it on Ubuntu (Node 22, 24) per change, macOS daily
+pnpm fuzz                  # the randomized checks, wide
+```
+
+`node dist/cli.js build <program.ts> --out <dir>` writes the generated C next to the binary, which is the most direct
+way to review what a construct compiles to; `test/golden/counter.c` is a pinned example.
+
+## Contact
+
+Coordinate through a private advisory on https://github.com/typesol/typesol/security, or report findings the same way
+(SECURITY.md).

package/docs/case-study-escrow.md

@@ -166,7 +166,7 @@ is marked PORTED in [the ports table](../test/ports/README.md).
 
 Two independent checks run the original and the port against each other.
 
-- **The port's own test** ([`test/ports-tokens.test.ts`](../test/ports-tokens.test.ts)) runs the upstream flow with SPL
+- **The port's own test** ([`test/porting/ports-tokens.test.ts`](../test/porting/ports-tokens.test.ts)) runs the upstream flow with SPL
   Token mints and again with Token-2022 mints: make, take (creating the taker's and the maker's missing token accounts),
   make again, a refund attempt by someone other than the maker, and the refund. It checks balances, the decoded offer
   and that offer and vault are closed.

package/docs/cli.md

@@ -6,12 +6,13 @@ error. Exit codes: **0** success, **1** failure (compile errors, failed deploy,
 
 | Command | What it does |
 | --- | --- |
-| `typesol init [<dir>] [--name <program>] [--template counter\|vault\|escrow]` | Create a project: `typesol.json`, `programs/<name>.ts`, `tests/<name>.test.ts` (LiteSVM), `package.json`, `tsconfig.json`, `programs/tsconfig.json` (with the editor plugin) and `.gitignore`. `<name>` must be snake_case; by default it is derived from `<dir>` (`my-app` → `my_app`). The template picks the program and its test: `counter` (default, a PDA counter per user), `vault` (SOL at a PDA: deposit, withdraw above rent, close) or `escrow` (SPL tokens: make, take, refund, the offer PDA signing for its vault). Refuses to overwrite files. |
+| `typesol init [<dir>] [--name <program>] [--template counter\|vault\|escrow]` | Create a project: `typesol.json`, `programs/<name>.ts`, `tests/<name>.test.ts` (LiteSVM), `package.json`, `tsconfig.json`, `programs/tsconfig.json` (with the editor plugin) and `.gitignore`. `<name>` must be snake_case; by default it is derived from `<dir>` (`my-app` → `my_app`). The template picks the program and its test: `counter` (default, a PDA counter per user), `vault` (SOL at a PDA: deposit, withdraw above rent, close) or `escrow` (SPL tokens: make, take, refund, the offer PDA signing for its vault). Refuses to overwrite files. It warns, with the install commands, when the platform-tools that building needs are missing. |
+| `typesol doctor [--url <rpc>] [--config <cli config>]` | Check what building, testing and deploying need: Node.js, the platform-tools, the Solana CLI, its keypair, the RPC (`--url`, a cluster moniker, or the CLI config) and the keypair's balance there, and the project. Each problem is printed with the command that fixes it. Exit code 1 when building is impossible (Node.js or the platform-tools missing); deploy pieces are warnings. |
 | `typesol build [<program>…] [--sbpf v0\|v1\|v2] [--profile] [--quiet]` | In a project: build every program (or those named) into `<out>/<name>/`: `<name>.so`, `<name>.json` (Anchor IDL), `<name>.client.ts` (TypeScript client, see [client.md](client.md)), `<name>.c`, `<name>.build.json`. The first build creates `<out>/deploy/<name>-keypair.json` and records the address in `typesol.json`; later builds refuse a missing or different keypair. |
 | `typesol build <file.ts> [--out <dir>] [--program-id <keypair.json>] [--sbpf …] [--profile]` | Outside a project (or a file that is not one of its programs): build that file. A project program's `.ts` builds as that program. |
 | `typesol check <file.ts> [--json] [--stdin]` | Type-check and validate without building. `--json` prints `{ ok, diagnostics: [{ file, line, column, message }] }`; `--stdin` checks the text given on stdin as that file (its imports come from disk). |
 | `typesol emit-c <file.ts> [--out <file.c>] [--profile]` | Print or write the generated C. |
-| `typesol deploy [<program>…] [--url <rpc>] [--keypair <payer.json>] [--config <cli config>] [--dry-run] [--sbpf …]` | Build, then `solana program deploy --use-rpc` at the program keypair's address. Deploying again upgrades (the payer must be the upgrade authority). `--dry-run` builds and prints the commands. Needs `solana` on PATH. |
+| `typesol deploy [<program>…] [--url <rpc>] [--keypair <payer.json>] [--config <cli config>] [--dry-run] [--sbpf …]` | Build, then `solana program deploy --use-rpc` at the program keypair's address. Deploying again upgrades (the payer must be the upgrade authority). `--dry-run` builds and prints the commands. Before sending anything it checks that the RPC answers and that the payer holds enough for the rent (about twice the binary's on a first deploy, while the buffer exists), and says what to do if not (start `solana-test-validator`, `solana airdrop` on devnet or a local validator). Needs `solana` on PATH. |
 | `typesol idl publish [<program>…] [--url <rpc>] [--keypair <authority.json>] [--config <cli config>] [--non-canonical]` | Compile (the binary is not rebuilt), then write each IDL to the Program Metadata program (seed `idl`). Canonical IDLs must be signed by the upgrade authority. Defaults come from the Solana CLI config (`~/.config/solana/cli/config.yml`). |
 | `typesol cpi <idl.json> [--out <file.ts>] [--prefix <name>] [--address <base58>]` | Generate TypeSOL helpers that call another program from its IDL. Unsupported instructions are listed on stderr. |
 | `typesol port <idl.json> [--out <file.ts>]` | A TypeSOL program skeleton from an Anchor IDL (0.30+/1.x), to port an Anchor program: account structs, enums, errors, events and one function per instruction with its accounts and arguments, each body `require(false, …NotPorted)` until written. Instruction discriminators (an explicit `@discriminator` when the name derives another), account names and error codes are kept, so existing clients keep working where the layouts match; notes on stderr list where they do not (Borsh `String`/`Option` in account data, a `Vec` that is not the last field, custom discriminators or error codes). |

package/docs/runtime.md

@@ -56,4 +56,4 @@ In file order:
 - A change that alters behavior (a result, an error code, a log line, account bytes) is a language change and goes
   in the CHANGELOG as one. One that only changes cost says so: "same results".
 - New error codes: add the `#define` here, the row in [errors.md](errors.md) and the name in the compiler's runtime
-  error list (`TYPESOL_ERRORS` in `src/clientgen.ts`), so clients name it (a test checks every code has a name).
+  error list (`TYPESOL_ERRORS` in `src/tools/clientgen.ts`), so clients name it (a test checks every code has a name).

package/docs/security-model.md

@@ -0,0 +1,97 @@
+# Security model
+
+What a program compiled by TypeSOL can rely on, who is trusted, and what is left to the program's author. This is the
+specification the tests check and an audit measures the compiler against; [audit.md](audit.md) is the package for
+auditors, [SECURITY.md](../SECURITY.md) how to report a problem.
+
+## Trust
+
+| Party | Trusted for |
+| --- | --- |
+| The program's author | the program's logic: what it allows, to whom, for how much |
+| TypeSOL (this repository) | that the binary does what the source and these guarantees say, and nothing an attacker can steer beyond it |
+| The toolchain | the TypeScript compiler API (parsing, types), Agave platform-tools (clang, lld), Node.js |
+| The Solana runtime | account ownership and signer flags as passed, the loader's account serialization, CPI privilege rules, sysvars |
+
+Everything a transaction carries is attacker-controlled: the instruction data, which accounts are passed in which
+slots (any account, repeated or not), the flags the runtime then enforces, the data of accounts the program does not
+own, remaining accounts, and what another program returns or writes.
+
+## Guarantees
+
+Each holds for every instruction of every program the compiler accepts. A break of any of them is a security bug
+(SECURITY.md).
+
+### Before the body runs
+
+1. **Account count.** Fewer accounts than parameters fail (3005); more than 32 in total fail before parsing (5113).
+2. **Account types.** Each parameter is checked for what its type says: `Signer` signed (3010); `Mut<…>` writable
+   (2000); a program account (`Account<T>`, `Mut<T>`) owned by this program (3007), initialized (3012), with `T`'s
+   discriminator (3002) and at least its size (3003); `TokenAccount` / `Mint` owned by SPL Token or Token-2022 and an
+   initialized account of that kind (3007 / 3003); program parameters at their fixed address and executable
+   (3008 / 3009); `SystemAccount` owned by the System Program (3011); `Zeroed<T>` owned, all-zero discriminator and
+   rent-exempt.
+3. **No aliasing.** Two writable parameters are never the same account (2040), whatever slots the transaction uses.
+4. **Arguments.** Every argument is length-checked before it is read; strings are valid UTF-8; booleans, enums and
+   options have valid tags (102).
+5. **Constraints.** `Seeds` (2006, with the stored or the canonical bump), `Ata` (2015 / 2009 / 2014), `HasOne`
+   (2001), `Owner` (2004), `Executable` (2007), `Address` (2012), `TokenOf` / `MintOf` (2014–2017, 2021, 2022) hold
+   before the body, per account in Anchor's order ([errors.md](errors.md#which-error-a-transaction-gets)). A
+   constraint naming an optional account is refused at compile time, so leaving the account out cannot skip it.
+
+### While it runs
+
+6. **Arithmetic.** Every `+ - * / % **`, compound assignment, `++` / `--`, unary minus, shift and cast is checked:
+   overflow and lost bits fail (5100), division by zero fails (5101), a cast out of range fails (4102). There is no
+   unchecked integer operation in the language.
+7. **Bounds.** Every index into an array, Vec, FixedVec or remaining-account list is checked (5104); a
+   growable Vec's stored length is checked against the account's size before it is used (3003).
+8. **Account creation.** `create` / `createIfNeeded` is a top-level statement, and the account cannot be read or
+   written before it (compile error). Creation refuses an account that already exists (3000), and an address someone
+   pre-funded still gets created. `createIfNeeded` on an existing account re-derives the canonical PDA and checks
+   owner, discriminator and size (token accounts: mint and owner; mints: decimals, authorities and the extensions it
+   names).
+9. **Writes through references.** A place is never written after the code that computes its value may have moved it:
+   replacing or resizing what a live reference points into is a compile error, as is writing a Vec element with a
+   right side that may resize the Vec.
+10. **Remaining accounts.** Writing one (`.lamports`, `loadAccountMut`) checks it is writable (3006) and not another
+    account of the instruction (2040); `loadAccountMut` loads a given account once per instruction (2040);
+    `loadAccount<T>` checks owner, discriminator and size, and validates the data as instruction arguments are.
+11. **Growth.** An account grows by at most 10 KiB per instruction (3016), the payer is a `Mut<Signer>`, new bytes are
+    zero and the new rent is paid; shrinking keeps the lamports in the account.
+12. **CPIs.** A program signs only for its own PDAs (the runtime enforces it; the seeds are those written in the
+    source). `invoke` marks an account writable or signer only when the parameter is `Mut` / `Signer` or the program
+    signs for it; remaining accounts keep the flags they were passed with, or are checked for the role requested.
+    Return data is read only from the program named, at the expected size (5106).
+13. **Events.** `emitCpi` is accepted only from this program's event-authority PDA, signed (2002).
+
+### When it ends
+
+14. **Closing.** A `CloseTo<…>` or `close(…)` account has its lamports moved to the destination, its data zeroed and
+    its owner reset to the System Program on every successful return, so it cannot be revived as the same account.
+15. **No silent success.** Every failed check returns its error code and the transaction fails: no code path continues
+    or returns success after a failed check or CPI.
+
+## Left to the author
+
+- **Logic.** Who may call what, limits, prices, fees. TypeSOL checks what the types and constraints say, nothing more.
+- **`AccountInfo` / `UncheckedProgram`.** Unchecked by design, as in Anchor: check what you rely on.
+- **`requirePda(account, seeds, bump)`.** Any valid bump passes (Anchor's `bump = expr`). Use a stored bump, never one
+  from the arguments.
+- **Oracles.** `pythPrice` checks verification, feed and age (pass the exponent you scale by); the raw `update.*`
+  fields are unchecked. `switchboardValue` needs the expected feed; set `minSamples`.
+- **`merkleVerify`.** Leaves and inner nodes hash alike: build leaves as `keccak256(keccak256(data))` in the program.
+- **Existing accounts in `createIfNeeded`.** An existing token account's delegate and close authority, and a mint's
+  extensions the call does not name, are not checked (as in Anchor).
+- **Seeds of variable length.** Two adjacent string seeds can collide (`"ab" + "c"` and `"a" + "bc"`), as in Anchor.
+
+## Where TypeSOL is stricter than Anchor
+
+- Any two writable parameters naming one account are refused (Anchor compares only program and token accounts).
+- Arithmetic overflow returns an error code (5100) in every build; Anchor aborts the program, and only when
+  overflow checks are enabled.
+
+## Status
+
+The compiler and runtime have had internal security reviews; the findings of the latest are fixed in 0.25.0
+(CHANGELOG). There has been no external audit yet: see [audit.md](audit.md).

package/docs/testing.md

@@ -5,10 +5,11 @@ run prints its seed; reproduce with `FUZZ_SEED=<n>`, widen with `FUZZ_RUNS` / `F
 
 | Check | Oracle | What must hold |
 | --- | --- | --- |
-| `test/fuzz-arith.test.ts` | BigInt | `+ - * / % **`, `& \| ^ << >> ~`, unary minus, comparisons and casts at every width u8…u128 / i8…i128, plus `mulDiv`, `mulDivCeil`, `isqrt`, `min`, `max`, return the same value or abort with the same code (5100/5101/4102), for edge and random inputs |
-| `test/fuzz-state.test.ts` | TypeScript state model | random honest + hostile actions on vault and escrow: every outcome as predicted, balances equal the model, SOL conserved up to fees, token supply exactly conserved; random filings/decisions/resets on ledgerbook: Vec contents, account size and rent exemption equal the model |
-| `test/differential.test.ts` | Anchor twins in `bench/anchor` | identical transactions to TypeSOL and Anchor programs: same outcomes, same account contents, same wallet and token balances after every step |
-| `test/ports-*.test.ts` | the Anchor programs of solana-developers/program-examples and their tests | TypeSOL rewrites under `test/ports/` run the originals' flows and failure paths with the same outcomes, error codes and balances ([test/ports/README.md](../test/ports/README.md)) |
+| `test/verification/fuzz-arith.test.ts` | BigInt | `+ - * / % **`, `& \| ^ << >> ~`, unary minus, comparisons and casts at every width u8…u128 / i8…i128, plus `mulDiv`, `mulDivCeil`, `isqrt`, `min`, `max`, return the same value or abort with the same code (5100/5101/4102), for edge and random inputs |
+| `test/verification/fuzz-state.test.ts` | TypeScript state model | random honest + hostile actions on vault and escrow: every outcome as predicted, balances equal the model, SOL conserved up to fees, token supply exactly conserved; random filings/decisions/resets on ledgerbook: Vec contents, account size and rent exemption equal the model |
+| `test/verification/fuzz-layout.test.ts` | TypeScript model | random pushes, pops, sets, in-place additions, moves and clears on an account with two growable Vecs (honest, out of range and by a stranger): the decoded account equals the model after every step; random `loadAccountMut` index pairs over remaining-account lists that repeat accounts: every alias refused (2040), balances conserved |
+| `test/verification/differential.test.ts` | Anchor twins in `test/anchor-twins` | identical transactions to TypeSOL and Anchor programs: same outcomes, same account contents, same wallet and token balances after every step |
+| `test/porting/ports-*.test.ts` | the Anchor programs of solana-developers/program-examples and their tests | TypeSOL rewrites under `test/ports/` run the originals' flows and failure paths with the same outcomes, error codes and balances ([test/ports/README.md](../test/ports/README.md)) |
 
 Compute-unit and binary-size comparisons with Anchor, native Rust and Pinocchio are in the README
 ([Numbers](../README.md#numbers)).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typesol/cli",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Compile a TypeScript-syntax language directly to Solana SBF programs.",
   "type": "module",
   "license": "MIT",
@@ -22,16 +22,16 @@
       "default": "./dist/workspace.js"
     },
     "./cpi": {
-      "types": "./dist/cpigen.d.ts",
-      "default": "./dist/cpigen.js"
+      "types": "./dist/tools/cpigen.d.ts",
+      "default": "./dist/tools/cpigen.js"
     },
     "./client": {
-      "types": "./dist/clientgen.d.ts",
-      "default": "./dist/clientgen.js"
+      "types": "./dist/tools/clientgen.d.ts",
+      "default": "./dist/tools/clientgen.js"
     },
     "./profile": {
-      "types": "./dist/profile.d.ts",
-      "default": "./dist/profile.js"
+      "types": "./dist/tools/profile.d.ts",
+      "default": "./dist/tools/profile.js"
     },
     "./testing": {
       "types": "./dist/testing.d.ts",
@@ -39,8 +39,8 @@
     },
     "./ts-plugin": "./ts-plugin/index.js",
     "./idl": {
-      "types": "./dist/idlpublish.d.ts",
-      "default": "./dist/idlpublish.js"
+      "types": "./dist/tools/idlpublish.d.ts",
+      "default": "./dist/tools/idlpublish.js"
     },
     "./package.json": "./package.json"
   },
@@ -63,12 +63,12 @@
     "test": "vitest run",
     "typesol": "node dist/cli.js",
     "smoke": "node scripts/smoke.ts",
-    "fuzz": "FUZZ_RUNS=2000 FUZZ_STEPS=600 FUZZ_VERBOSE=1 vitest run test/fuzz-arith.test.ts test/fuzz-state.test.ts test/differential.test.ts --silent=false",
-    "bench:anchor": "cd bench/anchor && cargo-build-sbf",
+    "fuzz": "FUZZ_RUNS=2000 FUZZ_STEPS=600 FUZZ_VERBOSE=1 vitest run test/verification/fuzz-arith.test.ts test/verification/fuzz-state.test.ts test/verification/fuzz-layout.test.ts test/verification/differential.test.ts --silent=false",
+    "build:twins": "cd test/anchor-twins && cargo-build-sbf",
     "prepack": "npm run build",
     "fetch:programs": "bash scripts/fetch-programs.sh",
-    "format": "prettier --write \"src/**/*.ts\" \"test/*.ts\" \"scripts/**/*.ts\" \"lib/**/*.ts\"",
-    "lint": "prettier --check \"src/**/*.ts\" \"test/*.ts\" \"scripts/**/*.ts\" \"lib/**/*.ts\" && pnpm typecheck",
+    "format": "prettier --write \"src/**/*.ts\" \"test/*.ts\" \"test/*/*.test.ts\" \"scripts/**/*.ts\" \"lib/**/*.ts\"",
+    "lint": "prettier --check \"src/**/*.ts\" \"test/*.ts\" \"test/*/*.test.ts\" \"scripts/**/*.ts\" \"lib/**/*.ts\" && pnpm typecheck",
     "prepublishOnly": "pnpm lint && pnpm test"
   },
   "engines": {