@groovenet/player 0.1.3 → 0.1.4

package/build/server/http.d.ts

@@ -0,0 +1,5 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import { ServerPlayerManager } from "./manager.js";
+/** The worker API is private to Compose. Public clients go through the app. */
+export declare function playerHttpServer(manager: ServerPlayerManager, key: string): import("node:http").Server<typeof IncomingMessage, typeof ServerResponse>;
+//# sourceMappingURL=http.d.ts.map

package/build/server/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/server/http.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAMpF,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAyBnD,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,mBAAmB,EAAE,GAAG,EAAE,MAAM,6EAwDzE"}

package/build/server/http.js

@@ -0,0 +1,129 @@
+import { createServer } from "node:http";
+import { timingSafeEqual } from "node:crypto";
+import { randomUUID } from "node:crypto";
+import { ZodError } from "zod";
+import { createServerPlayerSchema, playerIdSchema, serverPlayerCommandSchema } from "@groovenet/contracts";
+import { PlayerError } from "../types.js";
+import { ServerPlayerError } from "./store.js";
+function authorized(header, key) {
+    const actual = Buffer.from(header ?? "");
+    const expected = Buffer.from(`Bearer ${key}`);
+    return actual.length === expected.length && timingSafeEqual(actual, expected);
+}
+async function body(request) {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of request.iterator({ destroyOnReturn: false })) {
+        const buffer = Buffer.from(chunk);
+        bytes += buffer.length;
+        if (bytes > 2 * 1024 * 1024) {
+            request.resume();
+            throw new ServerPlayerError("BODY_TOO_LARGE", "Player command exceeds 2 MB", 413);
+        }
+        chunks.push(buffer);
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString());
+    }
+    catch {
+        throw new ServerPlayerError("INVALID_JSON", "Invalid JSON request", 400);
+    }
+}
+function json(response, status, value) {
+    response.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+    response.end(JSON.stringify(value));
+}
+/** The worker API is private to Compose. Public clients go through the app. */
+export function playerHttpServer(manager, key) {
+    if (key.length < 32)
+        throw new Error("PLAYER_API_KEY must contain at least 32 characters");
+    const instance = randomUUID();
+    let sequence = 0;
+    const server = createServer((request, response) => {
+        void (async () => {
+            if (!authorized(request.headers.authorization, key)) {
+                json(response, 401, { error: "Unauthorized", code: "UNAUTHORIZED" });
+                return;
+            }
+            const path = new URL(request.url ?? "/", "http://worker").pathname;
+            if (request.method === "GET" && path === "/health") {
+                json(response, 200, { status: "ok", instance });
+                return;
+            }
+            if (request.method === "GET" && path === "/engines") {
+                json(response, 200, { engines: manager.engineIds() });
+                return;
+            }
+            if (path === "/players") {
+                if (request.method === "GET") {
+                    json(response, 200, { players: manager.list() });
+                    return;
+                }
+                if (request.method === "POST") {
+                    json(response, 201, await manager.create(createServerPlayerSchema.parse(await body(request))));
+                    return;
+                }
+            }
+            const match = /^\/players\/([^/]+)(?:\/(commands|devices|events))?$/.exec(path);
+            if (!match) {
+                json(response, 404, { error: "Not found" });
+                return;
+            }
+            const id = playerIdSchema.parse(match[1]);
+            const player = manager.get(id);
+            if (!match[2] && request.method === "GET") {
+                json(response, 200, player);
+                return;
+            }
+            if (match[2] === "devices" && request.method === "GET") {
+                json(response, 200, { devices: await manager.devices(id) });
+                return;
+            }
+            if (match[2] === "commands" && request.method === "POST") {
+                json(response, 200, await manager.command(id, serverPlayerCommandSchema.parse(await body(request))));
+                return;
+            }
+            if (match[2] === "events" && request.method === "GET") {
+                response.writeHead(200, { "Content-Type": "text/event-stream", "Cache-Control": "no-cache, no-transform", "Connection": "keep-alive", "X-Accel-Buffering": "no" });
+                const send = (value) => {
+                    if (value.id !== id || response.destroyed)
+                        return;
+                    const event = JSON.stringify({ type: "snapshot", player: value, worker_instance: instance, sequence: ++sequence });
+                    // A slow/disconnected client is dropped; it never blocks the player.
+                    response.write(`event: snapshot\ndata: ${event}\n\n`);
+                    if (response.writableLength > 64 * 1024 * 1024)
+                        response.destroy();
+                };
+                const position = (value) => {
+                    if (value.player_id === id && !response.destroyed) {
+                        response.write(`event: position\ndata: ${JSON.stringify({ ...value, type: "position", worker_instance: instance, sequence: ++sequence })}\n\n`);
+                        if (response.writableLength > 64 * 1024 * 1024)
+                            response.destroy();
+                    }
+                };
+                const heartbeat = setInterval(() => { if (!response.destroyed && !response.write(": heartbeat\n\n"))
+                    response.destroy(); }, 15000);
+                heartbeat.unref();
+                const cleanup = () => { clearInterval(heartbeat); manager.off("snapshot", send); manager.off("position", position); };
+                response.once("close", cleanup);
+                manager.on("snapshot", send);
+                manager.on("position", position);
+                send(player);
+                return;
+            }
+            json(response, 405, { error: "Method not allowed" });
+        })().catch((error) => {
+            if (response.headersSent) {
+                response.destroy();
+                return;
+            }
+            const status = error instanceof ServerPlayerError ? error.status : error instanceof ZodError ? 400 : error instanceof PlayerError ? 422 : 502;
+            const code = error instanceof ServerPlayerError ? error.code : error instanceof ZodError ? "INVALID_ARGUMENT" : error instanceof PlayerError ? error.code : "PLAYER_OPERATION_FAILED";
+            json(response, status, { error: error instanceof ServerPlayerError ? error.message : "Player operation failed", code });
+        });
+    });
+    server.requestTimeout = 15000;
+    server.headersTimeout = 10000;
+    return server;
+}
+//# sourceMappingURL=http.js.map

