@senpi/runtime 3.0.135 → 3.0.139

package/dist/runtime/strategies-telemetry.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Strategies telemetry: the payload built from the strategies store, and the loop that broadcasts
+ * that payload as `plugin.senpi.strategies`.
+ */
+import type { DslState } from "../types/dsl/index.js";
+import type { StrategyRecord } from "./strategies-store.js";
+/** Minted once per plugin process. `plugin.senpi.events` carries the same value. */
+export declare const PROCESS_EPOCH: `${string}-${string}-${string}-${string}-${string}`;
+export interface StrategyScannerPayload {
+    scannerId: string;
+    intervalSeconds: number;
+    lastAliveAt: number | null;
+}
+export interface StrategyDslTierPayload {
+    triggerPct: number;
+    lockHwPct: number;
+    triggerPrice: number;
+    reached: boolean;
+}
+export interface StrategyDslPayload {
+    asset: string;
+    dex: string;
+    direction: "LONG" | "SHORT";
+    entryPrice: number;
+    leverage: number;
+    phase: 1 | 2;
+    firstStopLoss: number;
+    lastPrice: number;
+    lastPriceAt: number | null;
+    floorPrice: number;
+    currentTierIndex: number | null;
+    tierSince: number | null;
+    tiers: StrategyDslTierPayload[];
+}
+export interface StrategyPayload {
+    address: string;
+    name: string;
+    scanners: StrategyScannerPayload[];
+    dsl: StrategyDslPayload[];
+}
+export interface StrategiesPayload {
+    v: 1;
+    epoch: string;
+    generatedAt: number;
+    strategies: StrategyPayload[];
+}
+/** Liveness of one external scanner, epoch ms, or `null` when nothing was heard since the child (re)started. */
+export type LastAliveAtFn = (runtimeId: string, scannerName: string) => number | null;
+/** Active DSL states of one runtime, read from memory. `[]` when the runtime has no handle or no DSL. */
+export type DslStatesFn = (runtimeId: string) => readonly DslState[];
+export type StrategiesBroadcastFn = (event: string, payload: unknown, opts?: {
+    dropIfSlow?: boolean;
+}) => void;
+/**
+ * Builds the payload from the store and the DSL states. Copies only the payload fields from each
+ * DSL state. A runtime's state manager loads every address directory under its state directory.
+ * Only DSL states with a string `address` equal to the strategy wallet are kept.
+ */
+export declare function buildStrategiesPayload(input: {
+    epoch: string;
+    generatedAt: number;
+    store: ReadonlyMap<string, StrategyRecord>;
+    lastAliveAt: LastAliveAtFn;
+    dslStates: DslStatesFn;
+    /** Called with the runtime id when reading or copying that runtime's DSL states throws. */
+    onDslError?: (runtimeId: string, err: unknown) => void;
+}): StrategiesPayload;
+export interface StrategiesPublisher {
+    /** Ticks once, then every interval. A second call while running does nothing. */
+    start(): void;
+    /** Stops the ticks and resets the last payload to `strategies: []`. */
+    stop(): void;
+    /** The payload of the last tick. Before the first tick and after stop: `strategies: []`. */
+    lastPayload(): StrategiesPayload;
+}
+/**
+ * Each tick builds the payload from the store, the liveness reader and the DSL state reader, keeps
+ * it as the last payload, and broadcasts it when a broadcast function is available. The loop reads
+ * the store and never writes it.
+ */
+export declare function createStrategiesPublisher(deps: {
+    store: ReadonlyMap<string, StrategyRecord>;
+    lastAliveAt: LastAliveAtFn;
+    dslStates: DslStatesFn;
+    getBroadcast: () => StrategiesBroadcastFn | undefined;
+    onError?: (err: unknown) => void;
+    onDslError?: (runtimeId: string, err: unknown) => void;
+    epoch?: string;
+    now?: () => number;
+}): StrategiesPublisher;
+//# sourceMappingURL=strategies-telemetry.d.ts.map

