@senpi/runtime 1.0.95-dev.runtime-phase-2.20260506193916 → 1.0.95-dev.runtime-phase-2-api.20260507130312

package/dist/runtime-api/server.js

@@ -0,0 +1,109 @@
+/**
+ * `createApi()` — Fastify server factory for the runtime HTTP API.
+ *
+ * Wires the Fastify instance with:
+ *  - `POST /signals` — ingest signals for one or more wallets.
+ *  - `GET  /audit`   — MCP audit-query proxy scoped to one wallet.
+ *  - `GET  /health`  — three-state readiness + per-runtime queue depth.
+ *
+ * Returns the Fastify instance, the mutable readiness flag, and the boot
+ * timestamp. The lifecycle layer (S5) calls `fastify.listen()` and flips
+ * `readiness.setOk()` / `readiness.setDraining()` around start/stop.
+ *
+ * This module owns only wiring — no business logic. All route logic
+ * delegates to the shared handlers in `handlers/`.
+ */
+import Fastify from "fastify";
+import { registerSignalsRoute } from "./routes/signals.js";
+import { registerAuditRoute } from "./routes/audit.js";
+import { registerHealthRoute } from "./routes/health.js";
+import { createReadiness } from "./readiness.js";
+/**
+ * Create and configure the Fastify HTTP server.
+ *
+ * Does NOT start listening. Call `artifacts.fastify.listen(...)` from the
+ * lifecycle layer (S5) after `createApi()` returns.
+ *
+ * Error handler behaviour:
+ *  - `400` (schema validation), `413` (body too large), `415` (wrong
+ *    content-type) are passed through as `INVALID_REQUEST` with the original
+ *    Fastify message so callers can read the validation detail.
+ *  - All other errors are logged and returned as `500 / UNAVAILABLE`.
+ *
+ * Request timeout strategy (resolved in S5):
+ *  A single server-wide `requestTimeout: 30_000` covers all routes.
+ *  The plan called for per-route values (10s for `/signals` + `/health`,
+ *  30s for `/audit`), but Fastify v5 does not expose a declarative per-route
+ *  `requestTimeout` and wiring an `onRequest` hook with manual `setTimeout`
+ *  calls adds meaningful complexity for a localhost-only server where requests
+ *  that genuinely hang are almost always MCP-side.  The 30s ceiling is driven
+ *  entirely by `/audit` (MCP round-trip); `/signals` and `/health` both
+ *  complete in well under 1s in practice.  If per-route enforcement becomes
+ *  necessary, add an `onRequest` hook in this file.
+ *
+ * @param deps  Dependencies injected by the plugin entry point.
+ * @returns     `{ fastify, readiness, bootedAt }`.
+ */
+export function createApi(deps) {
+    const bootedAt = Date.now();
+    const readiness = createReadiness();
+    const fastify = Fastify({
+        logger: { level: "info" },
+        bodyLimit: 256 * 1024, // 256 KB — generous for signal batches, hard cap on abuse.
+        disableRequestLogging: false,
+        /**
+         * 30s request ceiling — driven by `/audit` (MCP round-trip).
+         * `/signals` and `/health` complete far faster; we accept the unified
+         * ceiling to avoid per-route hook complexity on a localhost-only server.
+         * Documented in docs/runtime-docs/runtime-api.md.
+         */
+        requestTimeout: 30_000,
+    });
+    // Custom error handler — normalises Fastify validation / payload errors into
+    // the senpi-stack envelope `{ success: false, error: { code, message } }`.
+    fastify.setErrorHandler((error, _req, reply) => {
+        // Fastify v5 types setErrorHandler with `unknown`; cast once for the handler.
+        const err = error;
+        const statusCode = err.statusCode;
+        if (statusCode === 400 ||
+            statusCode === 413 ||
+            statusCode === 415) {
+            return reply.status(statusCode).send({
+                success: false,
+                error: {
+                    code: "INVALID_REQUEST",
+                    message: err.message,
+                },
+            });
+        }
+        deps.logger.error("[senpi-core][runtime-api] Unhandled error", {
+            err,
+        });
+        return reply.status(500).send({
+            success: false,
+            error: {
+                code: "UNAVAILABLE",
+                message: err.message,
+            },
+        });
+    });
+    registerSignalsRoute(fastify, {
+        runtimeHandles: deps.runtimeHandles,
+        logger: deps.logger,
+        maxItems: deps.apiConfig.maxItemsPerSignalsRequest,
+        transport: "http",
+    });
+    registerAuditRoute(fastify, {
+        runtimeHandles: deps.runtimeHandles,
+        logger: deps.logger,
+    });
+    registerHealthRoute(fastify, {
+        runtimeHandles: deps.runtimeHandles,
+        apiConfig: { host: deps.apiConfig.host, port: deps.apiConfig.port },
+        readiness,
+        version: deps.version,
+        bootedAt,
+    });
+    return { fastify, readiness, bootedAt };
+}
+//# sourceMappingURL=server.js.map