package/build/server/http.js.map

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

package/build/server/manager.d.ts

@@ -0,0 +1,45 @@
+import { EventEmitter } from "node:events";
+import { type CreateServerPlayer, type ServerPlayer, type ServerPlayerCommand, type ServerPlayerCommandResult, type ServerPlayerDevice, type SpeakerObservation } from "@groovenet/contracts";
+import { type PlaybackBackend } from "../types.js";
+import { type PlayerStore } from "./store.js";
+export interface PlayerEngine {
+    libraryRoot: string;
+    create(outputId?: string): PlaybackBackend;
+}
+export type SpeakerObserver = (outputId: string) => Promise<SpeakerObservation>;
+export declare const unknownSpeaker: () => SpeakerObservation;
+/** Owns all player lifecycles; no HTTP connection owns a backend. */
+export declare class ServerPlayerManager extends EventEmitter {
+    private readonly store;
+    private readonly engines;
+    private readonly observe;
+    private players;
+    private runtimes;
+    private generation;
+    private tail;
+    private stopping;
+    private checkpointAt;
+    constructor(store: PlayerStore, engines: Record<string, PlayerEngine>, observe?: SpeakerObserver);
+    private serial;
+    initialize(): Promise<void>;
+    engineIds(): string[];
+    list(): ServerPlayer[];
+    get(id: string): ServerPlayer;
+    create(input: CreateServerPlayer): Promise<ServerPlayer>;
+    devices(id: string): Promise<ServerPlayerDevice[]>;
+    command(id: string, input: ServerPlayerCommand): Promise<ServerPlayerCommandResult>;
+    private play;
+    private enqueueEvent;
+    private detach;
+    private stop;
+    private transfer;
+    shutdown(): Promise<void>;
+    private requireAvailable;
+    private engine;
+    private active;
+    private revision;
+    private available;
+    private save;
+    private publish;
+}
+//# sourceMappingURL=manager.d.ts.map

