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

package/dist/runtime-api/routes/signals.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Fastify route: `POST /signals`.
+ *
+ * Accepts a batch of signal items targeting one or more runtime wallets,
+ * groups them by `(address, scanner)` to avoid the per-key ingest lock, fans
+ * out groups in parallel, processes items within each group sequentially, and
+ * returns per-item results in input order.
+ *
+ * Business logic lives entirely in:
+ *  - `handlers/ingest-signals.ts` — per-item dispatch + error translation.
+ *  - `handlers/group-by-scanner.ts` — lock-aware grouping helper.
+ *
+ * This file contains only Fastify wiring and the handler-level cap check.
+ */
+import type { FastifyInstance } from "fastify";
+import type { RuntimeHandle } from "../../runtime/run.js";
+import type { Logger } from "../../utils/logger.js";
+/**
+ * Dependencies injected into the `/signals` route at registration time.
+ */
+export interface SignalsRouteDeps {
+    /** Live runtime handles maintained by the plugin, keyed by lowercased address. */
+    runtimeHandles: Map<string, RuntimeHandle>;
+    /** Logger instance for unexpected errors. */
+    logger: Logger;
+    /**
+     * Maximum number of items allowed in a single request.
+     * Sourced from `config.api.maxItemsPerSignalsRequest` (default 10).
+     */
+    maxItems: number;
+    /**
+     * Transport tag forwarded to the ingest handler for telemetry.
+     * Fixed as `"http"` for this route; the gateway shim passes `"gateway"`.
+     */
+    transport: "http" | "gateway";
+}
+/**
+ * Register `POST /signals` on the given Fastify instance.
+ *
+ * The route validates the body against the `SignalsBody` TypeBox schema, then:
+ * 1. Rejects oversized batches (handler-level cap, configurable).
+ * 2. Groups items by `(address, scanner)` via `groupByAddressScanner`.
+ * 3. Runs groups in parallel; items within each group run sequentially.
+ * 4. Re-flattens results back to input order before responding.
+ *
+ * @param fastify  Fastify instance to register the route on.
+ * @param deps     Route dependencies injected at plugin start.
+ */
+export declare function registerSignalsRoute(fastify: FastifyInstance, deps: SignalsRouteDeps): void;
+//# sourceMappingURL=signals.d.ts.map

package/dist/runtime-api/routes/signals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.d.ts","sourceRoot":"","sources":["../../../src/runtime-api/routes/signals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAM/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAwDpD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kFAAkF;IAClF,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC3C,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,gBAAgB,GACrB,IAAI,CA+CN"}

package/dist/runtime-api/routes/signals.js