package/dist/runtime-api/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/runtime-api/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,OAAiC,MAAM,SAAS,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAsCjD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,SAAS,CAAC,IAAmB;IAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC5B,MAAM,SAAS,GAAG,eAAe,EAAE,CAAC;IAEpC,MAAM,OAAO,GAAG,OAAO,CAAC;QACtB,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE;QACzB,SAAS,EAAE,GAAG,GAAG,IAAI,EAAE,2DAA2D;QAClF,qBAAqB,EAAE,KAAK;QAC5B;;;;;WAKG;QACH,cAAc,EAAE,MAAM;KACvB,CAAC,CAAC;IAEH,6EAA6E;IAC7E,2EAA2E;IAC3E,OAAO,CAAC,eAAe,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QAC7C,8EAA8E;QAC9E,MAAM,GAAG,GAAG,KAAwC,CAAC;QACrD,MAAM,UAAU,GAAG,GAAG,CAAC,UAAU,CAAC;QAClC,IACE,UAAU,KAAK,GAAG;YAClB,UAAU,KAAK,GAAG;YAClB,UAAU,KAAK,GAAG,EAClB,CAAC;YACD,OAAO,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC;gBACnC,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE;oBACL,IAAI,EAAE,iBAAiB;oBACvB,OAAO,EAAE,GAAG,CAAC,OAAO;iBACrB;aACF,CAAC,CAAC;QACL,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,2CAA2C,EAAE;YAC7D,GAAG;SACJ,CAAC,CAAC;QACH,OAAO,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;YAC5B,OAAO,EAAE,KAAK;YACd,KAAK,EAAE;gBACL,IAAI,EAAE,aAAa;gBACnB,OAAO,EAAE,GAAG,CAAC,OAAO;aACrB;SACF,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,oBAAoB,CAAC,OAAO,EAAE;QAC5B,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,yBAAyB;QAClD,SAAS,EAAE,MAAM;KAClB,CAAC,CAAC;IAEH,kBAAkB,CAAC,OAAO,EAAE;QAC1B,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CAAC,CAAC;IAEH,mBAAmB,CAAC,OAAO,EAAE;QAC3B,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,SAAS,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE;QACnE,SAAS;QACT,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,QAAQ;KACT,CAAC,CAAC;IAEH,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;AAC1C,CAAC"}

package/dist/senpi/client.d.ts

@@ -1,4 +1,22 @@
 import type { McpTransport, SenpiClientConfig, CreatePositionRequest, CreatePositionResult, EditPositionResult, GetPositionResult, OpenPosition, GetStrategyResult, GetOpenOrdersResult, GetTraderHistoryOptions, TraderHistoryEntry, GetTraderStateOptions, TraderStateResult, StrategyFundResult, ClosePositionsRequest, GetPnlHistoryOptions, ListStrategiesFilters, StrategySummary, RatchetStopPosition, RatchetStopEvent, AddRatchetStopInput, EditRatchetStopInput, DeleteRatchetStopInput, QueryRatchetStopsInput, QueryRatchetStopEventsInput } from './types.js';
