// World startup failure buckets — the six canonical classes the
// classifier maps every observed Failed transition into.
//
// Order is load-bearing: the classifier walks these in declaration
// order on ambiguous evidence, so higher-confidence buckets
// (PromptMisdelivery, TransportDead) come before time-bounded
// inferences (TrustGateUnanswered, McpHandshakeStall). Adding a 7th
// bucket requires updating the classifier precedence and the
// `world.lifecycle.Failed` consumers in the SPA + NDJSON trace.

/**
 * @typedef {| 'PromptMisdelivery'
 *           | 'TransportDead'
 *           | 'TrustGateUnanswered'
 *           | 'McpHandshakeStall'
 *           | 'PluginStartupFailed'
 *           | 'ProviderProcessGone'} WorldStartupFailureKind
 */

/**
 * @type {Readonly<Record<WorldStartupFailureKind, WorldStartupFailureKind>>}
 */
export const WorldStartupFailureKind = Object.freeze({
  /** Dispatch sent but agent never received it (transport mismatch). */
  PromptMisdelivery: 'PromptMisdelivery',
  /** stdin/stdout/IPC channel never opened. */
  TransportDead: 'TransportDead',
  /** Agent reached TrustRequired, no approval ever arrived. */
  TrustGateUnanswered: 'TrustGateUnanswered',
  /** MCP server connection initialized but never completed handshake. */
  McpHandshakeStall: 'McpHandshakeStall',
  /** Plugin or skill source failed to load on boot. */
  PluginStartupFailed: 'PluginStartupFailed',
  /** Agent (Claude Code) process exited before responding. */
  ProviderProcessGone: 'ProviderProcessGone',
});

export const WORLD_STARTUP_FAILURE_KIND_ORDER = Object.freeze([
  WorldStartupFailureKind.PromptMisdelivery,
  WorldStartupFailureKind.TransportDead,
  WorldStartupFailureKind.TrustGateUnanswered,
  WorldStartupFailureKind.McpHandshakeStall,
  WorldStartupFailureKind.PluginStartupFailed,
  WorldStartupFailureKind.ProviderProcessGone,
]);

/**
 * @param {unknown} value
 * @returns {value is WorldStartupFailureKind}
 */
export function isWorldStartupFailureKind(value) {
  return (
    typeof value === 'string' &&
    WORLD_STARTUP_FAILURE_KIND_ORDER.includes(/** @type {any} */ (value))
  );
}