package/dist/runtime/strategies-telemetry.d.ts.map

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

package/dist/runtime/strategies-telemetry.js

@@ -0,0 +1,128 @@
+/**
+ * Strategies telemetry: the payload built from the strategies store, and the loop that broadcasts
+ * that payload as `plugin.senpi.strategies`.
+ */
+import { randomUUID } from "node:crypto";
+import { STRATEGIES_EVENT_NAME, STRATEGIES_PUBLISH_INTERVAL_MS } from "../constants/telemetry.js";
+/** Minted once per plugin process. `plugin.senpi.events` carries the same value. */
+export const PROCESS_EPOCH = randomUUID();
+function normalizeAddress(address) {
+    return address.trim().toLowerCase();
+}
+/** Epoch ms of an ISO string, or `null` when it does not parse. */
+function epochMsOrNull(iso) {
+    const ms = Date.parse(iso);
+    return Number.isNaN(ms) ? null : ms;
+}
+/**
+ * Copies the payload fields of one DSL state into new objects.
+ *
+ * `triggerPrice` solves the move check of `tierIndexFromPrice` (`src/dsl/engine/floors.ts`) for
+ * equality: the price move from entry, times leverage, in percent, equals `triggerPct`. In floating
+ * point, `tierIndexFromPrice` at exactly `triggerPrice` can compute a move a few ulps below
+ * `triggerPct`.
+ */
+function dslPayloadFromState(state) {
+    const sign = state.direction === "LONG" ? 1 : -1;
+    const current = state.currentTierIndex;
+    return {
+        asset: state.asset,
+        dex: state.dex,
+        direction: state.direction,
+        entryPrice: state.entryPrice,
+        leverage: state.leverage,
+        phase: state.phase,
+        firstStopLoss: state.phase1.absoluteFloor,
+        lastPrice: state.lastPrice,
+        lastPriceAt: epochMsOrNull(state.lastCheck),
+        floorPrice: state.floorPrice,
+        currentTierIndex: current,
+        tierSince: state.tierSince === null ? null : epochMsOrNull(state.tierSince),
+        tiers: state.tiers.map((tier, i) => ({
+            triggerPct: tier.triggerPct,
+            lockHwPct: tier.lockHwPct,
+            triggerPrice: state.entryPrice * (1 + (sign * tier.triggerPct) / 100 / state.leverage),
+            reached: current !== null && i <= current,
+        })),
+    };
+}
+/**
+ * Builds the payload from the store and the DSL states. Copies only the payload fields from each
+ * DSL state. A runtime's state manager loads every address directory under its state directory.
+ * Only DSL states with a string `address` equal to the strategy wallet are kept.
+ */
+export function buildStrategiesPayload(input) {
+    const strategies = [];
+    // A throw while reading or copying one runtime's DSL states gives that strategy `dsl: []`.
+    const dslRows = (runtimeId, address) => {
+        try {
+            return input
+                .dslStates(runtimeId)
+                .filter((state) => typeof state.address === "string" && normalizeAddress(state.address) === address)
+                .map(dslPayloadFromState);
+        }
+        catch (err) {
+            input.onDslError?.(runtimeId, err);
+            return [];
+        }
+    };
+    for (const [runtimeId, record] of input.store) {
+        const address = normalizeAddress(record.address);
+        strategies.push({
+            address,
+            name: record.name,
+            scanners: record.scanners.map((scanner) => ({
+                scannerId: scanner.scannerId,
+                intervalSeconds: scanner.intervalSeconds,
+                lastAliveAt: input.lastAliveAt(runtimeId, scanner.scannerId),
+            })),
+            dsl: dslRows(runtimeId, address),
+        });
+    }
+    return { v: 1, epoch: input.epoch, generatedAt: input.generatedAt, strategies };
+}
+/**
+ * Each tick builds the payload from the store, the liveness reader and the DSL state reader, keeps
+ * it as the last payload, and broadcasts it when a broadcast function is available. The loop reads
+ * the store and never writes it.
+ */
+export function createStrategiesPublisher(deps) {
+    const epoch = deps.epoch ?? PROCESS_EPOCH;
+    const now = deps.now ?? Date.now;
+    const empty = () => ({ v: 1, epoch, generatedAt: now(), strategies: [] });
+    let last = empty();
+    let timer;
+    const tick = () => {
+        try {
+            last = buildStrategiesPayload({
+                epoch,
+                generatedAt: now(),
+                store: deps.store,
+                lastAliveAt: deps.lastAliveAt,
+                dslStates: deps.dslStates,
+                onDslError: deps.onDslError,
+            });
+            deps.getBroadcast()?.(STRATEGIES_EVENT_NAME, last, { dropIfSlow: true });
+        }
+        catch (err) {
+            deps.onError?.(err);
+        }
+    };
+    return {
+        start() {
+            if (timer !== undefined)
+                return;
+            tick();
+            timer = setInterval(tick, STRATEGIES_PUBLISH_INTERVAL_MS);
+            timer.unref?.();
+        },
+        stop() {
+            if (timer !== undefined)
+                clearInterval(timer);
+            timer = undefined;
+            last = empty();
+        },
+        lastPayload: () => last,
+    };
+}
+//# sourceMappingURL=strategies-telemetry.js.map

