@senpi/runtime 3.0.6-dev.skill-manager-v2.20260629194505 → 3.0.9-dev.runtime-phase-2.20260707070820

package/dist/utils/event-catalog.d.ts

@@ -0,0 +1,506 @@
+/**
+ * The closed event catalog for `logger.event`: the pinned `{domain}.{event}` names, each event's
+ * canonical severity, the per-event attribute shapes, and the cross-event join keys shared with the
+ * rest of telemetry.
+ *
+ * This is the contract, not the emit order — the names are stable up front; the call sites that emit
+ * them are wired incrementally. Changing a name or a canonical severity breaks saved queries
+ * downstream, so the set is closed: `EventName` is a literal union over {@link EVENT_NAME}, and only
+ * these names may be passed to `logger.event`.
+ */
+import type { LogLevel } from "./logger.js";
+/**
+ * The pinned event names. `{domain}.{event}`, lowercase snake within a segment. The frozen
+ * self-learning set, so logs share one query vocabulary downstream.
+ */
+export declare const EVENT_NAME: {
+    readonly scannerSummary: "scanner.summary";
+    readonly scannerSpawned: "scanner.spawned";
+    readonly scannerExited: "scanner.exited";
+    readonly scannerRestarted: "scanner.restarted";
+    readonly scannerDegraded: "scanner.degraded";
+    readonly scannerRecovered: "scanner.recovered";
+    readonly scannerSilenceKilled: "scanner.silence_killed";
+    readonly scannerOrphanSwept: "scanner.orphan_swept";
+    readonly scannerLaunchFailed: "scanner.launch_failed";
+    readonly signalAccepted: "signal.accepted";
+    readonly signalRejected: "signal.rejected";
+    readonly signalExpired: "signal.expired";
+    readonly signalSuperseded: "signal.superseded";
+    readonly scaffoldTickError: "scaffold.tick_error";
+    readonly scaffoldTickTimeout: "scaffold.tick_timeout";
+    readonly signalOutcome: "signal.outcome";
+    readonly decisionMade: "decision.made";
+    readonly orderPlaced: "order.placed";
+    readonly orderFilled: "order.filled";
+    readonly orderFailed: "order.failed";
+    readonly positionOpened: "position.opened";
+    readonly positionClosed: "position.closed";
+    readonly positionIncreased: "position.increased";
+    readonly positionDecreased: "position.decreased";
+    readonly positionFlipped: "position.flipped";
+    readonly positionReconciled: "position.reconciled";
+    readonly dslCreated: "dsl.created";
+    readonly dslTierAdvanced: "dsl.tier_advanced";
+    readonly dslPhaseChanged: "dsl.phase_changed";
+    readonly dslSlUpdated: "dsl.sl_updated";
+    readonly dslClosePending: "dsl.close_pending";
+    readonly dslClosed: "dsl.closed";
+    readonly dslDeleted: "dsl.deleted";
+    readonly dslCloseAttempt: "dsl.close_attempt";
+    readonly dslSlSyncFailed: "dsl.sl_sync_failed";
+    readonly dslPriceFetchStale: "dsl.price_fetch_stale";
+    readonly dslHandoffFailed: "dsl.handoff_failed";
+    readonly runtimeCreated: "runtime.created";
+    readonly runtimeDeleted: "runtime.deleted";
+    readonly runtimeStarted: "runtime.started";
+    readonly runtimeStopped: "runtime.stopped";
+    readonly runtimePaused: "runtime.paused";
+    readonly runtimeResumed: "runtime.resumed";
+    readonly runtimeError: "runtime.error";
+    readonly runtimeQueueBackpressure: "runtime.queue_backpressure";
+    readonly runtimeScannersUnwired: "runtime.scanners_unwired";
+    readonly statePersistFailed: "state.persist_failed";
+    readonly mcpCallFailed: "mcp.call_failed";
+    readonly toolCalled: "tool.called";
+};
+/** The closed set of names accepted by `logger.event`. */
+export type EventName = (typeof EVENT_NAME)[keyof typeof EVENT_NAME];
+/** The canonical severity for an event name (the level a healthy emit uses). */
+export declare function canonicalSeverity(name: EventName): LogLevel;
+/** A safe-by-construction scalar attribute value. Flattened and capped, never redacted. */
+export type AttrValue = string | number | boolean;
+/** The keys of `T` whose value type does NOT admit `undefined` — i.e. the required attributes. */
+type RequiredAttrKeys<T> = {
+    [K in keyof T]-?: undefined extends T[K] ? never : K;
+}[keyof T];
+/**
+ * The accepted input shape for {@link eventAttrs}: a required attribute must be present with a defined
+ * value (it may not be passed `undefined`), while an optional attribute may be `value | undefined`
+ * (and is dropped when `undefined`). This is what keeps the `T` cast in `eventAttrs` honest — a
+ * required key can never be runtime-dropped, so the returned bag really is `T`.
+ */
+type EventAttrsInput<T> = {
+    [K in RequiredAttrKeys<T>]: T[K];
+} & {
+    [K in Exclude<keyof T, RequiredAttrKeys<T>>]?: T[K] | undefined;
+};
+/**
+ * Build an event's typed attribute bag, key-checked against the target shape `T` (an
+ * {@link EventAttributes} entry / {@link AttrsFor}). A required attribute must be supplied a defined
+ * value; an optional one may be `value | undefined` and is dropped when `undefined` (`undefined` is
+ * not a valid OTel attribute value). `null`/empty-string are kept as-is — only `undefined` is dropped.
+ * A misnamed key, a missing/`undefined` required key, or a wrong-typed value is a compile error at the
+ * builder, so a site cannot hand `logger.event` an attribute bag that doesn't match its event. Returns
+ * exactly `T`.
+ */
+export declare function eventAttrs<T extends EventAttributes[keyof EventAttributes]>(obj: EventAttrsInput<T>): T;
+/** Group a number with thousands separators for an event narrative body (e.g. 2400 → "2,400"). */
+export declare function fmtThousands(n: number): string;
+/**
+ * Per-event attribute shapes, keyed by event name. Entries are filled as the emissions are wired,
+ * one event at a time; until an event is typed here it falls to the loose default in
+ * {@link AttrsFor}, so not-yet-typed events still compile. Every key is a safe scalar (`senpi.*`
+ * convention, sharing the trace/identity namespace); `id` joins reuse {@link JOIN_ATTR}. Free-text
+ * (LLM reasoning, venue errors) never appears here — it rides the `redact` slot.
+ */
+export interface EventAttributes {
+    "order.placed": OrderEventAttrs;
+    "order.filled": OrderEventAttrs;
+    "order.failed": OrderEventAttrs;
+    "decision.made": DecisionMadeAttrs;
+    "signal.outcome": SignalOutcomeAttrs;
+    "scanner.summary": ScannerSummaryAttrs;
+    "scanner.spawned": ScannerLifecycleAttrs;
+    "scanner.exited": ScannerLifecycleAttrs;
+    "scanner.restarted": ScannerLifecycleAttrs;
+    "scanner.degraded": ScannerLifecycleAttrs;
+    "scanner.recovered": ScannerLifecycleAttrs;
+    "scanner.silence_killed": ScannerLifecycleAttrs;
+    "scanner.orphan_swept": ScannerLifecycleAttrs;
+    "scanner.launch_failed": ScannerLaunchFailedAttrs;
+    "signal.accepted": IntakeDispositionAttrs;
+    "signal.rejected": IntakeDispositionAttrs;
+    "signal.expired": IntakeDispositionAttrs;
+    "signal.superseded": IntakeDispositionAttrs;
+    "scaffold.tick_error": ScaffoldErrorAttrs;
+    "scaffold.tick_timeout": ScaffoldErrorAttrs;
+    "runtime.created": RuntimeCreatedAttrs;
+    "runtime.deleted": RuntimeDeletedAttrs;
+    "runtime.started": RuntimeStartedAttrs;
+    "runtime.stopped": RuntimeStoppedAttrs;
+    "runtime.paused": RuntimePausedAttrs;
+    "runtime.resumed": RuntimeResumedAttrs;
+    "runtime.error": RuntimeErrorAttrs;
+    "runtime.queue_backpressure": RuntimeQueueBackpressureAttrs;
+    "runtime.scanners_unwired": RuntimeScannersUnwiredAttrs;
+    "state.persist_failed": StatePersistFailedAttrs;
+    "position.opened": PositionLifecycleAttrs;
+    "position.closed": PositionLifecycleAttrs;
+    "position.increased": PositionLifecycleAttrs;
+    "position.decreased": PositionLifecycleAttrs;
+    "position.flipped": PositionLifecycleAttrs;
+    "position.reconciled": PositionLifecycleAttrs;
+    "dsl.created": DslTransitionAttrs;
+    "dsl.tier_advanced": DslTransitionAttrs;
+    "dsl.phase_changed": DslTransitionAttrs;
+    "dsl.sl_updated": DslTransitionAttrs;
+    "dsl.close_pending": DslTransitionAttrs;
+    "dsl.closed": DslTransitionAttrs;
+    "dsl.deleted": DslTransitionAttrs;
+    "dsl.sl_sync_failed": DslFailureAttrs;
+    "dsl.price_fetch_stale": DslFailureAttrs;
+    "dsl.handoff_failed": DslFailureAttrs;
+    "mcp.call_failed": McpCallFailedAttrs;
+    "tool.called": ToolCalledAttrs;
+}
+/** Shared shape for the three order events; per-event fields are optional (placed has no fill, etc.). */
+export interface OrderEventAttrs {
+    "senpi.order.id"?: string;
+    "senpi.position.id"?: string;
+    "senpi.asset": string;
+    "senpi.order.direction"?: string;
+    "senpi.order.type"?: string;
+    "senpi.order.size"?: number;
+    "senpi.order.reduce_only"?: boolean;
+    "senpi.order.fill_price"?: number;
+    "senpi.order.fill_size"?: number;
+    "senpi.order.execution_as_maker"?: boolean;
+    /** Granular reason code on a failed order (e.g. `position_open_failed`, `exception`). */
+    "senpi.order.reason"?: string;
+    /** `Error.name` on a failed order; the venue error text rides the `redact` slot. */
+    "senpi.order.error_name"?: string;
+}
+export interface DecisionMadeAttrs {
+    /** How the decision was produced: `llm` | `rule` | `none` | … */
+    "senpi.decision.mode"?: string;
+    "senpi.decision.by_llm": boolean;
+    "senpi.decision.intent": string;
+    "senpi.decision.confidence": number;
+    "senpi.decision.confidence_threshold"?: number;
+    "senpi.decision.model"?: string;
+    "senpi.decision.tokens_used"?: number;
+    "senpi.decision.duration_ms"?: number;
+}
+export interface SignalOutcomeAttrs {
+    "senpi.position.id"?: string;
+    "senpi.order.id"?: string;
+    "senpi.scanner.id"?: string;
+    "senpi.signal.type"?: string;
+    "senpi.signal.asset": string;
+    "senpi.signal.direction"?: string;
+    "senpi.signal.score": number;
+    /** Disposition: `accepted` | `rejected` | `blocked` | `error`. */
+    "senpi.outcome.result": string;
+    /** Granular per-signal reason code (e.g. `submitted`, `no_slots`, `risk_gate_*`). */
+    "senpi.outcome.reason_code"?: string;
+    "senpi.outcome.margin_amount"?: number;
+    /** Which precedence rule sized the margin: `signal_marginPct` | `config_margin_pct` | `margin_per_slot` | `budget_over_slots`. */
+    "senpi.outcome.margin_source"?: string;
+    /** The applied percent (of withdrawable) for the two percent-based sources; absent on the fixed/budget branches. */
+    "senpi.outcome.margin_pct"?: number;
+    "senpi.outcome.leverage"?: number;
+    "senpi.outcome.notional_value"?: number;
+    "senpi.outcome.size"?: number;
+}
+export interface ScannerSummaryAttrs {
+    "senpi.scanner.id": string;
+    "senpi.scanner.scanned_count": number;
+    "senpi.scanner.passed_count": number;
+    "senpi.scanner.dropped_count": number;
+    /**
+     * Per-reason drop counts, keyed `senpi.scanner.dropped.{reason}` (+ a `…dropped.other` overflow
+     * bucket). The reason segment is a producer-controlled string, so these keys are dynamic and
+     * bounded by the caller's cap — typed narrowly as numeric counts under that key prefix.
+     */
+    [dropReason: `senpi.scanner.dropped.${string}`]: number;
+}
+/**
+ * Shared shape for the seven `scanner.*` supervisor-lifecycle events. `senpi.scanner.id`/name and
+ * `senpi.supervisor.id` (the join key to the supervisor's own free-text logs) are always present;
+ * the rest are per-transition (pid/attempt on `spawned`, exit detail on `exited`, backoff on
+ * `restarted`, `rapid_failures` on `degraded`, `silence_ms` on `silence_killed`). `senpi.supervisor.run_id`
+ * is the per-spawn run id — distinct from the per-scan `senpi.run.id`. These fire outside any signal
+ * flow, so the wallet is stamped here explicitly rather than riding the async-context identity bag.
+ */
+export interface ScannerLifecycleAttrs {
+    "senpi.scanner.id": string;
+    "senpi.scanner.name": string;
+    "senpi.supervisor.id": string;
+    /** Strategy wallet; absent when the runtime has no wallet. */
+    "senpi.strategy.address"?: string;
+    "senpi.supervisor.run_id"?: string;
+    "senpi.scanner.pid"?: number;
+    "senpi.scanner.exit_code"?: number;
+    "senpi.scanner.signal"?: string;
+    "senpi.scanner.duration_ms"?: number;
+    "senpi.scanner.backoff_ms"?: number;
+    "senpi.scanner.attempt"?: number;
+    "senpi.scanner.rapid_failures"?: number;
+    "senpi.scanner.silence_ms"?: number;
+}
+/**
+ * A supervised scanner that failed to wire up — initial launch (`launch_phase=wire`, before any
+ * supervisor exists) or the relaunch id re-mint (`launch_phase=remint`, where the supervisor and the
+ * old id are known). Either way the scanner produces no signals. The exception rides the event's
+ * `error` slot; the wallet is stamped explicitly (this fires outside any signal flow).
+ */
+export interface ScannerLaunchFailedAttrs {
+    "senpi.scanner.name": string;
+    /** `wire` (initial launch) | `remint` (relaunch id rotation). */
+    "senpi.scanner.launch_phase": string;
+    "senpi.strategy.address"?: string;
+    /** The old scanner id — present on a `remint` failure. */
+    "senpi.scanner.id"?: string;
+    /** The owning supervisor's id — present on a `remint` failure. */
+    "senpi.supervisor.id"?: string;
+}
+/**
+ * Shared shape for the four signal-intake disposition events — the pre-decision acceptance fact at
+ * the process boundary (distinct from the post-decision `signal.outcome`). `senpi.scanner.id` (the
+ * POSTed id, present even when it resolves to no entry) is always set; name/wallet are absent on an
+ * unknown-scanner reject. The minted `senpi.signal.correlation_id` rides `accepted`; a low-cardinality
+ * `senpi.intake.reason_code` rides a coded request-level reject. These fire at the HTTP boundary,
+ * outside any signal flow, so the wallet is stamped here rather than via async-context identity. The
+ * free-text reject reason rides the event's `redact` slot.
+ */
+export interface IntakeDispositionAttrs {
+    "senpi.scanner.id": string;
+    "senpi.scanner.name"?: string;
+    "senpi.strategy.address"?: string;
+    /** Per-signal asset; absent on a whole-request reject. */
+    "senpi.signal.asset"?: string;
+    /** The minted correlation id — present on `signal.accepted`. */
+    "senpi.signal.correlation_id"?: string;
+    /** Coded request-level reject reason (`unknown_scanner` | `max_items_exceeded`). */
+    "senpi.intake.reason_code"?: string;
+}
+/**
+ * Shared shape for the two scaffold tick-failure events from the `/errors` boundary — a scanner tick
+ * that threw or exceeded its budget (so it produced no signal). `senpi.scaffold.error_type` carries
+ * the scaffold's failure class (a Python exception name, or `state_persist_failed`) on `tick_error`;
+ * it is omitted on `tick_timeout`, where the name says it. The raw message rides `redact`.
+ */
+export interface ScaffoldErrorAttrs {
+    "senpi.scanner.id": string;
+    "senpi.scanner.name"?: string;
+    "senpi.strategy.address"?: string;
+    "senpi.scaffold.error_type"?: string;
+}
+/**
+ * A runtime added to the registry via `senpi.installRuntime`. The registry-level create fact —
+ * distinct from `runtime.started`, which is the process boot transition and also fires on a transient
+ * restart. Fires at the gateway, outside any signal flow, so the wallet and runtime id are stamped
+ * explicitly.
+ */
+export interface RuntimeCreatedAttrs {
+    "senpi.runtime.id": string;
+    "senpi.strategy.address"?: string;
+    "senpi.recipe.name"?: string;
+}
+/**
+ * A runtime removed from the registry via `senpi.deleteRuntime`. The discriminator a transient
+ * `runtime.stopped` can't provide — a delete is permanent, a stop may be a restart. Fires
+ * unconditionally on the delete path (after the registry removal), so a runtime that registered but
+ * never booted — which skips `handle.stop()` and so emits no `runtime.stopped` — is still observable.
+ * `senpi.runtime.had_live_handle` records whether a running handle was stopped as part of the delete.
+ */
+export interface RuntimeDeletedAttrs {
+    "senpi.runtime.id": string;
+    "senpi.strategy.address"?: string;
+    "senpi.runtime.had_live_handle": boolean;
+}
+export interface RuntimeStartedAttrs {
+    /** Strategy wallet. Stamped explicitly: these events fire outside the per-signal identity context, so the async-context fallback resolves no address. */
+    "senpi.strategy.address"?: string;
+    "senpi.recipe.name"?: string;
+    "senpi.recipe.version"?: string;
+    "senpi.config.hash"?: string;
+    "senpi.runtime.version"?: string;
+    "senpi.runtime.scanner_count": number;
+    "senpi.runtime.action_count": number;
+    "senpi.runtime.has_dsl": boolean;
+    "senpi.strategy.slots"?: number;
+    "senpi.strategy.trading_risk"?: string;
+    "senpi.strategy.margin_per_slot"?: number;
+    "senpi.strategy.margin_pct"?: number;
+    "senpi.strategy.default_leverage"?: number;
+}
+/**
+ * A runtime came up with its external supervised-scanner stack unwired — it runs on internal scanners
+ * only, the highest-impact supervised-scanner failure mode. `senpi.scanners.launch_phase` names which
+ * gateway seam failed (`mount` / `launch` at boot, `install_wire` / `install_launch` on a live install);
+ * the boot exception rides the event's `error` slot. Fires outside any signal flow, so the runtime id
+ * and wallet are stamped explicitly.
+ */
+export interface RuntimeScannersUnwiredAttrs {
+    "senpi.runtime.id": string;
+    "senpi.strategy.address"?: string;
+    "senpi.scanners.launch_phase": string;
+}
+export interface RuntimeStoppedAttrs {
+    "senpi.strategy.address"?: string;
+    "senpi.runtime.version"?: string;
+    "senpi.runtime.uptime_ms"?: number;
+}
+export interface RuntimePausedAttrs {
+    "senpi.strategy.address"?: string;
+    "senpi.gate.id"?: string;
+    "senpi.gate.name"?: string;
+}
+export interface RuntimeResumedAttrs {
+    "senpi.strategy.address"?: string;
+    "senpi.gate.id"?: string;
+    "senpi.gate.name"?: string;
+}
+export interface RuntimeErrorAttrs {
+    "senpi.runtime.phase": string;
+    "senpi.scanner.id"?: string;
+}
+/**
+ * The serial signal queue reached its backpressure threshold — the consumer is falling behind inflow.
+ * `senpi.queue.depth` (the depth at the trip) shares the namespace the `signal.process` span stamps;
+ * `senpi.queue.threshold` makes the event self-describing across threshold changes. The wallet is
+ * stamped explicitly — this fires at enqueue, outside the per-signal async-context identity bag.
+ */
+export interface RuntimeQueueBackpressureAttrs {
+    "senpi.queue.depth": number;
+    "senpi.queue.threshold": number;
+    /** The scanner whose enqueue tripped the threshold. */
+    "senpi.scanner.id"?: string;
+    "senpi.strategy.address"?: string;
+}
+/** A `StateManager` write that failed to persist — the state key that was lost. */
+export interface StatePersistFailedAttrs {
+    /** The state key (e.g. `0xWallet/dsl-BTC`) whose write was lost. */
+    "senpi.state.key": string;
+}
+/**
+ * Shared shape for the six `position.*` lifecycle events; `event` discriminates which fields are
+ * populated (entry/size on `opened`, close detail on `closed`, the delta on `increased`/`decreased`,
+ * `new_asset` on `flipped`, `reconciliation_source` on `opened`/`reconciled`). Every value is a safe
+ * scalar — these events carry no free-text, so no `redact` slot. `senpi.asset` is always present.
+ */
+export interface PositionLifecycleAttrs {
+    "senpi.position.id"?: string;
+    "senpi.asset": string;
+    "senpi.dex"?: string;
+    "senpi.position.direction"?: string;
+    "senpi.position.entry_price"?: number;
+    "senpi.position.size"?: number;
+    "senpi.position.leverage"?: number;
+    "senpi.position.margin"?: number;
+    "senpi.position.unrealized_pnl"?: number;
+    "senpi.position.roe"?: number;
+    /** closed */
+    "senpi.position.close_reason"?: string;
+    "senpi.position.closed_price"?: number;
+    "senpi.position.closed_size"?: number;
+    /** increased / decreased */
+    "senpi.position.size_delta"?: number;
+    "senpi.position.previous_size"?: number;
+    /** flipped — `senpi.asset` holds the pre-flip asset, this the post-flip coin */
+    "senpi.position.new_asset"?: string;
+    /** `runtime_opened` | `externally_detected`, on `opened`/`reconciled` only. */
+    "senpi.position.reconciliation_source"?: string;
+}
+/**
+ * Shared shape for the seven wired `dsl.*` transitions; `transition` discriminates which fields are
+ * populated (the exit ladder + entry on `created`, floor/SL on `sl_updated`, phase/tier on
+ * `phase_changed`/`tier_advanced`, the close reason on `closed`, the retry attempt on `close_pending`).
+ * All safe scalars — no `redact`. `dsl.close_attempt` is intentionally absent: it is a per-tick
+ * telemetry unit kept on the 9b trace, not a queryable event-log fact.
+ */
+export interface DslTransitionAttrs {
+    "senpi.position.id"?: string;
+    "senpi.asset": string;
+    "senpi.dex"?: string;
+    "senpi.position.direction"?: string;
+    "senpi.dsl.preset"?: string;
+    "senpi.dsl.phase"?: number;
+    "senpi.dsl.tier_index"?: number;
+    "senpi.dsl.floor_price"?: number;
+    "senpi.dsl.new_floor_price"?: number;
+    "senpi.dsl.new_sl_price"?: number;
+    "senpi.dsl.sl_order_id"?: number;
+    "senpi.dsl.current_roe"?: number;
+    "senpi.dsl.peak_roe"?: number;
+    "senpi.dsl.locked_profit_pct"?: number;
+    "senpi.dsl.close_reason"?: string;
+    "senpi.dsl.attempt"?: number;
+}
+/**
+ * Shared shape for the three `dsl.*` exit-engine failure-state events — degradation the DSL monitor
+ * tracks but that surfaced only as a tick-span error or a `warn` log: an exchange SL push that threw
+ * (`sl_sync_failed`, with its running `sl_sync_failure_count` and the exception on the event's `error`
+ * slot), a position with no price for `fetch_failure_count` consecutive ticks (`price_fetch_stale`),
+ * and a Phase-2 backend handoff that degraded (`handoff_failed`, `handoff_failure` naming the step:
+ * `register` left it stuck pending, `rollback` reverted to local management, `poll` failed to reach
+ * the backend that owns the stop). `senpi.asset` is always present; identity (`senpi.strategy.*`)
+ * rides the per-tick async-context bag, like the sibling `dsl.*` transition events. Opaque free-text
+ * — a declined-registration backend payload — rides the `redact` slot.
+ */
+export interface DslFailureAttrs {
+    "senpi.position.id"?: string;
+    "senpi.asset": string;
+    "senpi.dex"?: string;
+    /** sl_sync_failed: running count of consecutive exchange SL-sync failures. */
+    "senpi.dsl.sl_sync_failure_count"?: number;
+    /** price_fetch_stale: consecutive price-fetch failures at the stale threshold. */
+    "senpi.dsl.fetch_failure_count"?: number;
+    /** handoff_failed: which step degraded — `register` | `rollback` | `poll`. */
+    "senpi.dsl.handoff_failure"?: string;
+    /** handoff_failed: the backend's id for this position, when one was assigned. */
+    "senpi.dsl.backend_position_id"?: string;
+}
+/**
+ * An outbound Senpi MCP `tools/call` that threw — the narrative half of the MCP-failure plane, so an
+ * outage is greppable/alertable without spelunking the HTTP-client spans. Keys mirror the `tools/call`
+ * span (`gen_ai.tool.name` / `error.type` / `rpc.response.status_code` / `server.address`) so the event
+ * joins straight to the span carrying the stack; identity (`senpi.strategy.*`) rides the async-context
+ * bag. The raw error text (where the HTTP status / DNS detail lives) rides the `redact` slot.
+ */
+export interface McpCallFailedAttrs {
+    "gen_ai.tool.name": string;
+    /** Low-cardinality error class (`errorTypeOf`: `Error.name` | the string | `_OTHER`). */
+    "error.type": string;
+    /** JSON-RPC error code when the SDK supplied one; absent on a transport-level failure. */
+    "rpc.response.status_code"?: string;
+    /** The MCP server host — distinguishes a prod vs dev endpoint outage. */
+    "server.address"?: string;
+}
+/**
+ * An abnormal agent tool call — the agent-blind hole, made greppable. Only abnormal outcomes are
+ * evented: `error` (a tool call that threw) and `unknown` (the drift alarm — the model requested a
+ * tool it was never offered; `gen_ai.tool.name` carries the invented name, capped). Successful calls
+ * stay on the span/metric planes — a state-changing one already emits a richer domain event
+ * (`position.opened`, `order.placed`, …), and an abnormal MCP RPC fault is the sibling
+ * `mcp.call_failed` (richer, with the JSON-RPC code). `gen_ai.tool.name` joins to the call's span;
+ * identity rides the async-context bag; the error text rides the `redact` slot. The schema keys stay
+ * origin-uniform for the metric-plane follow-on (which dimensions by `mcp`/`decision` too).
+ */
+export interface ToolCalledAttrs {
+    "gen_ai.tool.name": string;
+    /** Dispatch site: `agent` (gateway tool hook). `mcp` is reserved for the metric plane. */
+    "senpi.tool.origin": string;
+    /** `error` (call threw) | `unknown` (tool requested but never offered). `ok`/`denied` reserved (not evented). */
+    "senpi.tool.outcome": string;
+    /** Low-cardinality error class on an abnormal outcome (`errorTypeOf`). */
+    "error.type"?: string;
+}
+/**
+ * The attribute shape for a given event: its typed entry when one exists, else a loose scalar bag so
+ * not-yet-typed events still compile.
+ */
+export type AttrsFor<N extends EventName> = N extends keyof EventAttributes ? EventAttributes[N] : Record<string, AttrValue>;
+/**
+ * The cross-event join/identity keys — the `senpi.*` attributes that thread an event back to its
+ * position or order. Same namespace + casing the trace/identity stamps use, so events join cleanly to
+ * spans. Per-event keys live in {@link EventAttributes}, not here.
+ */
+export declare const JOIN_ATTR: {
+    readonly positionId: "senpi.position.id";
+    readonly orderId: "senpi.order.id";
+};
+export {};
+//# sourceMappingURL=event-catalog.d.ts.map