@@ -0,0 +1,90 @@
+/**
+ * Fastify route: `POST /signals`.
+ *
+ * Accepts a batch of signal items targeting one or more runtime wallets,
+ * groups them by `(address, scanner)` to avoid the per-key ingest lock, fans
+ * out groups in parallel, processes items within each group sequentially, and
+ * returns per-item results in input order.
+ *
+ * Business logic lives entirely in:
+ *  - `handlers/ingest-signals.ts` — per-item dispatch + error translation.
+ *  - `handlers/group-by-scanner.ts` — lock-aware grouping helper.
+ *
+ * This file contains only Fastify wiring and the handler-level cap check.
+ */
+import { SignalsBody } from "./signals.schema.js";
+import { ingestSignalsHandler } from "../handlers/ingest-signals.js";
+import { groupByAddressScanner } from "../handlers/group-by-scanner.js";
+function toWire(r) {
+    if (r.success) {
+        return {
+            success: true,
+            address: r.address,
+            scanner: r.scanner,
+            data: {
+                timestamp: r.timestamp,
+                signalCount: r.signalCount,
+                contextUpdated: r.contextUpdated,
+            },
+        };
+    }
+    return {
+        success: false,
+        address: r.address,
+        scanner: r.scanner,
+        error: {
+            code: r.code,
+            message: r.message,
+        },
+    };
+}
+/**
+ * Register `POST /signals` on the given Fastify instance.
+ *
+ * The route validates the body against the `SignalsBody` TypeBox schema, then:
+ * 1. Rejects oversized batches (handler-level cap, configurable).
+ * 2. Groups items by `(address, scanner)` via `groupByAddressScanner`.
+ * 3. Runs groups in parallel; items within each group run sequentially.
+ * 4. Re-flattens results back to input order before responding.
+ *
+ * @param fastify  Fastify instance to register the route on.
+ * @param deps     Route dependencies injected at plugin start.
+ */
+export function registerSignalsRoute(fastify, deps) {
+    fastify.post("/signals", { schema: { body: SignalsBody } }, async (req, reply) => {
+        const items = req.body;
+        // Handler-level cap — operator-tunable, not encoded in the TypeBox schema.
+        if (items.length > deps.maxItems) {
+            return reply.status(400).send({
+                success: false,
+                error: {
+                    code: "INVALID_REQUEST",
+                    message: `Exceeded api.maxItemsPerSignalsRequest=${deps.maxItems}; got ${items.length}.`,
+                },
+            });
+        }
+        // Group by (address, scanner) — each group is a SignalGroup (IndexedSignalItem[]).
+        const groups = groupByAddressScanner(items);
+        // Fan out across groups in parallel; process items within each group sequentially.
+        const grouped = await Promise.all(groups.map(async (group) => {
+            const out = [];
+            for (const { index, item } of group) {
+                out.push({
+                    index,
+                    result: await ingestSignalsHandler(item, {
+                        runtimeHandles: deps.runtimeHandles,
+                        logger: deps.logger,
+                        transport: deps.transport,
+                    }),
+                });
+            }
+            return out;
+        }));
+        // Re-flatten in input order.
+        const flat = grouped.flat();
+        flat.sort((a, b) => a.index - b.index);
+        const results = flat.map((entry) => toWire(entry.result));
+        return reply.send({ success: true, data: { results } });
+    });
+}
+//# sourceMappingURL=signals.js.map

package/dist/runtime-api/routes/signals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.js","sourceRoot":"","sources":["../../../src/runtime-api/routes/signals.ts"],"names":[],"mappings":"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"}

package/dist/runtime-api/routes/signals.schema.d.ts

@@ -0,0 +1,94 @@
+/**
+ * TypeBox schema for the `POST /signals` request body.
+ *
+ * `SignalItemT` is derived from TypeBox `Static<>` and is structurally
+ * compatible with the hand-written {@link SignalItem} interface in
+ * `handlers/types.ts`. The interface in `handlers/types.ts` is kept as the
+ * canonical description (referenced by JSDoc across the codebase); this module
+ * derives the runtime-validatable form from TypeBox so both shapes stay in
+ * sync at compile-time.
+ *
+ * Note on `direction`: the TypeBox schema accepts any string so
+ * `SignalItemT["direction"]` is `string | undefined`, matching
+ * `Signal["direction"]` in `scanners/types.ts`. The tighter
+ * `"long" | "short" | null` constraint lives in the MCP layer; the runtime
+ * applies it implicitly during scanner-engine ingest.
+ *
+ * Note on `maxItems`: enforced at handler level using the configured
+ * `api.maxItemsPerSignalsRequest` value (default 10). Schema-level cap is
+ * kept open-ended so the shape works in tests without recompiling.
+ */
+import { type Static } from "@sinclair/typebox";
+/** TypeBox schema for one item in the `POST /signals` body. */
+export declare const SignalItem: import("@sinclair/typebox").TObject<{
+    /** Wallet address of the target runtime. Lowercased server-side. */
+    address: import("@sinclair/typebox").TString;
+    /** Configured scanner id. */
+    scanner: import("@sinclair/typebox").TString;
+    /** Asset for a single ingested signal. */
+    asset: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    /**
+     * Direction for a single ingested signal.
+     * Accepts any string — `"long"` / `"short"` are the conventional values.
+     */
+    direction: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    /** Confidence score for a single ingested signal (0–1). */
+    score: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    /** Signal classification override for a single ingested signal. */
+    signal_type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    /**
+     * Single ingest payload for signal-producing or context-producing scanners.
+     * Mutually exclusive with `signals[]`.
+     */
+    data: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>>;
+    /**
+     * Batch signal payloads for signal-producing external scanners.
+     * Mutually exclusive with `data`.
+     */
+    signals: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        asset: import("@sinclair/typebox").TString;
+        direction: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        score: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+        signal_type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        data: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>;
+    }>>>;
+}>;
+/** TypeBox schema for the full `POST /signals` request body array. */
+export declare const SignalsBody: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+    /** Wallet address of the target runtime. Lowercased server-side. */
+    address: import("@sinclair/typebox").TString;
+    /** Configured scanner id. */
+    scanner: import("@sinclair/typebox").TString;
+    /** Asset for a single ingested signal. */
+    asset: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    /**
+     * Direction for a single ingested signal.
+     * Accepts any string — `"long"` / `"short"` are the conventional values.
+     */
+    direction: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    /** Confidence score for a single ingested signal (0–1). */
+    score: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    /** Signal classification override for a single ingested signal. */
+    signal_type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    /**
+     * Single ingest payload for signal-producing or context-producing scanners.
+     * Mutually exclusive with `signals[]`.
+     */
+    data: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>>;
+    /**
+     * Batch signal payloads for signal-producing external scanners.
+     * Mutually exclusive with `data`.
+     */
+    signals: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        asset: import("@sinclair/typebox").TString;
+        direction: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        score: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+        signal_type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        data: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>;
+    }>>>;
+}>>;
+/** TypeScript type for one signal item — derived from TypeBox, single source of truth. */
+export type SignalItemT = Static<typeof SignalItem>;
+/** TypeScript type for the `POST /signals` request body. */
+export type SignalsBodyT = Static<typeof SignalsBody>;
+//# sourceMappingURL=signals.schema.d.ts.map

