/**
 * Phase E1 (olam-dogfood-vision): WorldsSource interface.
 *
 * Single narrow boundary that both LocalWorldsSource (today's
 * dockerode-driven enumeration) and PylonWorldsSource (future cloud
 * worlds) implement. The interface is the entire contract — there is
 * no shared abstract class, no shared base, no shared utility module.
 *
 * Per Phase E plan (S1 contract carried through C-phase): the wire
 * shape IS the abstraction. Sources implementing this interface are
 * free to pick any backend (dockerode, Pylon SDK, mock, sqlite cache
 * — anything) as long as `list()` returns the WorldSummary shape.
 *
 * Deliberately narrow:
 *   - `name` — discriminator for the source. SPA uses this to render
 *     the per-world `source` chip (E5).
 *   - `list()` — read-only enumeration. NO mutations. Mutations stay
 *     on host-cp's existing endpoints (POST /api/worlds delegation,
 *     DELETE via per-world CP, etc.). T5 mitigation: keeping the
 *     surface narrow lets the future Pylon SDK integration extend
 *     `list()`'s implementation without forcing a contract change
 *     across consumers.
 *
 * This is a `.mjs` file (matches host-cp's existing module style).
 * Type information is conveyed via JSDoc; consumers reading via
 * TypeScript get the shape via `// @ts-check` + JSDoc inference.
 *
 * @typedef {object} ServiceInfo
 * @property {string} name
 * @property {number} host_port
 * @property {number} internal_port
 * @property {string} url
 * @property {boolean} live
 *
 * @typedef {object} WorldSummary
 * @property {string} id
 * @property {string | null} name
 * @property {'running' | 'starting' | 'unknown' | 'failed'} status
 * @property {ServiceInfo[]} services
 * @property {'local' | 'pylon-cloud'} source
 *
 * @typedef {object} WorldsSource
 * @property {'local' | 'pylon-cloud'} name
 * @property {() => Promise<WorldSummary[]>} list
 */

// Re-export the source-name discriminator so consumers don't repeat
// the literal string. Both implementations + E4's composition layer
// + E5's SPA badge logic reference this.
export const SOURCE_NAMES = /** @type {const} */ (['local', 'pylon-cloud']);

// `WorldsSource` is a TYPE export — no runtime symbol. Consumers
// import it via JSDoc references:
//   /** @type {import('./worlds-source.mjs').WorldsSource} */
// or in TypeScript:
//   import type { WorldsSource } from './worlds-source.mjs';
//
// Test files exercising the interface treat it as duck-typed: any
// object with the right shape passes structural compatibility.