package/dist/runtime/strategies-telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategies-telemetry.js","sourceRoot":"","sources":["../../src/runtime/strategies-telemetry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,qBAAqB,EAAE,8BAA8B,EAAE,MAAM,2BAA2B,CAAC;AAIlG,oFAAoF;AACpF,MAAM,CAAC,MAAM,aAAa,GAAG,UAAU,EAAE,CAAC;AAyD1C,SAAS,gBAAgB,CAAC,OAAe;IACvC,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AACtC,CAAC;AAED,mEAAmE;AACnE,SAAS,aAAa,CAAC,GAAW;IAChC,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,OAAO,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;AACtC,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,mBAAmB,CAAC,KAAe;IAC1C,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,KAAK,CAAC,gBAAgB,CAAC;IACvC,OAAO;QACL,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,aAAa;QACzC,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,WAAW,EAAE,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC;QAC3C,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,gBAAgB,EAAE,OAAO;QACzB,SAAS,EAAE,KAAK,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC;QAC3E,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;YACnC,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,YAAY,EAAE,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,GAAG,GAAG,KAAK,CAAC,QAAQ,CAAC;YACtF,OAAO,EAAE,OAAO,KAAK,IAAI,IAAI,CAAC,IAAI,OAAO;SAC1C,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAQtC;IACC,MAAM,UAAU,GAAsB,EAAE,CAAC;IACzC,2FAA2F;IAC3F,MAAM,OAAO,GAAG,CAAC,SAAiB,EAAE,OAAe,EAAwB,EAAE;QAC3E,IAAI,CAAC;YACH,OAAO,KAAK;iBACT,SAAS,CAAC,SAAS,CAAC;iBACpB,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,IAAI,gBAAgB,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC;iBACnG,GAAG,CAAC,mBAAmB,CAAC,CAAC;QAC9B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,KAAK,CAAC,UAAU,EAAE,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;YACnC,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC,CAAC;IACF,KAAK,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAC9C,MAAM,OAAO,GAAG,gBAAgB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACjD,UAAU,CAAC,IAAI,CAAC;YACd,OAAO;YACP,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;gBAC1C,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,eAAe,EAAE,OAAO,CAAC,eAAe;gBACxC,WAAW,EAAE,KAAK,CAAC,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC,SAAS,CAAC;aAC7D,CAAC,CAAC;YACH,GAAG,EAAE,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC;SACjC,CAAC,CAAC;IACL,CAAC;IACD,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,UAAU,EAAE,CAAC;AAClF,CAAC;AAWD;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,IASzC;IACC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,aAAa,CAAC;IAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IACjC,MAAM,KAAK,GAAG,GAAsB,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC;IAC7F,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;IACnB,IAAI,KAAiD,CAAC;IAEtD,MAAM,IAAI,GAAG,GAAS,EAAE;QACtB,IAAI,CAAC;YACH,IAAI,GAAG,sBAAsB,CAAC;gBAC5B,KAAK;gBACL,WAAW,EAAE,GAAG,EAAE;gBAClB,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,UAAU,EAAE,IAAI,CAAC,UAAU;aAC5B,CAAC,CAAC;YACH,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC,qBAAqB,EAAE,IAAI,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3E,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC;QACtB,CAAC;IACH,CAAC,CAAC;IAEF,OAAO;QACL,KAAK;YACH,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO;YAChC,IAAI,EAAE,CAAC;YACP,KAAK,GAAG,WAAW,CAAC,IAAI,EAAE,8BAA8B,CAAC,CAAC;YAC1D,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;QAClB,CAAC;QACD,IAAI;YACF,IAAI,KAAK,KAAK,SAAS;gBAAE,aAAa,CAAC,KAAK,CAAC,CAAC;YAC9C,KAAK,GAAG,SAAS,CAAC;YAClB,IAAI,GAAG,KAAK,EAAE,CAAC;QACjB,CAAC;QACD,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI;KACxB,CAAC;AACJ,CAAC"}