package/dist/runtime-api/routes/signals.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.schema.d.ts","sourceRoot":"","sources":["../../../src/runtime-api/routes/signals.schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAQ,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEtD,+DAA+D;AAC/D,eAAO,MAAM,UAAU;IAEnB,oEAAoE;;IAEpE,6BAA6B;;IAE7B,0CAA0C;;IAE1C;;;OAGG;;IAEH,2DAA2D;;IAE3D,mEAAmE;;IAEnE;;;OAGG;;IAEH;;;OAGG;;;;;;;;EAcN,CAAC;AAEF,sEAAsE;AACtE,eAAO,MAAM,WAAW;IAxCpB,oEAAoE;;IAEpE,6BAA6B;;IAE7B,0CAA0C;;IAE1C;;;OAGG;;IAEH,2DAA2D;;IAE3D,mEAAmE;;IAEnE;;;OAGG;;IAEH;;;OAGG;;;;;;;;GAiB2D,CAAC;AAEnE,0FAA0F;AAC1F,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,4DAA4D;AAC5D,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC"}

package/dist/runtime-api/routes/signals.schema.js

@@ -0,0 +1,58 @@
+/**
+ * TypeBox schema for the `POST /signals` request body.
+ *
+ * `SignalItemT` is derived from TypeBox `Static<>` and is structurally
+ * compatible with the hand-written {@link SignalItem} interface in
+ * `handlers/types.ts`. The interface in `handlers/types.ts` is kept as the
+ * canonical description (referenced by JSDoc across the codebase); this module
+ * derives the runtime-validatable form from TypeBox so both shapes stay in
+ * sync at compile-time.
+ *
+ * Note on `direction`: the TypeBox schema accepts any string so
+ * `SignalItemT["direction"]` is `string | undefined`, matching
+ * `Signal["direction"]` in `scanners/types.ts`. The tighter
+ * `"long" | "short" | null` constraint lives in the MCP layer; the runtime
+ * applies it implicitly during scanner-engine ingest.
+ *
+ * Note on `maxItems`: enforced at handler level using the configured
+ * `api.maxItemsPerSignalsRequest` value (default 10). Schema-level cap is
+ * kept open-ended so the shape works in tests without recompiling.
+ */
+import { Type } from "@sinclair/typebox";
+/** TypeBox schema for one item in the `POST /signals` body. */
+export const SignalItem = Type.Object({
+    /** Wallet address of the target runtime. Lowercased server-side. */
+    address: Type.String({ minLength: 1 }),
+    /** Configured scanner id. */
+    scanner: Type.String({ minLength: 1 }),
+    /** Asset for a single ingested signal. */
+    asset: Type.Optional(Type.String()),
+    /**
+     * Direction for a single ingested signal.
+     * Accepts any string — `"long"` / `"short"` are the conventional values.
+     */
+    direction: Type.Optional(Type.String()),
+    /** Confidence score for a single ingested signal (0–1). */
+    score: Type.Optional(Type.Number({ minimum: 0, maximum: 1 })),
+    /** Signal classification override for a single ingested signal. */
+    signal_type: Type.Optional(Type.String()),
+    /**
+     * Single ingest payload for signal-producing or context-producing scanners.
+     * Mutually exclusive with `signals[]`.
+     */
+    data: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+    /**
+     * Batch signal payloads for signal-producing external scanners.
+     * Mutually exclusive with `data`.
+     */
+    signals: Type.Optional(Type.Array(Type.Object({
+        asset: Type.String(),
+        direction: Type.Optional(Type.String()),
+        score: Type.Optional(Type.Number({ minimum: 0, maximum: 1 })),
+        signal_type: Type.Optional(Type.String()),
+        data: Type.Record(Type.String(), Type.Unknown()),
+    }))),
+}, { additionalProperties: false });
+/** TypeBox schema for the full `POST /signals` request body array. */
+export const SignalsBody = Type.Array(SignalItem, { minItems: 1 });
+//# sourceMappingURL=signals.schema.js.map

