/**
 * Phase E3 (olam-dogfood-vision): PylonWorldsSource skeleton.
 *
 * Stub implementation of the WorldsSource contract (E1) for Pylon-
 * managed cloud worlds. Returns `[]` for now — the actual @pleri/pylon
 * SDK integration is intentionally deferred (T5 mitigation: design the
 * contract before the SDK lands so consumers don't churn when it does).
 *
 * The class proves the interface composes: E4 wires this alongside
 * LocalWorldsSource into the GET /api/worlds handler so a Pylon-enabled
 * deployment fans out across both sources, dedupes by id, and returns
 * the union. With this stub returning `[]`, an enabled-but-empty Pylon
 * source is a strict no-op over local-only behavior.
 *
 * Activation: gated by `OLAM_HOST_CP_PYLON_ENABLED=1`. When the env
 * var is unset/0/false, server.mjs (E4) does NOT instantiate this
 * source — the local-only path is preserved verbatim. When enabled,
 * the empty source layers additively on top of local; behavior is
 * still observably identical until the SDK ships.
 *
 * Why a no-op stub instead of waiting for the SDK:
 *   - Consumers (SPA badge logic in E5, regression tests, CLI lookup)
 *     can be wired against the contract without blocking on the SDK.
 *   - Forces E4's composition logic to actually fan out, dedupe, and
 *     merge — exercising the multi-source path in CI before any cloud
 *     traffic touches it.
 *   - Surface-area lock-in: anything missing here surfaces as a
 *     contract gap NOW, not after the SDK is wired.
 *
 * @typedef {import('./worlds-source.mjs').WorldsSource} WorldsSource
 * @typedef {import('./worlds-source.mjs').WorldSummary} WorldSummary
 */

/**
 * @typedef {object} PylonWorldsSourceDeps
 * @property {boolean} enabled
 *   When false, list() short-circuits to `[]` without any Pylon
 *   interaction. Kept on the deps object (rather than read from
 *   process.env at construction time) so tests can flip it without
 *   mutating module-level env state.
 */

/**
 * @param {PylonWorldsSourceDeps} [deps]
 * @returns {WorldsSource}
 */
export function createPylonWorldsSource(deps = { enabled: false }) {
  return {
    name: 'pylon-cloud',
    async list() {
      if (!deps.enabled) return [];
      // TODO(pylon): wire @pleri/pylon SDK. Expected shape:
      //   const client = new PylonClient({ token: scopedToken });
      //   const cloudWorlds = await client.worlds.list();
      //   return cloudWorlds.map((w) => ({
      //     id: w.id,
      //     name: w.displayName ?? null,
      //     status: mapPylonStatus(w.state), // 'running' | 'starting' | ...
      //     services: mapPylonServices(w.services),
      //     source: 'pylon-cloud',
      //   }));
      // Until the SDK lands, the source is intentionally empty —
      // proving the interface composes (E4) without committing the
      // mapping shape prematurely.
      return [];
    },
  };
}