package/dist/runtime/strategy-lifecycle.d.ts

@@ -1,12 +1,32 @@
 /**
- * In-memory seed of the Theme-4 strategy lifecycle state machine (running→paused→stopped).
- * Short-term (§4); the durable crash-safe (SQLite) version is §5 merge work.
+ * Seed of the Theme-4 strategy lifecycle state machine (running→paused→stopped). The self-pause
+ * state is in memory; the halt latches are persisted (below). Short-term (§4); the durable
+ * crash-safe (SQLite) version is §5 merge work.
  *
  * Owns the self-pause state that RiskGuard used to hold. RiskGuard is now a stateless
  * gate evaluator that only reports; this component remembers which gates are currently
  * paused per strategy and fires the hook event + user notification on a genuine
  * running→paused transition, deduped so it alerts once per breach and re-arms only on
  * an explicit OPEN (re-running) of the same gate.
+ *
+ * It also owns the halt LATCH for the halt-class gates in {@link LATCHED_GATES}
+ * (daily loss, drawdown). Their live inputs are mark-to-market, so a strategy sitting
+ * near its limit reads breached / not-breached on every price bounce; without a latch
+ * each bounce reopened entries mid-day. {@link StrategyLifecycle.applyLatch} is called by
+ * the risk guard on every evaluation of those gates and overrides a fresh OPEN with
+ * CLOSED until the latch's release rule fires:
+ *   - daily_loss_halt: the next UTC day (day taken from the MCP snapshot, not the box clock);
+ *   - drawdown_halt: the next UTC day only when `drawdown_reset_on_day_rollover` is true;
+ *     otherwise never.
+ * A latch for a gate that is no longer configured is dropped when the recipe is rebuilt
+ * ({@link StrategyLifecycle.pruneLatches}), so re-adding the rail later starts clean.
+ *
+ * Latches are persisted per strategy through {@link StrategyLifecycleDeps.latchStore} (the
+ * runtime's StateManager, file `<stateDir>/<address>/risk-halt-latch.json`), so a latch survives
+ * a gateway restart, an npm auto-update and a fleet redeploy: the restarted runtime reloads it on
+ * the strategy's first halt check and enforces it exactly as before, with the same release rules.
+ * The self-pause state above is still in memory only, so a restored latch announces its pause
+ * once more after a restart.
  */
 import type { RiskGateEvaluation, RiskGateId, RiskSource } from "../health/types.js";
 import type { HookSystem } from "../types/hooks.js";