package/build/server/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/server/manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAuD,KAAK,kBAAkB,EAAE,KAAK,YAAY,EAAE,KAAK,mBAAmB,EAAE,KAAK,yBAAyB,EAAE,KAAK,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAEnP,OAAO,EAAe,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAEjE,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC;CAC5C;AACD,MAAM,MAAM,eAAe,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAChF,eAAO,MAAM,cAAc,QAAO,kBAA0H,CAAC;AAK7J,qEAAqE;AACrE,qBAAa,mBAAoB,SAAQ,YAAY;IAQvC,OAAO,CAAC,QAAQ,CAAC,KAAK;IAAe,OAAO,CAAC,QAAQ,CAAC,OAAO;IAAgC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAPjI,OAAO,CAAC,OAAO,CAAmC;IAClD,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,IAAI,CAAuC;IACnD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,YAAY,CAA6B;IAEjD,YAA6B,KAAK,EAAE,WAAW,EAAmB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EAAmB,OAAO,GAAE,eAA8C,EAAc;IAE/L,OAAO,CAAC,MAAM;IAMR,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAShC;IAED,SAAS,IAAI,MAAM,EAAE,CAA6C;IAClE,IAAI,IAAI,YAAY,EAAE,CAAkD;IACxE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,CAI5B;IAED,MAAM,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAUvD;IAEK,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAYvD;IAED,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAwFlF;YAEa,IAAI;IA2ElB,OAAO,CAAC,YAAY;YAcN,MAAM;YAYN,IAAI;YAOJ,QAAQ;IA2BhB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAQ9B;YAEa,gBAAgB;IAM9B,OAAO,CAAC,MAAM;IAKd,OAAO,CAAC,MAAM;IAKd,OAAO,CAAC,QAAQ;IAGhB,OAAO,CAAC,SAAS;YACH,IAAI;IAMlB,OAAO,CAAC,OAAO;CAChB"}

package/build/server/manager.js