package/dist/runtime-api/routes/signals.schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.schema.js","sourceRoot":"","sources":["../../../src/runtime-api/routes/signals.schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,IAAI,EAAe,MAAM,mBAAmB,CAAC;AAEtD,+DAA+D;AAC/D,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CACnC;IACE,oEAAoE;IACpE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IACtC,6BAA6B;IAC7B,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IACtC,0CAA0C;IAC1C,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IACnC;;;OAGG;IACH,SAAS,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IACvC,2DAA2D;IAC3D,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;IAC7D,mEAAmE;IACnE,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IACzC;;;OAGG;IACH,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAC/D;;;OAGG;IACH,OAAO,EAAE,IAAI,CAAC,QAAQ,CACpB,IAAI,CAAC,KAAK,CACR,IAAI,CAAC,MAAM,CAAC;QACV,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE;QACpB,SAAS,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;QACvC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;QAC7D,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;QACzC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;KACjD,CAAC,CACH,CACF;CACF,EACD,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAChC,CAAC;AAEF,sEAAsE;AACtE,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC"}

package/dist/runtime-api/server.d.ts

@@ -0,0 +1,79 @@
+/**
+ * `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 { type FastifyInstance } from "fastify";
+import { createReadiness } from "./readiness.js";
+import type { RuntimeHandle } from "../runtime/run.js";
+import type { Logger } from "../utils/logger.js";
+import type { ApiConfig } from "./config.js";
+/**
+ * Dependencies passed to {@link createApi}.
+ */
+export interface CreateApiDeps {
+    /** Live runtime handles maintained by the plugin, keyed by lowercased address. */
+    runtimeHandles: Map<string, RuntimeHandle>;
+    /** Validated `api` config block (host, port, maxItemsPerSignalsRequest). */
+    apiConfig: ApiConfig;
+    /** Logger instance — forwarded to shared handlers for structured error logging. */
+    logger: Logger;
+    /**
+     * Plugin version string read from `openclaw.plugin.json` at boot.
+     * Exposed in `GET /health` so callers can correlate requests with deployments.
+     */
+    version: string;
+}
+/**
+ * Artifacts returned by {@link createApi}.
+ *
+ * Ownership:
+ *  - `fastify`   — call `.listen()` and `.close()` in the lifecycle layer (S5).
+ *  - `readiness` — call `setOk()` after `.listen()` resolves; `setDraining()`
+ *                  before `.close()` during graceful shutdown.
+ *  - `bootedAt`  — Unix epoch ms recorded when `createApi()` was called;
+ *                  used by `GET /health` to compute `uptime_ms`.
+ */
+export interface ApiArtifacts {
+    fastify: FastifyInstance;
+    readiness: ReturnType<typeof createReadiness>;
+    bootedAt: number;
+}
+/**
+ * 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 declare function createApi(deps: CreateApiDeps): ApiArtifacts;
+//# sourceMappingURL=server.d.ts.map

package/dist/runtime-api/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/runtime-api/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,SAAS,CAAC;AAIxD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,kFAAkF;IAClF,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC3C,4EAA4E;IAC5E,SAAS,EAAE,SAAS,CAAC;IACrB,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;IAC9C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,YAAY,CAqE3D"}

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>;