@@ -43,6 +63,62 @@ export interface StrategyLifecycleDeps {
     notifications?: NotificationService;
     /** Runtime name attached to fired hook events (defaults to "runtime"). */
     runtimeName?: string;
+    /**
+     * Durable home for the halt latches (the runtime passes its StateManager). Without it the
+     * latches live in memory only and a gateway restart forgets them, which is the behaviour tests
+     * and the stub path get.
+     */
+    latchStore?: HaltLatchStore;
+}
+/**
+ * The slice of StateManager the halt latch persists through. Typed structurally so a test can
+ * hand in a fake; StateManager satisfies it as-is.
+ *
+ * Contract relied on: `getOrLoad` resolves undefined when nothing is stored (StateManager also
+ * resolves undefined for a corrupt file, which it tombstones and warns about) and REJECTS on a
+ * transient IO error; `set` persists durably or rejects.
+ */
+export interface HaltLatchStore {
+    getOrLoad(key: string): Promise<unknown>;
+    set(key: string, value: unknown): Promise<void>;
+}
+/**
+ * State key of a strategy's persisted halt latches. StateManager maps it to
+ * `<stateDir>/<address>/risk-halt-latch.json`: inside the strategy's own dir, so it is archived
+ * with the strategy, and not `strategy` / `dsl-*`, so hydrate and the DSL listings ignore it.
+ */
+export declare function haltLatchKey(address: string): string;
+/** Schema version of the persisted latch file; any other version is read as "no latch". */
+export declare const HALT_LATCH_STATE_VERSION = 1;
+/**
+ * Halt-class gates whose genuine breach latches until its release rule fires, instead of
+ * reopening on the next non-breached reading. `max_entries_day` is deliberately absent:
+ * its mid-day reopen is tracked separately and keeps the pre-latch behaviour here.
+ */
+export declare const LATCHED_GATES: ReadonlySet<RiskGateId>;
+export interface ApplyLatchOpts {
+    /**
+     * Release the latch when an evaluation from a later UTC day arrives. Always true for
+     * daily_loss_halt; `drawdown_reset_on_day_rollover` for drawdown_halt.
+     */
+    releaseOnDayRollover: boolean;
+}
+/** What a latch remembers about the breach that set it. Also its persisted per-gate shape. */
+export interface HaltLatch {
+    /** UTC day (YYYY-MM-DD) of the snapshot that tripped the gate. */
+    utcDay: string;
+    /** Wall-clock ISO time the latch was set. */
+    latchedAt: string;
+    /** The breaching evaluation's own reason (live numbers at trip time). */
+    trippedReason: string;
+}
+/**
+ * On-disk shape of one strategy's halt latches. An address with nothing latched is written as
+ * `{ version: 1, gates: {} }` rather than deleted, so "cleared" is a durable fact too.
+ */
+export interface PersistedHaltLatches {
+    version: typeof HALT_LATCH_STATE_VERSION;
+    gates: Partial<Record<RiskGateId, HaltLatch>>;
 }
 export interface StrategyLifecycle {
     /**
@@ -53,6 +129,36 @@ export interface StrategyLifecycle {
      * @param source   evaluation source (runtime / cli)
      */
     observe(address: string, label: string, evaluations: RiskGateEvaluation[], source: RiskSource): void;
+    /**
+     * Apply the halt latch to one fresh evaluation of a {@link LATCHED_GATES} gate and return
+     * the evaluation to enforce (other gates pass through untouched).
+     *
+     * - A genuine breach (CLOSED + evaluationOk + no fallback) sets the latch if none is held.
+     *   Fail-closed / fallback evaluations never set it.
+     * - While latched, a fresh OPEN is overridden to CLOSED with a latched reason and
+     *   `evaluationOk: true` — the evaluation itself succeeded; the gate is closed by the latch.
+     * - The latch is released only by a successful evaluation from a later UTC day, and only
+     *   when `opts.releaseOnDayRollover` is true. The fresh evaluation is then enforced as-is.
+     *
+     * Async because of persistence: the strategy's persisted latches are loaded on its first call,
+     * and a set or release is written before the verdict returns. It cannot throw.
+     * - A failed load fails closed for that call: CLOSED with `evaluationOk: false`,
+     *   `fallbackApplied: true`, `failureKind: "transport"`, like a failed snapshot fetch. A latch on
+     *   disk this process has not read must not read as OPEN. Nothing is set or released on that
+     *   call, so no pause fires; the next call retries the load.
+     * - A failed write is logged and never changes the verdict: the in-memory latch keeps enforcing.
+     */
+    applyLatch(address: string, evaluation: RiskGateEvaluation, opts: ApplyLatchOpts): Promise<RiskGateEvaluation>;
+    /**
+     * Drop the latches (and the matching pause state) of latched gates that are no longer
+     * configured for `address`. Called when the recipe is rebuilt: a gate whose rail was removed
+     * no longer enforces anything, so its latch must not resurface if the rail is added back later.
+     * Emits `runtime.resumed` for a dropped gate that was paused.
+     *
+     * Loads the persisted latches first (so a latch saved by an earlier process is pruned too) and
+     * writes the result. Never throws: the rebuild commit that calls it must not fail on disk IO.
+     */
+    pruneLatches(address: string, configured: ReadonlySet<RiskGateId>): Promise<void>;
 }
 export declare function createStrategyLifecycle(deps?: StrategyLifecycleDeps): StrategyLifecycle;
 export {};