@@ -0,0 +1,423 @@
+import { EventEmitter } from "node:events";
+import { randomUUID } from "node:crypto";
+import { createServerPlayerSchema, serverPlayerCommandSchema } from "@groovenet/contracts";
+import { audioSource } from "../resolver.js";
+import { PlayerError } from "../types.js";
+import { ServerPlayerError } from "./store.js";
+export const unknownSpeaker = () => ({ availability: "unknown", observed_at: null, source: "unconfigured", sender_identity: "unknown" });
+const errorValue = (error) => error instanceof PlayerError || error instanceof ServerPlayerError ? { code: error.code, message: error.message } : { code: "PLAYER_OPERATION_FAILED", message: "Player operation failed" };
+const clone = (value) => structuredClone(value);
+/** Owns all player lifecycles; no HTTP connection owns a backend. */
+export class ServerPlayerManager extends EventEmitter {
+    store;
+    engines;
+    observe;
+    players = new Map();
+    runtimes = new Map();
+    generation = 0;
+    tail = Promise.resolve();
+    stopping = false;
+    checkpointAt = new Map();
+    constructor(store, engines, observe = async () => unknownSpeaker()) {
+        super();
+        this.store = store;
+        this.engines = engines;
+        this.observe = observe;
+    }
+    serial(action) {
+        const result = this.tail.then(action);
+        this.tail = result.catch(() => { });
+        return result;
+    }
+    async initialize() {
+        // No engine object or network connection is created during restoration.
+        for (const saved of await this.store.list()) {
+            const player = clone(saved);
+            player.assigned_output = null;
+            player.state.status = "stopped";
+            player.state.checkpoint = true;
+            this.players.set(player.id, await this.store.save(player, saved.revision));
+        }
+    }
+    engineIds() { return Object.keys(this.engines).sort(); }
+    list() { return [...this.players.values()].map(clone); }
+    get(id) {
+        const player = this.players.get(id);
+        if (!player)
+            throw new ServerPlayerError("PLAYER_NOT_FOUND", "Player does not exist", 404);
+        return clone(player);
+    }
+    create(input) {
+        return this.serial(async () => {
+            this.available();
+            const parsed = createServerPlayerSchema.parse(input);
+            if (!this.engines[parsed.engine_id])
+                throw new ServerPlayerError("ENGINE_NOT_CONFIGURED", "Engine is not configured on this server", 400);
+            const player = await this.store.create(parsed, { queue: [], current_entry_id: null, status: "stopped", position: 0, duration: null, volume: 50, desired_output: null, checkpoint: false, error: null });
+            this.players.set(player.id, player);
+            this.publish(player);
+            return clone(player);
+        });
+    }
+    async devices(id) {
+        const player = this.get(id);
+        const runtime = this.runtimes.get(id);
+        const backend = runtime?.backend ?? this.engine(player).create();
+        try {
+            const outputs = await backend.listDevices();
+            return await Promise.all(outputs.map(async (output) => ({ ...output,
+                assigned_player_id: this.list().find((p) => p.assigned_output === output.id)?.id ?? null,
+                desired_by: this.list().filter((p) => p.state.desired_output === output.id).map((p) => p.id),
+                observed: await this.observe(output.id),
+            })));
+        }
+        finally {
+            if (!runtime)
+                await backend.close();
+        }
+    }
+    command(id, input) {
+        return this.serial(async () => {
+            this.available();
+            const command = serverPlayerCommandSchema.parse(input);
+            let player = this.get(id);
+            this.revision(player, command.expected_revision);
+            if (command.type === "output.transfer")
+                return this.transfer(player, command);
+            try {
+                switch (command.type) {
+                    case "rename":
+                        player.name = command.name;
+                        break;
+                    case "queue.add": {
+                        const at = command.at ?? player.state.queue.length;
+                        if (at > player.state.queue.length || player.state.queue.length + command.tracks.length > 10000)
+                            throw new ServerPlayerError("INVALID_QUEUE", "Queue insertion is out of range", 400);
+                        const added = [];
+                        for (const ref of command.tracks) {
+                            const track = await this.store.resolve(ref);
+                            if (!track)
+                                throw new ServerPlayerError("TRACK_NOT_FOUND", "Queued track does not exist or is ambiguous", 404);
+                            added.push({ ...ref, id: randomUUID(), title: track.title, artist: track.artist });
+                        }
+                        player.state.queue.splice(at, 0, ...added);
+                        break;
+                    }
+                    case "queue.remove": {
+                        const index = player.state.queue.findIndex((entry) => entry.id === command.entry_id);
+                        if (index < 0)
+                            throw new ServerPlayerError("ENTRY_NOT_FOUND", "Queue entry does not exist", 404);
+                        if (command.entry_id === player.state.current_entry_id)
+                            await this.stop(player);
+                        player.state.queue.splice(index, 1);
+                        break;
+                    }
+                    case "queue.move": {
+                        const index = player.state.queue.findIndex((entry) => entry.id === command.entry_id);
+                        if (index < 0 || command.to >= player.state.queue.length)
+                            throw new ServerPlayerError("INVALID_QUEUE", "Queue move is out of range", 400);
+                        player.state.queue.splice(command.to, 0, player.state.queue.splice(index, 1)[0]);
+                        break;
+                    }
+                    case "queue.clear":
+                        await this.stop(player);
+                        player.state.queue = [];
+                        break;
+                    case "output.select":
+                        if (this.runtimes.has(id))
+                            await this.stop(player, true);
+                        player.state.desired_output = command.output_id;
+                        // Remembering a desired output does not reserve or connect it.
+                        break;
+                    case "play": {
+                        const entryId = command.entry_id ?? player.state.current_entry_id ?? player.state.queue[0]?.id;
+                        await this.play(player, entryId, command);
+                        return { player: this.get(id) };
+                    }
+                    case "resume":
+                        if (this.runtimes.has(id)) {
+                            const backend = this.runtimes.get(id).backend;
+                            if (await backend.outputConnection?.() !== "connected")
+                                await this.requireAvailable(player.state.desired_output, command);
+                            await backend.pause(false);
+                            player.state.status = "playing";
+                            player.state.checkpoint = false;
+                        }
+                        else {
+                            await this.play(player, player.state.current_entry_id ?? undefined, command);
+                            return { player: this.get(id) };
+                        }
+                        break;
+                    case "pause":
+                        await this.active(id).backend.pause(true);
+                        player.state.status = "paused";
+                        break;
+                    case "stop":
+                        await this.stop(player);
+                        break;
+                    case "next":
+                    case "previous": {
+                        const index = player.state.queue.findIndex((entry) => entry.id === player.state.current_entry_id);
+                        const next = command.type === "next" ? index + 1 : Math.max(0, index - 1);
+                        if (next >= player.state.queue.length) {
+                            await this.stop(player);
+                            player.state.status = "ended";
+                        }
+                        else {
+                            await this.play(player, player.state.queue[next]?.id, command, false);
+                            return { player: this.get(id) };
+                        }
+                        break;
+                    }
+                    case "seek":
+                        if (!player.state.current_entry_id)
+                            throw new ServerPlayerError("NO_CURRENT_TRACK", "No current track", 400);
+                        if (this.runtimes.has(id))
+                            await this.active(id).backend.seek(command.seconds);
+                        player.state.position = command.seconds;
+                        player.state.checkpoint = !this.runtimes.has(id);
+                        break;
+                    case "volume":
+                        if (this.runtimes.has(id))
+                            await this.active(id).backend.setVolume(command.volume);
+                        player.state.volume = command.volume;
+                        break;
+                }
+                // Queue/settings edits do not recover failed playback. Keep its cause
+                // visible until a transport command successfully leaves the error state.
+                if (player.state.status !== "error")
+                    player.state.error = null;
+                player = await this.save(player);
+                return { player: clone(player) };
+            }
+            catch (error) {
+                // Validation failures do not mutate authoritative state. Engine operations
+                // persist an actionable error; they never advance or silently retry.
+                if (!(error instanceof ServerPlayerError)) {
+                    player = this.get(id);
+                    player.state.status = "error";
+                    player.state.error = errorValue(error);
+                    await this.save(player);
+                }
+                throw error;
+            }
+        });
+    }
+    async play(player, entryId, policy, resumeCheckpoint = true) {
+        const entry = player.state.queue.find((entry) => entry.id === entryId);
+        if (!entry)
+            throw new ServerPlayerError("ENTRY_NOT_FOUND", "Queue is empty or the entry does not exist", 400);
+        const output = player.state.desired_output;
+        if (!output)
+            throw new ServerPlayerError("OUTPUT_REQUIRED", "Select a desired output before playing", 400);
+        const owner = this.list().find((p) => p.assigned_output === output && p.id !== player.id);
+        if (owner)
+            throw new ServerPlayerError("OUTPUT_ASSIGNED", "Speaker belongs to another player; use explicit transfer");
+        const needsReconnect = (player.state.status === "paused" || player.state.status === "error") && await this.runtimes.get(player.id)?.backend.outputConnection?.() !== "connected";
+        if (player.assigned_output !== output || needsReconnect)
+            await this.requireAvailable(output, policy);
+        const track = await this.store.resolve(entry);
+        const engine = this.engine(player);
+        const source = track ? audioSource(track, { apiBase: "http://unused/api", audioLibraryRoot: engine.libraryRoot }) : null;
+        if (!source)
+            throw new ServerPlayerError("NO_AUDIO", "Current track has no indexed audio source", 422);
+        const position = resumeCheckpoint && player.state.current_entry_id === entry.id ? player.state.position : 0;
+        await this.detach(player);
+        player.assigned_output = output;
+        player.state.current_entry_id = entry.id;
+        player.state.position = position;
+        player.state.duration = null;
+        player.state.status = "loading";
+        player.state.checkpoint = false;
+        player.state.error = null;
+        // Persist the selected entry before engine effects. A crash never replays a
+        // completed entry or automatically starts this pending load on restoration.
+        player = await this.save(player);
+        this.available();
+        const backend = engine.create(output);
+        const runtime = { backend, generation: ++this.generation };
+        this.runtimes.set(player.id, runtime);
+        backend.on("position", (position, duration) => this.enqueueEvent(player.id, runtime, async (current) => {
+            if (!Number.isFinite(position) || position < 0)
+                return;
+            current.state.position = position;
+            current.state.duration = duration !== null && Number.isFinite(duration) && duration >= 0 ? duration : null;
+            current.state.checkpoint = false;
+            this.players.set(current.id, current);
+            this.emit("position", { player_id: current.id, revision: current.revision, current_entry_id: current.state.current_entry_id, position: current.state.position, duration: current.state.duration, observed_at: new Date().toISOString() });
+            if (Date.now() - (this.checkpointAt.get(current.id) ?? 0) >= 5000) {
+                await this.store.checkpoint(current);
+                this.checkpointAt.set(current.id, Date.now());
+            }
+        }));
+        backend.on("ended", () => this.enqueueEvent(player.id, runtime, async (current) => {
+            const index = current.state.queue.findIndex((entry) => entry.id === current.state.current_entry_id);
+            const next = current.state.queue[index + 1];
+            if (next) {
+                current.state.current_entry_id = next.id;
+                current.state.position = 0;
+                current.state.duration = null;
+                current.state.status = "loading";
+                const advanced = await this.save(current);
+                await this.play(advanced, next.id, { allow_unknown: true, takeover: false }, false);
+            }
+            else {
+                await this.stop(current);
+                current.state.status = "ended";
+                await this.save(current);
+            }
+        }));
+        backend.on("error", (error) => this.enqueueEvent(player.id, runtime, async (current) => {
+            current.state.status = "error";
+            current.state.error = errorValue(error);
+            try {
+                await this.detach(current);
+            }
+            catch { /* retain the uncertain claim */ }
+            await this.save(current);
+        }));
+        try {
+            await backend.load(source);
+            if (position > 0)
+                await backend.seek(position);
+            await backend.setVolume(player.state.volume);
+            player.state.status = "playing";
+            await this.save(player);
+        }
+        catch (error) {
+            player = this.get(player.id);
+            player.state.status = "error";
+            player.state.error = errorValue(error);
+            try {
+                await this.detach(player);
+            }
+            catch { /* don't transfer an uncertain claim */ }
+            await this.save(player);
+            throw error;
+        }
+    }
+    enqueueEvent(id, runtime, action) {
+        void this.serial(async () => {
+            if (this.stopping || this.runtimes.get(id)?.generation !== runtime.generation)
+                return;
+            try {
+                await action(this.get(id));
+            }
+            catch (error) {
+                const current = this.get(id);
+                current.state.status = "error";
+                current.state.error = errorValue(error);
+                try {
+                    await this.detach(current);
+                }
+                catch { /* preserve uncertain claim */ }
+                await this.save(current);
+            }
+        }).catch((error) => { this.emit("fault", error); });
+    }
+    async detach(player) {
+        const runtime = this.runtimes.get(player.id);
+        if (runtime) {
+            // Invalidate callbacks before awaiting close, including duplicate EOFs.
+            this.runtimes.delete(player.id);
+            await runtime.backend.close();
+        }
+        else if (player.assigned_output !== null) {
+            throw new ServerPlayerError("RELEASE_UNCERTAIN", "Previous engine release is uncertain; stop that engine and restart the worker before reassigning", 503);
+        }
+        player.assigned_output = null;
+    }
+    async stop(player, preserveCurrent = false) {
+        await this.detach(player);
+        player.state.status = preserveCurrent && player.state.current_entry_id ? "paused" : "stopped";
+        player.state.checkpoint = preserveCurrent && player.state.current_entry_id !== null;
+        if (!preserveCurrent) {
+            player.state.current_entry_id = null;
+            player.state.position = 0;
+            player.state.duration = null;
+        }
+    }
+    async transfer(target, command) {
+        if (target.id === command.from_player_id)
+            throw new ServerPlayerError("INVALID_TRANSFER", "Transfer requires two different players", 400);
+        let source = this.get(command.from_player_id);
+        this.revision(source, command.from_revision);
+        if (source.assigned_output !== command.output_id)
+            throw new ServerPlayerError("OUTPUT_NOT_ASSIGNED", "Source player does not own this speaker");
+        let detached = false;
+        try {
+            await this.stop(source, true);
+            source = await this.save(source);
+            detached = true;
+            if (this.runtimes.has(target.id)) {
+                await this.stop(target, true);
+                target = await this.save(target);
+            }
+            target.state.desired_output = command.output_id;
+            target = await this.save(target);
+            if (command.play)
+                await this.play(target, target.state.current_entry_id ?? target.state.queue[0]?.id, command);
+            return { player: this.get(target.id), transfer: { from_player: this.get(source.id), detached, attached: command.play, error: null } };
+        }
+        catch (error) {
+            if (!detached) {
+                source.state.status = "error";
+                source.state.error = errorValue(error);
+                try {
+                    await this.save(source);
+                }
+                catch { /* keep the transfer result truthful */ }
+            }
+            // The source may already be detached. Report each phase; do not reconnect
+            // it to pretend the operation was atomic or compete with an external app.
+            return { player: this.get(target.id), transfer: { from_player: this.get(source.id), detached, attached: false, error: errorValue(error) } };
+        }
+    }
+    async shutdown() {
+        this.stopping = true;
+        await this.serial(async () => {
+            for (const player of this.list()) {
+                try {
+                    await this.stop(player, true);
+                    await this.save(player);
+                }
+                catch (error) {
+                    this.emit("fault", error);
+                }
+            }
+        });
+    }
+    async requireAvailable(output, policy) {
+        const observed = await this.observe(output);
+        if (observed.availability === "occupied" && !policy.takeover)
+            throw new ServerPlayerError("SPEAKER_OCCUPIED", "Observed speaker activity requires explicit takeover");
+        if (observed.availability === "unknown" && !policy.allow_unknown)
+            throw new ServerPlayerError("AVAILABILITY_UNKNOWN", "Speaker availability is unknown; explicitly acknowledge it before connecting");
+    }
+    engine(player) {
+        const engine = this.engines[player.engine_id];
+        if (!engine)
+            throw new ServerPlayerError("ENGINE_NOT_CONFIGURED", "Player engine is not configured", 503);
+        return engine;
+    }
+    active(id) {
+        const runtime = this.runtimes.get(id);
+        if (!runtime)
+            throw new ServerPlayerError("PLAYER_INACTIVE", "Player has no active engine session; explicitly play to start one");
+        return runtime;
+    }
+    revision(player, expected) {
+        if (player.revision !== expected)
+            throw new ServerPlayerError("REVISION_CONFLICT", "Player changed; refresh its state before retrying");
+    }
+    available() { if (this.stopping)
+        throw new ServerPlayerError("WORKER_STOPPING", "Player worker is stopping", 503); }
+    async save(player) {
+        const saved = await this.store.save(player, player.revision);
+        this.players.set(player.id, saved);
+        this.publish(saved);
+        return clone(saved);
+    }
+    publish(player) { this.emit("snapshot", clone(player)); }
+}
+//# sourceMappingURL=manager.js.map