+/**
+ * Typed error thrown by `SenpiClient` mutation methods when the response
+ * reports a failure at either layer (outer MCP envelope or inner engine
+ * result). Callers that today only catch `throw` will fire on real
+ * failures instead of silently treating phantom-success responses as
+ * success — preventing the orphaned-DSL-state class of bug.
+ *
+ * Codes:
+ *  - `UNEXPECTED_RESPONSE` — response shape is not the expected object.
+ *  - `UPSTREAM_ERROR`      — outer MCP envelope `success === false`.
+ *  - `ENGINE_FAILURE`      — outer envelope ok, but inner engine result
+ *                            reported `success === false` (e.g. CREATE_ORDER_RESTING).
+ */
+export declare class SenpiClientError extends Error {
+    readonly code: "UNEXPECTED_RESPONSE" | "UPSTREAM_ERROR" | "ENGINE_FAILURE";
+    readonly details: unknown;
+    constructor(code: "UNEXPECTED_RESPONSE" | "UPSTREAM_ERROR" | "ENGINE_FAILURE", message: string, details?: unknown);
+}
 export declare class SenpiClient {
     private readonly injectedTransport;
     private readonly config;
@@ -10,6 +28,27 @@ export declare class SenpiClient {
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     private callTool;
+    /**
+     * Run an MCP `audit_query` and return the unwrapped response payload.
+     *
+     * Stays a thin pass-through so the runtime layer (which owns the
+     * wallet→strategyId resolution and error mapping) can compose the call
+     * with full type-safety. Callers must already have set
+     * `resource_type` / `resource_id` if scoping is desired — this method
+     * does not interpret arguments.
+     *
+     * @param args  Arbitrary key/value map forwarded verbatim as the MCP
+     *              tool input. Caller is responsible for matching the
+     *              MCP `audit_query` schema.
+     * @param opts  Optional AbortSignal; when fired, the underlying MCP
+     *              `callTool` is cancelled (the SDK rejects with an
+     *              AbortError).
+     * @returns     The `.data` field of the MCP envelope when present;
+     *              otherwise the raw response.
+     */
+    auditQuery(args: Record<string, unknown>, opts?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
     /**
      * Returns an adapter compatible with SenpiToolClient so the same connection
      * can be used for scanner provider MCP tool calls (e.g. leaderboard_get_markets).
@@ -17,14 +56,36 @@ export declare class SenpiClient {
     asToolClient(): {
         callTool(name: string, args: Record<string, unknown>): Promise<unknown>;
     };
+    /**
+     * Register a backend ratchet-stop (DSL Phase 2 handoff).
+     *
+     * Throws `SenpiClientError` on outer envelope failure or inner engine
+     * `success: false`. Callers' existing `if (result.success && result.position)`
+     * branches now treat the success path only — failures land in the
+     * surrounding try/catch instead of falling through.
+     */
     addRatchetStop(input: AddRatchetStopInput): Promise<{
         success: boolean;
         position?: RatchetStopPosition;
     }>;
+    /**
+     * Update an existing backend ratchet-stop.
+     *
+     * Throws `SenpiClientError` on outer envelope failure or inner engine
+     * `success: false`.
+     */
     editRatchetStop(input: EditRatchetStopInput): Promise<{
         success: boolean;
         position?: RatchetStopPosition;
     }>;
+    /**
+     * Delete a backend ratchet-stop. Used during DSL teardown / handoff close.
+     *
+     * Throws `SenpiClientError` on outer envelope failure or inner engine
+     * `success: false`. Previously this method's `{ success: boolean }` return
+     * was ignored by every caller (only `throw` was caught), which left
+     * zombie ratchet-stops on the backend when the engine reported failure.
+     */
     deleteRatchetStop(input: DeleteRatchetStopInput): Promise<{
         success: boolean;
     }>;
@@ -44,6 +105,21 @@ export declare class SenpiClient {
      * Set/update SL (and optionally TP) on an open position. Uses MCP edit_position.
      * For XYZ DEX pass dex: "xyz" so coin is sent as "xyz:COIN"; otherwise main DEX uses plain coin.
      */
+    /**
+     * Set / update an exchange-side stop loss (or perform other position
+     * edits) on an open position.
+     *
+     * Throws `SenpiClientError` when either response layer reports failure:
+     *  - `UPSTREAM_ERROR`  — MCP envelope `success: false`.
+     *  - `ENGINE_FAILURE`  — outer ok, inner engine `success: false`
+     *                        (e.g. position not found, SL placement rejected).
+     *
+     * Returning normally means the engine accepted the edit. The returned
+     * `EditPositionResult` carries `slOrderId` when an SL was placed/updated;
+     * a `null` slOrderId on a non-throwing return indicates the engine reported
+     * success without the expected SL artifact — caller should treat that as
+     * a soft failure (logged as a warn) and re-attempt on the next sync tick.
+     */
     editPosition(wallet: string, payload: {
         coin: string;
         dex?: string;
@@ -105,8 +181,22 @@ export declare class SenpiClient {
     topUp(wallet: string, amount: number): Promise<StrategyFundResult>;
     withdrawFunds(wallet: string, amount: number): Promise<StrategyFundResult>;
     closeStrategy(wallet: string): Promise<StrategyFundResult>;
-    closePositions(wallet: string, positions: ClosePositionsRequest[]): Promise<unknown>;
-    cancelOrder(wallet: string, orderId: number): Promise<unknown>;
+    /**
+     * Submit a batch close_positions MCP call.
+     *
+     * Throws `SenpiClientError` on outer envelope or inner engine failure
+     * (same shape as {@link closePosition}). Successful return means the
+     * batch was accepted; per-position confirmation must still come from
+     * position-tracker scanner events.
+     */
+    closePositions(wallet: string, positions: ClosePositionsRequest[]): Promise<Record<string, unknown>>;
+    /**
+     * Cancel an outstanding order by id.
+     *
+     * Throws `SenpiClientError` on outer envelope or inner engine failure
+     * (same shape as {@link closePosition}).
+     */
+    cancelOrder(wallet: string, orderId: number): Promise<Record<string, unknown>>;
     getAssetTradingLimits(wallet: string, coin: string, dex?: string): Promise<{
         maxLeverage: number;
     } | null>;

package/dist/senpi/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/senpi/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/senpi/client.ts"],"names":[],"mappings":"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"}

package/dist/senpi/client.js

@@ -6,6 +6,99 @@ import { extractMinClearingHouseTime, createClearingHouseStalenessGuard } from "
 import { normalizeDslCoinDex, reconcileDexFromClearingHouseKey } from "../utils/perp-coin.js";
 import { createLogger } from "../utils/logger.js";
 const logger = createLogger("[senpi][client]");
+/**
+ * Typed error thrown by `SenpiClient` mutation methods when the response
+ * reports a failure at either layer (outer MCP envelope or inner engine
+ * result). Callers that today only catch `throw` will fire on real
+ * failures instead of silently treating phantom-success responses as
+ * success — preventing the orphaned-DSL-state class of bug.
+ *
+ * Codes:
+ *  - `UNEXPECTED_RESPONSE` — response shape is not the expected object.
+ *  - `UPSTREAM_ERROR`      — outer MCP envelope `success === false`.
+ *  - `ENGINE_FAILURE`      — outer envelope ok, but inner engine result
+ *                            reported `success === false` (e.g. CREATE_ORDER_RESTING).
+ */
+export class SenpiClientError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "SenpiClientError";
+        this.code = code;
+        this.details = details;
+    }
+}
+/**
+ * Best-effort engine error message extraction. Mirrors the resolver used
+ * inside the MCP server's mutation handlers (Task 2 fix shape) so DSL/
+ * action logs surface the same string the operator sees in audit logs.
+ */
+function extractEngineMessage(data) {
+    const err = data.error;
+    if (err && typeof err === "object") {
+        const errObj = err;
+        const description = typeof errObj.description === "string" ? errObj.description : undefined;
+        const errMessage = typeof errObj.message === "string" ? errObj.message : undefined;
+        const errCode = typeof errObj.code === "string" ? errObj.code : undefined;
+        const text = description ?? errMessage;
+        if (text && errCode)
+            return `${errCode}: ${text}`;
+        if (text)
+            return text;
+        if (errCode)
+            return errCode;
+    }
+    else if (typeof err === "string" && err.length > 0) {
+        return err;
+    }
+    if (typeof data.message === "string" && data.message.length > 0)
+        return data.message;
+    if (typeof data.errorCode === "string" && data.errorCode.length > 0)
+        return data.errorCode;
+    return "Trading engine reported failure";
+}
+/**
+ * Enforces success at both response layers and returns the unwrapped
+ * inner data. Throws `SenpiClientError` on any reported failure.
+ *
+ * Resolution order:
+ *  1. `raw` is not an object → `UNEXPECTED_RESPONSE`.
+ *  2. Outer envelope `success === false` → `UPSTREAM_ERROR` with the
+ *     envelope's error.code / error.message preserved.
+ *  3. Unwrap envelope to inner data; if not an object → `UNEXPECTED_RESPONSE`.
+ *  4. Inner data carries a boolean `success === false` → `ENGINE_FAILURE`
+ *     with a best-effort engine message.
+ *  5. Otherwise return the inner data.
+ *
+ * Used by every mutation method (createPosition, editPosition,
+ * closePosition, etc.) so DSL/actions can rely on `throw` semantics
+ * matching real failures, instead of trusting an outer-envelope-only
+ * "success" that may mask an engine rejection.
+ */
+function requireMutationSuccess(tool, raw) {
+    if (!isRecord(raw)) {
+        throw new SenpiClientError("UNEXPECTED_RESPONSE", `${tool}: response is not an object`, raw);
+    }
+    // Outer envelope check — only present on direct MCP responses.
+    if (raw.success === false) {
+        const errObj = isRecord(raw.error) ? raw.error : undefined;
+        const code = (errObj && typeof errObj.code === "string") ? errObj.code : "UPSTREAM_ERROR";
+        const message = (errObj && typeof errObj.message === "string")
+            ? errObj.message
+            : `${tool}: outer envelope reported failure`;
+        throw new SenpiClientError("UPSTREAM_ERROR", `${tool}: ${code}: ${message}`, raw);
+    }
+    const data = unwrapEnvelope(raw) ?? raw;
+    if (!isRecord(data)) {
+        throw new SenpiClientError("UNEXPECTED_RESPONSE", `${tool}: inner data is not an object`, raw);
+    }
+    // Inner engine-level success check (only when the field is explicitly boolean).
+    if (typeof data.success === "boolean" && data.success === false) {
+        throw new SenpiClientError("ENGINE_FAILURE", `${tool}: ${extractEngineMessage(data)}`, data);
+    }
+    return data;
+}
 /**
  * execution_get_order_status payloads vary: flat `{ filled, status }` vs Hyperliquid-style
  * `{ status: "order", order: { status: "filled", order: {...} } }`. Top-level `status` may be a
@@ -125,7 +218,7 @@ export class SenpiClient {
             this.mcpClient = null;
         }
     }
-    async callTool(toolName, args) {
+    async callTool(toolName, args, opts) {
         // Injected mode: delegate directly
         if (this.injectedTransport) {
             return this.injectedTransport(toolName, args);
@@ -134,7 +227,9 @@ export class SenpiClient {
         if (!this.mcpClient) {
             throw new Error('SenpiClient not connected — call connect() first');
         }
-        const result = await this.mcpClient.callTool({ name: toolName, arguments: args });
+        const result = opts?.signal
+            ? await this.mcpClient.callTool({ name: toolName, arguments: args }, undefined, { signal: opts.signal })
+            : await this.mcpClient.callTool({ name: toolName, arguments: args });
         if (result.content && Array.isArray(result.content) && result.content.length > 0) {
             const part = result.content[0];
             if (part && 'text' in part && typeof part.text === 'string') {
@@ -148,6 +243,28 @@ export class SenpiClient {
         }
         return result;
     }
+    /**
+     * Run an MCP `audit_query` and return the unwrapped response payload.
+     *
+     * Stays a thin pass-through so the runtime layer (which owns the
+     * wallet→strategyId resolution and error mapping) can compose the call
+     * with full type-safety. Callers must already have set
+     * `resource_type` / `resource_id` if scoping is desired — this method
+     * does not interpret arguments.
+     *
+     * @param args  Arbitrary key/value map forwarded verbatim as the MCP
+     *              tool input. Caller is responsible for matching the
+     *              MCP `audit_query` schema.
+     * @param opts  Optional AbortSignal; when fired, the underlying MCP
+     *              `callTool` is cancelled (the SDK rejects with an
+     *              AbortError).
+     * @returns     The `.data` field of the MCP envelope when present;
+     *              otherwise the raw response.
+     */
+    async auditQuery(args, opts) {
+        const raw = await this.callTool('audit_query', args, opts);
+        return unwrapEnvelope(raw) ?? raw;
+    }
     /**
      * Returns an adapter compatible with SenpiToolClient so the same connection
      * can be used for scanner provider MCP tool calls (e.g. leaderboard_get_markets).
@@ -158,26 +275,48 @@ export class SenpiClient {
         };
     }
     // ─── Ratchet stop (DSL backend engine) ──────────────────────────────────────
+    /**
+     * Register a backend ratchet-stop (DSL Phase 2 handoff).
+     *
+     * Throws `SenpiClientError` on outer envelope failure or inner engine
+     * `success: false`. Callers' existing `if (result.success && result.position)`
+     * branches now treat the success path only — failures land in the
+     * surrounding try/catch instead of falling through.
+     */
     async addRatchetStop(input) {
         const raw = await this.callTool("ratchet_stop_add", {
             ...input,
             asset: dexQualifiedAsset(input.asset, input.dex),
         });
-        return this.unwrapRatchetStopResult(raw, "ratchet_stop_add");
+        return requireMutationSuccess("ratchet_stop_add", raw);
     }
+    /**
+     * Update an existing backend ratchet-stop.
+     *
+     * Throws `SenpiClientError` on outer envelope failure or inner engine
+     * `success: false`.
+     */
     async editRatchetStop(input) {
         const raw = await this.callTool("ratchet_stop_edit", {
             ...input,
             asset: dexQualifiedAsset(input.asset, input.dex),
         });
-        return this.unwrapRatchetStopResult(raw, "ratchet_stop_edit");
+        return requireMutationSuccess("ratchet_stop_edit", raw);
     }
+    /**
+     * Delete a backend ratchet-stop. Used during DSL teardown / handoff close.
+     *
+     * Throws `SenpiClientError` on outer envelope failure or inner engine
+     * `success: false`. Previously this method's `{ success: boolean }` return
+     * was ignored by every caller (only `throw` was caught), which left
+     * zombie ratchet-stops on the backend when the engine reported failure.
+     */
     async deleteRatchetStop(input) {
         const raw = await this.callTool("ratchet_stop_delete", {
             ...input,
             asset: dexQualifiedAsset(input.asset, input.dex),
         });
-        return this.unwrapRatchetStopResult(raw, "ratchet_stop_delete");
+        return requireMutationSuccess("ratchet_stop_delete", raw);
     }
     async queryRatchetStops(input) {
         const qualifiedAsset = input.asset ? dexQualifiedAsset(input.asset, input.dex) : undefined;
@@ -247,6 +386,21 @@ export class SenpiClient {
      * Set/update SL (and optionally TP) on an open position. Uses MCP edit_position.
      * For XYZ DEX pass dex: "xyz" so coin is sent as "xyz:COIN"; otherwise main DEX uses plain coin.
      */
+    /**
+     * Set / update an exchange-side stop loss (or perform other position
+     * edits) on an open position.
+     *
+     * Throws `SenpiClientError` when either response layer reports failure:
+     *  - `UPSTREAM_ERROR`  — MCP envelope `success: false`.
+     *  - `ENGINE_FAILURE`  — outer ok, inner engine `success: false`
+     *                        (e.g. position not found, SL placement rejected).
+     *
+     * Returning normally means the engine accepted the edit. The returned
+     * `EditPositionResult` carries `slOrderId` when an SL was placed/updated;
+     * a `null` slOrderId on a non-throwing return indicates the engine reported
+     * success without the expected SL artifact — caller should treat that as
+     * a soft failure (logged as a warn) and re-attempt on the next sync tick.
+     */
     async editPosition(wallet, payload) {
         const coin = payload.dex === "xyz" && payload.coin && !payload.coin.startsWith("xyz:")
             ? `xyz:${payload.coin}`
@@ -266,7 +420,10 @@ export class SenpiClient {
             rawKeys: isRecord(raw) ? Object.keys(raw) : [],
             rawShape: isRecord(raw) ? JSON.stringify(raw).slice(0, 500) : String(raw),
         });
-        const result = (unwrapEnvelope(raw) ?? raw);
+        // Throws on outer/inner success: false. Returning means the engine
+        // accepted the edit. Older callers that only catch `throw` will now
+        // see real failures instead of silently treating them as success.
+        const result = requireMutationSuccess("edit_position", raw);
         if (result && typeof result === "object" && !Array.isArray(result)) {
             const ro = result;
             const slOrderId = extractSlOrderId(ro, raw);
@@ -537,17 +694,33 @@ export class SenpiClient {
             return { success: false };
         return { success: data.success === true, message: asString(data.message) ?? undefined };
     }
+    /**
+     * Submit a batch close_positions MCP call.
+     *
+     * Throws `SenpiClientError` on outer envelope or inner engine failure
+     * (same shape as {@link closePosition}). Successful return means the
+     * batch was accepted; per-position confirmation must still come from
+     * position-tracker scanner events.
+     */
     async closePositions(wallet, positions) {
-        return this.callTool("strategy_close_positions", {
+        const raw = await this.callTool("strategy_close_positions", {
             strategy_wallet: wallet,
             positions,
         });
+        return requireMutationSuccess("strategy_close_positions", raw);
     }
+    /**
+     * Cancel an outstanding order by id.
+     *
+     * Throws `SenpiClientError` on outer envelope or inner engine failure
+     * (same shape as {@link closePosition}).
+     */
     async cancelOrder(wallet, orderId) {
-        return this.callTool("cancel_order", {
+        const raw = await this.callTool("cancel_order", {
             strategyWalletAddress: wallet,
             orderId,
         });
+        return requireMutationSuccess("cancel_order", raw);
     }
     async getAssetTradingLimits(wallet, coin, dex) {
         try {