package/dist/runtime/strategy-lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strategy-lifecycle.d.ts","sourceRoot":"","sources":["../../src/runtime/strategy-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,KAAK,EAAE,gBAAgB,EAAuB,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAO3G;;;kEAGkE;AAClE,UAAU,SAAS;IACjB,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd;2DACuD;IACvD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC,CAIrE,CAAC;AA6HF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EACnD,MAAM,EAAE,MAAM,GACb,gBAAgB,CAGlB;AAED,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,yEAAyE;IACzE,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,OAAO,CACL,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,kBAAkB,EAAE,EACjC,MAAM,EAAE,UAAU,GACjB,IAAI,CAAC;CACT;AAED,wBAAgB,uBAAuB,CAAC,IAAI,GAAE,qBAA0B,GAAG,iBAAiB,CAyE3F"}
+{"version":3,"file":"strategy-lifecycle.d.ts","sourceRoot":"","sources":["../../src/runtime/strategy-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,KAAK,EAAE,gBAAgB,EAAuB,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAO3G;;;kEAGkE;AAClE,UAAU,SAAS;IACjB,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd;2DACuD;IACvD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC,CAIrE,CAAC;AAkIF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EACnD,MAAM,EAAE,MAAM,GACb,gBAAgB,CAGlB;AAED,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,yEAAyE;IACzE,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,2FAA2F;AAC3F,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,UAAU,CAGhD,CAAC;AAEH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AAED,8FAA8F;AAC9F,MAAM,WAAW,SAAS;IACxB,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC;CACvB;AAgBD;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,wBAAwB,CAAC;IACzC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC;CAC/C;AA6ED,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,OAAO,CACL,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,kBAAkB,EAAE,EACjC,MAAM,EAAE,UAAU,GACjB,IAAI,CAAC;IAER;;;;;;;;;;;;;;;;;;OAkBG;IACH,UAAU,CACR,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,kBAAkB,EAC9B,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAE/B;;;;;;;;OAQG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnF;AAED,wBAAgB,uBAAuB,CAAC,IAAI,GAAE,qBAA0B,GAAG,iBAAiB,CAsQ3F"}