package/dist/utils/event-catalog.d.ts.map

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

package/dist/utils/event-catalog.js

@@ -0,0 +1,142 @@
+/**
+ * The closed event catalog for `logger.event`: the pinned `{domain}.{event}` names, each event's
+ * canonical severity, the per-event attribute shapes, and the cross-event join keys shared with the
+ * rest of telemetry.
+ *
+ * This is the contract, not the emit order — the names are stable up front; the call sites that emit
+ * them are wired incrementally. Changing a name or a canonical severity breaks saved queries
+ * downstream, so the set is closed: `EventName` is a literal union over {@link EVENT_NAME}, and only
+ * these names may be passed to `logger.event`.
+ */
+/**
+ * The pinned event names. `{domain}.{event}`, lowercase snake within a segment. The frozen
+ * self-learning set, so logs share one query vocabulary downstream.
+ */
+export const EVENT_NAME = {
+    scannerSummary: "scanner.summary",
+    scannerSpawned: "scanner.spawned",
+    scannerExited: "scanner.exited",
+    scannerRestarted: "scanner.restarted",
+    scannerDegraded: "scanner.degraded",
+    scannerRecovered: "scanner.recovered",
+    scannerSilenceKilled: "scanner.silence_killed",
+    scannerOrphanSwept: "scanner.orphan_swept",
+    scannerLaunchFailed: "scanner.launch_failed",
+    signalAccepted: "signal.accepted",
+    signalRejected: "signal.rejected",
+    signalExpired: "signal.expired",
+    signalSuperseded: "signal.superseded",
+    scaffoldTickError: "scaffold.tick_error",
+    scaffoldTickTimeout: "scaffold.tick_timeout",
+    signalOutcome: "signal.outcome",
+    decisionMade: "decision.made",
+    orderPlaced: "order.placed",
+    orderFilled: "order.filled",
+    orderFailed: "order.failed",
+    positionOpened: "position.opened",
+    positionClosed: "position.closed",
+    positionIncreased: "position.increased",
+    positionDecreased: "position.decreased",
+    positionFlipped: "position.flipped",
+    positionReconciled: "position.reconciled",
+    dslCreated: "dsl.created",
+    dslTierAdvanced: "dsl.tier_advanced",
+    dslPhaseChanged: "dsl.phase_changed",
+    dslSlUpdated: "dsl.sl_updated",
+    dslClosePending: "dsl.close_pending",
+    dslClosed: "dsl.closed",
+    dslDeleted: "dsl.deleted",
+    dslCloseAttempt: "dsl.close_attempt",
+    dslSlSyncFailed: "dsl.sl_sync_failed",
+    dslPriceFetchStale: "dsl.price_fetch_stale",
+    dslHandoffFailed: "dsl.handoff_failed",
+    runtimeCreated: "runtime.created",
+    runtimeDeleted: "runtime.deleted",
+    runtimeStarted: "runtime.started",
+    runtimeStopped: "runtime.stopped",
+    runtimePaused: "runtime.paused",
+    runtimeResumed: "runtime.resumed",
+    runtimeError: "runtime.error",
+    runtimeQueueBackpressure: "runtime.queue_backpressure",
+    runtimeScannersUnwired: "runtime.scanners_unwired",
+    statePersistFailed: "state.persist_failed",
+    mcpCallFailed: "mcp.call_failed",
+    toolCalled: "tool.called",
+};
+/**
+ * Each event's canonical severity — and its FLOOR. Failure-shaped events (`order.failed`,
+ * `runtime.error`) are `error`; `runtime.paused` is `warn`; the rest are `info`. A caller may
+ * ESCALATE a catalogued event above its canonical level (e.g. `signal.outcome` goes `error` on a
+ * failed outcome) but never below it: `logger.event` takes the max of the passed level and this, so a
+ * catalogued event can't be labelled under its canonical severity. Names absent here default to
+ * `info`.
+ */
+const CANONICAL_SEVERITY = {
+    [EVENT_NAME.orderFailed]: "error",
+    [EVENT_NAME.runtimeError]: "error",
+    [EVENT_NAME.runtimePaused]: "warn",
+    // The serial consumer falling behind inflow — signals piling up faster than they process. Handled
+    // (the FIFO still drains), so warn, not error.
+    [EVENT_NAME.runtimeQueueBackpressure]: "warn",
+    // A crash-loop guard trip and a silence-kill are the operator's alert conditions.
+    [EVENT_NAME.scannerDegraded]: "warn",
+    [EVENT_NAME.scannerSilenceKilled]: "warn",
+    // A scanner that never wires up (or fails to re-mint on relaunch) produces no signals.
+    [EVENT_NAME.scannerLaunchFailed]: "warn",
+    // A tick that errors or times out is a scanner producing nothing — an alert condition, like a
+    // crash-loop; the routine intake dispositions (accepted/rejected/expired/superseded) stay info.
+    [EVENT_NAME.scaffoldTickError]: "warn",
+    [EVENT_NAME.scaffoldTickTimeout]: "warn",
+    // Exit management silently degrading is an alert condition — a stop the venue never received, a
+    // position flying blind on price, a backend handoff that never completed. All handled (retried or
+    // recovered) so they are warn, not error.
+    [EVENT_NAME.dslSlSyncFailed]: "warn",
+    [EVENT_NAME.dslPriceFetchStale]: "warn",
+    [EVENT_NAME.dslHandoffFailed]: "warn",
+    // A runtime that came up with its external scanner stack unwired is running blind — a real
+    // degradation an operator must see. The error slot carries the boot exception.
+    [EVENT_NAME.runtimeScannersUnwired]: "error",
+    // A persisted write the runtime lost — risks silent position-state loss, so error (not the handled
+    // warn of the DSL degradations). The error slot carries the exception without fanning the notifier.
+    [EVENT_NAME.statePersistFailed]: "error",
+    // A single MCP RPC fault is usually transient/handled (caller retries or returns null); the outage
+    // is the burst/aggregate. Warn, like the DSL degradations — the stack rides the tools/call span.
+    [EVENT_NAME.mcpCallFailed]: "warn",
+};
+/** The canonical severity for an event name (the level a healthy emit uses). */
+export function canonicalSeverity(name) {
+    return CANONICAL_SEVERITY[name] ?? "info";
+}
+/**
+ * Build an event's typed attribute bag, key-checked against the target shape `T` (an
+ * {@link EventAttributes} entry / {@link AttrsFor}). A required attribute must be supplied a defined
+ * value; an optional one may be `value | undefined` and is dropped when `undefined` (`undefined` is
+ * not a valid OTel attribute value). `null`/empty-string are kept as-is — only `undefined` is dropped.
+ * A misnamed key, a missing/`undefined` required key, or a wrong-typed value is a compile error at the
+ * builder, so a site cannot hand `logger.event` an attribute bag that doesn't match its event. Returns
+ * exactly `T`.
+ */
+export function eventAttrs(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    // Required keys are statically guaranteed defined and present (see EventAttrsInput); dropping the
+    // `undefined`-valued optionals leaves exactly `T`, which the loose `Record` can't prove on its own.
+    return out;
+}
+/** Group a number with thousands separators for an event narrative body (e.g. 2400 → "2,400"). */
+export function fmtThousands(n) {
+    return n.toLocaleString("en-US");
+}
+/**
+ * The cross-event join/identity keys — the `senpi.*` attributes that thread an event back to its
+ * position or order. Same namespace + casing the trace/identity stamps use, so events join cleanly to
+ * spans. Per-event keys live in {@link EventAttributes}, not here.
+ */
+export const JOIN_ATTR = {
+    positionId: "senpi.position.id",
+    orderId: "senpi.order.id",
+};
+//# sourceMappingURL=event-catalog.js.map