@dev.sail.money/sailor 0.1.0-local → 1.0.0-39

package/scripts/check-init.mjs

@@ -1,108 +1,108 @@
-#!/usr/bin/env node
-/**
- * `sailor init` smoke test.
- *
- * Scaffolds a fresh project from the in-tree CLI bundle into a temp dir and
- * asserts the scaffold succeeded. This exists to catch the class of regression
- * the doc-drift gate structurally cannot — e.g. `packageRoot()` resolving to a
- * `bin.sailor` package that ships no `templates/`, which made `init` fail from a
- * monorepo checkout with "Template ... not found. Available: none".
- *
- * It runs the REAL built bundle from a monorepo layout, which is exactly the
- * in-tree path that broke before. Pure Node + child_process; the only build
- * dependency is the CLI bundle (`pnpm --filter sailor build`).
- *
- * Run:  node scripts/check-init.mjs   (CI builds the CLI first)
- * Exit: 0 = scaffold OK, 1 = failure (prints what was missing).
- */
-
-import { execFileSync } from "node:child_process";
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
-const BUNDLE = path.join(ROOT, "packages/cli/dist/index.cjs");
-const PROJECT = "smoke-agent";
-
-function fail(msg) {
-  console.error(`✗ init smoke test FAILED: ${msg}`);
-  process.exit(1);
-}
-
-if (!fs.existsSync(BUNDLE)) {
-  fail(`CLI bundle not found at ${BUNDLE}.\n  Build it first: pnpm --filter sailor build`);
-}
-
-// Scaffold into a temp dir. `init` requires the destination to live inside the
-// process cwd, so we run the bundle with cwd set to a fresh temp root.
-const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "sailor-init-smoke-"));
-const dest = path.join(tmpRoot, PROJECT);
-
-try {
-  let stdout = "";
-  try {
-    stdout = execFileSync(process.execPath, [BUNDLE, "init", PROJECT], {
-      cwd: tmpRoot,
-      encoding: "utf-8",
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-  } catch (err) {
-    const out = `${err.stdout ?? ""}${err.stderr ?? ""}`.trim();
-    fail(`\`sailor init ${PROJECT}\` exited non-zero.\n  ${out || err.message}`);
-  }
-
-  // A successful fresh init prints the single-line handoff to the AI assistant.
-  if (!/say start/i.test(stdout)) {
-    fail(`init did not report success.\n  stdout: ${stdout.trim()}`);
-  }
-
-  // Assert the scaffold landed.
-  const mustExist = [
-    ".sail/config.json",
-    "package.json",
-    "foundry.toml",
-    "mandates",
-    "AGENTS.md",
-  ];
-  for (const rel of mustExist) {
-    if (!fs.existsSync(path.join(dest, rel))) fail(`expected scaffolded "${rel}" — not found`);
-  }
-
-  // config.json is valid JSON named after the project.
-  const config = JSON.parse(fs.readFileSync(path.join(dest, ".sail/config.json"), "utf-8"));
-  if (config.name !== PROJECT) fail(`config.json name is "${config.name}", expected "${PROJECT}"`);
-
-  // package.json is valid, renamed, and the workspace protocol was resolved away
-  // (a leftover "workspace:*" would make the scaffold un-installable for users).
-  const pkg = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf-8"));
-  if (pkg.name !== PROJECT) fail(`package.json name is "${pkg.name}", expected "${PROJECT}"`);
-  if (pkg.dependencies?.["@sail/sdk"] === "workspace:*") {
-    fail(`package.json still has "@sail/sdk": "workspace:*" — init did not resolve it`);
-  }
-
-  // Regression guard: an absolute path outside the cwd must be REJECTED, not
-  // silently nested into `<cwd>/<abs path>`. (Pre-fix, `path.join` swallowed the
-  // leading slash and scaffolded a bogus nested tree while printing success.)
-  const outside = path.join(os.tmpdir(), "sailor-init-outside", "agent");
-  let rejected = false;
-  try {
-    execFileSync(process.execPath, [BUNDLE, "init", outside], {
-      cwd: tmpRoot,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-  } catch {
-    rejected = true; // non-zero exit = correctly refused
-  }
-  if (!rejected) fail(`an absolute path outside cwd ("${outside}") was accepted — should be rejected`);
-  if (fs.existsSync(path.join(outside, ".sail/config.json"))) {
-    fail(`init scaffolded into an out-of-cwd absolute path "${outside}"`);
-  }
-
-  console.log(`✓ init smoke test passed — scaffolded ${PROJECT}/ from the in-tree bundle`);
-  console.log("✓ init guard passed — absolute path outside cwd rejected, not silently nested");
-} finally {
-  fs.rmSync(path.join(os.tmpdir(), "sailor-init-outside"), { recursive: true, force: true });
-  fs.rmSync(tmpRoot, { recursive: true, force: true });
-}
+#!/usr/bin/env node
+/**
+ * `sailor init` smoke test.
+ *
+ * Scaffolds a fresh project from the in-tree CLI bundle into a temp dir and
+ * asserts the scaffold succeeded. This exists to catch the class of regression
+ * the doc-drift gate structurally cannot — e.g. `packageRoot()` resolving to a
+ * `bin.sailor` package that ships no `templates/`, which made `init` fail from a
+ * monorepo checkout with "Template ... not found. Available: none".
+ *
+ * It runs the REAL built bundle from a monorepo layout, which is exactly the
+ * in-tree path that broke before. Pure Node + child_process; the only build
+ * dependency is the CLI bundle (`pnpm --filter sailor build`).
+ *
+ * Run:  node scripts/check-init.mjs   (CI builds the CLI first)
+ * Exit: 0 = scaffold OK, 1 = failure (prints what was missing).
+ */
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+const BUNDLE = path.join(ROOT, "packages/cli/dist/index.cjs");
+const PROJECT = "smoke-agent";
+
+function fail(msg) {
+  console.error(`✗ init smoke test FAILED: ${msg}`);
+  process.exit(1);
+}
+
+if (!fs.existsSync(BUNDLE)) {
+  fail(`CLI bundle not found at ${BUNDLE}.\n  Build it first: pnpm --filter sailor build`);
+}
+
+// Scaffold into a temp dir. `init` requires the destination to live inside the
+// process cwd, so we run the bundle with cwd set to a fresh temp root.
+const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "sailor-init-smoke-"));
+const dest = path.join(tmpRoot, PROJECT);
+
+try {
+  let stdout = "";
+  try {
+    stdout = execFileSync(process.execPath, [BUNDLE, "init", PROJECT], {
+      cwd: tmpRoot,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch (err) {
+    const out = `${err.stdout ?? ""}${err.stderr ?? ""}`.trim();
+    fail(`\`sailor init ${PROJECT}\` exited non-zero.\n  ${out || err.message}`);
+  }
+
+  // A successful fresh init prints the AGENTS.md onboarding banner.
+  if (!/AGENTS\.md/i.test(stdout)) {
+    fail(`init did not report success.\n  stdout: ${stdout.trim()}`);
+  }
+
+  // Assert the scaffold landed.
+  const mustExist = [
+    ".sail/config.json",
+    "package.json",
+    "foundry.toml",
+    "mandates",
+    "AGENTS.md",
+  ];
+  for (const rel of mustExist) {
+    if (!fs.existsSync(path.join(dest, rel))) fail(`expected scaffolded "${rel}" — not found`);
+  }
+
+  // config.json is valid JSON named after the project.
+  const config = JSON.parse(fs.readFileSync(path.join(dest, ".sail/config.json"), "utf-8"));
+  if (config.name !== PROJECT) fail(`config.json name is "${config.name}", expected "${PROJECT}"`);
+
+  // package.json is valid, renamed, and the workspace protocol was resolved away
+  // (a leftover "workspace:*" would make the scaffold un-installable for users).
+  const pkg = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf-8"));
+  if (pkg.name !== PROJECT) fail(`package.json name is "${pkg.name}", expected "${PROJECT}"`);
+  if (pkg.dependencies?.["@sail/sdk"] === "workspace:*") {
+    fail(`package.json still has "@sail/sdk": "workspace:*" — init did not resolve it`);
+  }
+
+  // Regression guard: an absolute path outside the cwd must be REJECTED, not
+  // silently nested into `<cwd>/<abs path>`. (Pre-fix, `path.join` swallowed the
+  // leading slash and scaffolded a bogus nested tree while printing success.)
+  const outside = path.join(os.tmpdir(), "sailor-init-outside", "agent");
+  let rejected = false;
+  try {
+    execFileSync(process.execPath, [BUNDLE, "init", outside], {
+      cwd: tmpRoot,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch {
+    rejected = true; // non-zero exit = correctly refused
+  }
+  if (!rejected) fail(`an absolute path outside cwd ("${outside}") was accepted — should be rejected`);
+  if (fs.existsSync(path.join(outside, ".sail/config.json"))) {
+    fail(`init scaffolded into an out-of-cwd absolute path "${outside}"`);
+  }
+
+  console.log(`✓ init smoke test passed — scaffolded ${PROJECT}/ from the in-tree bundle`);
+  console.log("✓ init guard passed — absolute path outside cwd rejected, not silently nested");
+} finally {
+  fs.rmSync(path.join(os.tmpdir(), "sailor-init-outside"), { recursive: true, force: true });
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+}

package/templates/custom-mandate/.sail/contracts/interfaces/IPermission.sol

@@ -1,18 +1,18 @@
-// SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
-
-struct Context {
-    address account;
-    address manager;
-    address submitter;
-    address target;
-    bytes4 selector;
-    uint256 value;
-    uint256 blockTimestamp;
-    uint256 blockNumber;
-}
-
-interface IPermission {
-    function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool);
-    function discriminator() external view returns (bytes32);
-}
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+struct Context {
+    address account;
+    address manager;
+    address submitter;
+    address target;
+    bytes4 selector;
+    uint256 value;
+    uint256 blockTimestamp;
+    uint256 blockNumber;
+}
+
+interface IPermission {
+    function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool);
+    function discriminator() external view returns (bytes32);
+}

package/templates/custom-mandate/README.md

@@ -1,116 +1,116 @@
-# Write Your Own Permission — Sail Protocol
-
-Sail Protocol accepts ANY contract implementing `IPermission`. There is no fixed set of
-permission types. `BoundedCallPermission` here is a general primitive; `examples/permissions/`
-shows protocol-specific patterns. Every financial bound your mandate enforces should live in
-Solidity — the kernel checks `evaluate()` on every dispatch. The agent's TypeScript can be changed
-without your signature; the permission contract cannot. You own what you deploy.
-
----
-
-Sailor does not ship a blessed library of financial permission contracts. You author, review, and
-deploy your own `IPermission` contract, and Sailor makes deploying and registering it easy.
-
-## What a permission contract is
-
-A permission contract is an on-chain policy that the SailKernel consults before it lets your agent
-(the manager) execute any transaction from your SMA. On every dispatch the kernel calls
-`evaluate(txData, ctx)` on each registered permission via `staticcall` — return `true` to allow the
-call, `false` to block it. The contract holds your rules (allowed targets, size caps, token
-allowlists, time windows, …) so the agent can only ever act inside the bounds you deployed.
-
-## The IPermission interface
-
-```solidity
-interface IPermission {
-    function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool);
-    function discriminator() external view returns (bytes32);
-}
-
-struct Context {
-    address account;        // the SMA (Safe) the dispatch executes from
-    address manager;        // the delegated signer authorized to dispatch
-    address submitter;      // the address that submitted the dispatch transaction
-    address target;         // the contract the call is directed at
-    bytes4  selector;       // the 4-byte function selector being called
-    uint256 value;          // msg.value (native asset) sent with the call
-    uint256 blockTimestamp; // block.timestamp at evaluation
-    uint256 blockNumber;    // block.number at evaluation
-}
-```
-
-- `evaluate` — your policy. Return `true` to permit the call, `false` to block it. Runs under a
-  100k-gas `staticcall`; a revert or gas overage is treated as `false`.
-- `discriminator` — a stable `bytes32` name for your permission (e.g. `keccak256("MyMandate")`).
-
-Keep all policy parameters constructor-configured so each deployment is a complete, reviewable
-policy before it is attached to the SMA.
-
-## Workflow
-
-```bash
-# 1. Write your contract in mandates/ (start from BoundedCallPermission.sol)
-# 2. Compile
-forge build
-
-# 3. Deploy and attach in one step
-sailor mandate deploy --contract <Name> --attach --sma <SMA>
-```
-
-Or deploy first and attach later (two-step):
-
-```bash
-sailor mandate deploy --contract <Name>            # prints the deployed address
-sailor mandate attach --address <deployedAddress> --sma <SMA>
-```
-
-Both attach paths open the browser signing station so the owner authorizes the registration
-(EIP-712 `RegisterPermission`); the agent submits the on-chain transaction.
-
-## Prerequisites
-
-- [Foundry](https://book.getfoundry.sh/getting-started/installation)
-- An existing Sailor agent (created with `sailor init`)
-
-## Responsibility
-
-> **You are responsible for the correctness of your permission logic. Sailor registers whatever
-> contract address you provide. A bug can block all agent activity or authorize transactions you did
-> not intend. Review carefully before attaching.**
-
-## Extracting calldata parameters safely
-
-When you need to bound a specific call argument (amount cap, recipient check, slippage floor),
-use `SailCalldata` instead of manual `abi.decode`. The two common bugs it prevents:
-
-1. **Forgetting the length check** — decoding before checking `txData.length` can revert or
-   silently return wrong values. `SailCalldata.hasParams(txData, N)` is the one-line guard.
-2. **Wrong slot index** — off-by-one decodes the wrong parameter. Named helpers make the
-   intent explicit: `asAddress(txData, 0)`, `asUint256(txData, 1)`, `asAddress(txData, 2)`.
-
-```solidity
-import {SailCalldata} from "./SailCalldata.sol";
-
-function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool) {
-    if (ctx.target != POOL)        return false;
-    if (ctx.selector != SEL_SUPPLY) return false;
-    // supply(address asset, uint256 amount, address onBehalfOf, uint16 referralCode)
-    if (!SailCalldata.hasParams(txData, 4)) return false;
-    address asset      = SailCalldata.asAddress(txData, 0);
-    uint256 amount     = SailCalldata.asUint256(txData, 1);
-    address onBehalfOf = SailCalldata.asAddress(txData, 2);
-    // ...
-}
-```
-
-Available helpers: `asAddress`, `asUint256`, `asInt256`, `asBytes32`, `asBool`,
-`asUint128`, `asUint64`, `asUint32`, `asUint24`, `asUint16`, `asBytes4`.
-Only covers static (fixed-size) types. For `bytes`, `string`, or dynamic arrays,
-use `abi.decode(txData[4:], ...)` after the `hasParams` guard.
-
-## Structure
-
-- `foundry.toml` — Foundry config with `@sail/` remapping to `.sail/contracts/`
-- `.sail/contracts/interfaces/IPermission.sol` — interface copy (matches SailProtocol)
-- `mandates/BoundedCallPermission.sol` — general primitive: allowlisted targets, optional selector filter, max ETH value
-- `mandates/SailCalldata.sol` — safe calldata parameter extraction helpers
+# Write Your Own Permission — Sail Protocol
+
+Sail Protocol accepts ANY contract implementing `IPermission`. There is no fixed set of
+permission types. `BoundedCallPermission` here is a general primitive; `examples/permissions/`
+shows protocol-specific patterns. Every financial bound your mandate enforces should live in
+Solidity — the kernel checks `evaluate()` on every dispatch. The agent's TypeScript can be changed
+without your signature; the permission contract cannot. You own what you deploy.
+
+---
+
+Sailor does not ship a blessed library of financial permission contracts. You author, review, and
+deploy your own `IPermission` contract, and Sailor makes deploying and registering it easy.
+
+## What a permission contract is
+
+A permission contract is an on-chain policy that the SailKernel consults before it lets your agent
+(the manager) execute any transaction from your SMA. On every dispatch the kernel calls
+`evaluate(txData, ctx)` on each registered permission via `staticcall` — return `true` to allow the
+call, `false` to block it. The contract holds your rules (allowed targets, size caps, token
+allowlists, time windows, …) so the agent can only ever act inside the bounds you deployed.
+
+## The IPermission interface
+
+```solidity
+interface IPermission {
+    function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool);
+    function discriminator() external view returns (bytes32);
+}
+
+struct Context {
+    address account;        // the SMA (Safe) the dispatch executes from
+    address manager;        // the delegated signer authorized to dispatch
+    address submitter;      // the address that submitted the dispatch transaction
+    address target;         // the contract the call is directed at
+    bytes4  selector;       // the 4-byte function selector being called
+    uint256 value;          // msg.value (native asset) sent with the call
+    uint256 blockTimestamp; // block.timestamp at evaluation
+    uint256 blockNumber;    // block.number at evaluation
+}
+```
+
+- `evaluate` — your policy. Return `true` to permit the call, `false` to block it. Runs under a
+  100k-gas `staticcall`; a revert or gas overage is treated as `false`.
+- `discriminator` — a stable `bytes32` name for your permission (e.g. `keccak256("MyMandate")`).
+
+Keep all policy parameters constructor-configured so each deployment is a complete, reviewable
+policy before it is attached to the SMA.
+
+## Workflow
+
+```bash
+# 1. Write your contract in mandates/ (start from BoundedCallPermission.sol)
+# 2. Compile
+forge build
+
+# 3. Deploy and attach in one step
+sailor mandate deploy --contract <Name> --attach --sma <SMA>
+```
+
+Or deploy first and attach later (two-step):
+
+```bash
+sailor mandate deploy --contract <Name>            # prints the deployed address
+sailor mandate attach --address <deployedAddress> --sma <SMA>
+```
+
+Both attach paths open the browser signing station so the owner authorizes the registration
+(EIP-712 `RegisterPermission`); the agent submits the on-chain transaction.
+
+## Prerequisites
+
+- [Foundry](https://book.getfoundry.sh/getting-started/installation)
+- An existing Sailor agent (created with `sailor init`)
+
+## Responsibility
+
+> **You are responsible for the correctness of your permission logic. Sailor registers whatever
+> contract address you provide. A bug can block all agent activity or authorize transactions you did
+> not intend. Review carefully before attaching.**
+
+## Extracting calldata parameters safely
+
+When you need to bound a specific call argument (amount cap, recipient check, slippage floor),
+use `SailCalldata` instead of manual `abi.decode`. The two common bugs it prevents:
+
+1. **Forgetting the length check** — decoding before checking `txData.length` can revert or
+   silently return wrong values. `SailCalldata.hasParams(txData, N)` is the one-line guard.
+2. **Wrong slot index** — off-by-one decodes the wrong parameter. Named helpers make the
+   intent explicit: `asAddress(txData, 0)`, `asUint256(txData, 1)`, `asAddress(txData, 2)`.
+
+```solidity
+import {SailCalldata} from "./SailCalldata.sol";
+
+function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool) {
+    if (ctx.target != POOL)        return false;
+    if (ctx.selector != SEL_SUPPLY) return false;
+    // supply(address asset, uint256 amount, address onBehalfOf, uint16 referralCode)
+    if (!SailCalldata.hasParams(txData, 4)) return false;
+    address asset      = SailCalldata.asAddress(txData, 0);
+    uint256 amount     = SailCalldata.asUint256(txData, 1);
+    address onBehalfOf = SailCalldata.asAddress(txData, 2);
+    // ...
+}
+```
+
+Available helpers: `asAddress`, `asUint256`, `asInt256`, `asBytes32`, `asBool`,
+`asUint128`, `asUint64`, `asUint32`, `asUint24`, `asUint16`, `asBytes4`.
+Only covers static (fixed-size) types. For `bytes`, `string`, or dynamic arrays,
+use `abi.decode(txData[4:], ...)` after the `hasParams` guard.
+
+## Structure
+
+- `foundry.toml` — Foundry config with `@sail/` remapping to `.sail/contracts/`
+- `.sail/contracts/interfaces/IPermission.sol` — interface copy (matches SailProtocol)
+- `mandates/BoundedCallPermission.sol` — general primitive: allowlisted targets, optional selector filter, max ETH value
+- `mandates/SailCalldata.sol` — safe calldata parameter extraction helpers

package/templates/custom-mandate/foundry.toml

@@ -1,8 +1,8 @@
-[profile.default]
-src = "mandates"
-out = "out"
-libs = ["lib"]
-remappings = ["@sail/=.sail/contracts/"]
-solc = "0.8.26"
-optimizer = true
-optimizer_runs = 200
+[profile.default]
+src = "mandates"
+out = "out"
+libs = ["lib"]
+remappings = ["@sail/=.sail/contracts/"]
+solc = "0.8.26"
+optimizer = true
+optimizer_runs = 200

package/templates/custom-mandate/mandates/BoundedCallPermission.sol

@@ -1,41 +1,41 @@
-// SPDX-License-Identifier: MIT
-pragma solidity 0.8.26;
-
-import {IPermission, Context} from "@sail/interfaces/IPermission.sol";
-// SailCalldata: safe helpers for extracting calldata parameters inside evaluate().
-// Use SailCalldata.hasParams(txData, N) + SailCalldata.asAddress/asUint256/... instead of
-// manual abi.decode when you need to bound specific call arguments (amounts, recipients, etc.).
-// See SailCalldata.sol for the full API and examples/permissions/ for protocol examples.
-import {SailCalldata} from "./SailCalldata.sol";
-
-/// @title BoundedCallPermission
-/// @notice General-purpose IPermission primitive. Bounds the universal properties of any call:
-///         allowed targets, allowed selectors, and max ETH value. Protocol-agnostic.
-///         For calldata-parameter bounds (amount caps, recipient checks, slippage), use
-///         SailCalldata (imported above) and write a protocol-specific permission —
-///         see examples/permissions/ for the pattern per protocol.
-/// @dev Deploy one instance per SMA with constructor-configured parameters.
-contract BoundedCallPermission is IPermission {
-    bytes32 private constant DISCRIMINATOR = keccak256("BoundedCallPermission");
-
-    mapping(address => bool) public isAllowedTarget;
-    mapping(bytes4 => bool) public isAllowedSelector;
-    bool public immutable SELECTOR_FILTERING;
-    uint256 public immutable MAX_VALUE;
-
-    constructor(address[] memory allowedTargets, bytes4[] memory allowedSelectors, uint256 maxValue) {
-        for (uint256 i = 0; i < allowedTargets.length; i++) isAllowedTarget[allowedTargets[i]] = true;
-        SELECTOR_FILTERING = allowedSelectors.length > 0;
-        for (uint256 i = 0; i < allowedSelectors.length; i++) isAllowedSelector[allowedSelectors[i]] = true;
-        MAX_VALUE = maxValue;
-    }
-
-    function evaluate(bytes calldata, Context calldata ctx) external view returns (bool) {
-        if (!isAllowedTarget[ctx.target]) return false;
-        if (SELECTOR_FILTERING && !isAllowedSelector[ctx.selector]) return false;
-        if (ctx.value > MAX_VALUE) return false;
-        return true;
-    }
-
-    function discriminator() external pure returns (bytes32) { return DISCRIMINATOR; }
-}
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+import {IPermission, Context} from "@sail/interfaces/IPermission.sol";
+// SailCalldata: safe helpers for extracting calldata parameters inside evaluate().
+// Use SailCalldata.hasParams(txData, N) + SailCalldata.asAddress/asUint256/... instead of
+// manual abi.decode when you need to bound specific call arguments (amounts, recipients, etc.).
+// See SailCalldata.sol for the full API and examples/permissions/ for protocol examples.
+import {SailCalldata} from "./SailCalldata.sol";
+
+/// @title BoundedCallPermission
+/// @notice General-purpose IPermission primitive. Bounds the universal properties of any call:
+///         allowed targets, allowed selectors, and max ETH value. Protocol-agnostic.
+///         For calldata-parameter bounds (amount caps, recipient checks, slippage), use
+///         SailCalldata (imported above) and write a protocol-specific permission —
+///         see examples/permissions/ for the pattern per protocol.
+/// @dev Deploy one instance per SMA with constructor-configured parameters.
+contract BoundedCallPermission is IPermission {
+    bytes32 private constant DISCRIMINATOR = keccak256("BoundedCallPermission");
+
+    mapping(address => bool) public isAllowedTarget;
+    mapping(bytes4 => bool) public isAllowedSelector;
+    bool public immutable SELECTOR_FILTERING;
+    uint256 public immutable MAX_VALUE;
+
+    constructor(address[] memory allowedTargets, bytes4[] memory allowedSelectors, uint256 maxValue) {
+        for (uint256 i = 0; i < allowedTargets.length; i++) isAllowedTarget[allowedTargets[i]] = true;
+        SELECTOR_FILTERING = allowedSelectors.length > 0;
+        for (uint256 i = 0; i < allowedSelectors.length; i++) isAllowedSelector[allowedSelectors[i]] = true;
+        MAX_VALUE = maxValue;
+    }
+
+    function evaluate(bytes calldata, Context calldata ctx) external view returns (bool) {
+        if (!isAllowedTarget[ctx.target]) return false;
+        if (SELECTOR_FILTERING && !isAllowedSelector[ctx.selector]) return false;
+        if (ctx.value > MAX_VALUE) return false;
+        return true;
+    }
+
+    function discriminator() external pure returns (bytes32) { return DISCRIMINATOR; }
+}

package/templates/custom-mandate/mandates/README.md

@@ -1,16 +1,16 @@
-# Mandates
-
-Solidity permission contracts live here. Each contract implements `@sail/interfaces/IPermission.sol`.
-The SailKernel calls `evaluate(txData, ctx)` before any manager dispatch. Return `true` to permit,
-`false` to block.
-
-## Workflow
-
-```bash
-forge build
-sailor mandate prepare
-sailor ui
-```
-
-Keep all policy parameters constructor-configured so each deployment has a complete, reviewable
-policy before it is attached to the SMA.
+# Mandates
+
+Solidity permission contracts live here. Each contract implements `@sail/interfaces/IPermission.sol`.
+The SailKernel calls `evaluate(txData, ctx)` before any manager dispatch. Return `true` to permit,
+`false` to block.
+
+## Workflow
+
+```bash
+forge build
+sailor mandate prepare
+sailor ui
+```
+
+Keep all policy parameters constructor-configured so each deployment has a complete, reviewable
+policy before it is attached to the SMA.