@ajclarkson/homerun 0.0.1-edge.0131fc6

package/dist/src/framework/action-runtime.js

@@ -0,0 +1,193 @@
+function safeStringify(err) {
+    try {
+        return JSON.stringify(err);
+    }
+    catch {
+        return String(err);
+    }
+}
+// HA `data` keys are conventionally the same name as the attribute they end up setting
+// (temperature, brightness, position, ...) — true across core and third-party integrations
+// as a platform-wide naming convention, not something homerun needs to hand-map per service.
+// These are the known exceptions: call parameters that don't name a resulting attribute.
+const NON_ATTRIBUTE_DATA_KEYS = new Set(['transition', 'entity_id']);
+// `set_value` on these domains sets the entity's top-level `state` directly — unlike most
+// services, where a `data` key names the attribute it ends up on, these have no attribute
+// called `value` at all. Found the hard way (#153): computeExpectedAck's generic convention
+// falsely flagged every number/input_text room-sensor feed call as an ack timeout, since
+// `attributes.value` never existed to satisfy.
+const SET_VALUE_TO_STATE_DOMAINS = new Set(['number', 'input_number', 'input_text', 'input_select', 'text']);
+// Domains/services excluded from tracking entirely rather than guessing at a convention that
+// doesn't hold cleanly — group membership attributes don't reliably come back as an exact
+// match of what was passed (ordering, or reflecting the whole group rather than the delta).
+// scene.turn_on is here for a different reason (#156): a scene entity's `state` is a
+// last-activated timestamp, not 'on'/'off', so the generic turn_on special-case never
+// matches — and even a timestamp-based check would only confirm HA accepted the call, not
+// that the scene's member entities (the things that actually matter) responded. Real
+// coverage would mean tracking each member entity individually — see #155.
+const UNTRACKED_SERVICES = new Set(['media_player.join', 'media_player.unjoin', 'scene.turn_on']);
+// Computes the field/attribute -> value map a dispatched call is expected to produce, or
+// undefined if there's nothing to track (no inferable fields, an excluded service, or the
+// entity already matches every expected field — an idempotent call that legitimately produces
+// no state_changed at all). See #55's design discussion for why this is convention-based
+// rather than a per-service table.
+function computeExpectedAck(action, current) {
+    if (UNTRACKED_SERVICES.has(`${action.domain}.${action.service}`))
+        return undefined;
+    const expected = {};
+    if (action.service === 'turn_on') {
+        expected.state = 'on';
+    }
+    else if (action.service === 'turn_off') {
+        expected.state = 'off';
+    }
+    else if (action.service === 'set_value' && SET_VALUE_TO_STATE_DOMAINS.has(action.domain) && action.data?.value !== undefined) {
+        expected.state = action.data.value;
+    }
+    for (const [key, value] of Object.entries(action.data ?? {})) {
+        if (NON_ATTRIBUTE_DATA_KEYS.has(key))
+            continue;
+        if ('state' in expected && key === 'value' && SET_VALUE_TO_STATE_DOMAINS.has(action.domain))
+            continue;
+        expected[key] = value;
+    }
+    if (Object.keys(expected).length === 0)
+        return undefined;
+    // See ha-client.ts's ackSatisfied for why `state` needs string coercion (#158) — the same
+    // number-vs-string gap applies here to the idempotency pre-check.
+    const alreadySatisfied = Object.entries(expected).every(([key, value]) => key === 'state' ? current !== undefined && String(current.state) === String(value) : current?.attributes[key] === value);
+    if (alreadySatisfied)
+        return undefined;
+    return expected;
+}
+export class ActionRuntime {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+        this.deps.haClient.on('action_ack_timeout', (e) => this.handleAckTimeout(e));
+    }
+    handleAckTimeout(e) {
+        this.deps.metrics?.incrementCounter('homerun_action_ack_timeout_total', {
+            location: e.location,
+            action_type: e.action.type,
+        });
+        this.deps.eventPublisher.publishActionEvent({
+            schema: 'home.events.v2',
+            correlation_id: e.correlationId,
+            root_correlation_id: e.rootCorrelationId ?? e.correlationId,
+            automation_id: e.automationId,
+            location: e.location,
+            subsystem: e.subsystem,
+            timestamp: new Date().toISOString(),
+            ...(this.deps.dryRun ? { dry_run: true } : {}),
+            event_type: 'action_ack_timeout',
+            action: e.action,
+            entity: e.entity_id,
+            expected: e.expected,
+        });
+    }
+    async execute(actions, ctx) {
+        for (const action of actions) {
+            await this.runAction(action, ctx);
+        }
+    }
+    async runAction(action, ctx) {
+        const labels = { location: ctx.location, action_type: action.type };
+        this.deps.eventPublisher.publishActionEvent(this.makeStartedEvent(ctx, action));
+        this.deps.metrics?.incrementCounter('homerun_actions_dispatched_total', labels);
+        const start = performance.now();
+        try {
+            if (!this.deps.dryRun) {
+                await this.dispatch(action, ctx);
+            }
+            const duration = (performance.now() - start) / 1000;
+            this.deps.metrics?.observeHistogram('homerun_action_duration_seconds', duration, labels);
+            this.deps.metrics?.incrementCounter('homerun_actions_succeeded_total', labels);
+            this.deps.eventPublisher.publishActionEvent(this.makeResultEvent(ctx, action, 'ok'));
+        }
+        catch (err) {
+            const duration = (performance.now() - start) / 1000;
+            this.deps.metrics?.observeHistogram('homerun_action_duration_seconds', duration, labels);
+            this.deps.metrics?.incrementCounter('homerun_actions_failed_total', labels);
+            const error = err instanceof Error
+                ? err.message
+                : typeof err === 'object' && err !== null
+                    ? safeStringify(err)
+                    : String(err);
+            this.deps.eventPublisher.publishActionEvent(this.makeResultEvent(ctx, action, 'error', error));
+        }
+    }
+    async dispatch(action, ctx) {
+        switch (action.type) {
+            case 'ha.call_service': {
+                const entityId = action.target?.entity_id;
+                if (this.deps.commandAck?.enabled && entityId) {
+                    const expected = computeExpectedAck(action, this.deps.haClient.state(entityId));
+                    if (expected) {
+                        this.deps.haClient.registerPendingAck(entityId, {
+                            correlationId: ctx.correlationId,
+                            rootCorrelationId: ctx.rootCorrelationId,
+                            automationId: ctx.automationId,
+                            location: ctx.location,
+                            subsystem: ctx.subsystem,
+                            action,
+                            expected,
+                        }, this.deps.commandAck.timeoutMs);
+                    }
+                }
+                await this.deps.haClient.callService(action.domain, action.service, action.target, action.data, {
+                    correlationId: ctx.correlationId,
+                    rootCorrelationId: ctx.rootCorrelationId,
+                    automationId: ctx.automationId,
+                });
+                break;
+            }
+            case 'mqtt.publish':
+                if (action.impliesEntity) {
+                    this.deps.haClient.registerPendingWrite(action.impliesEntity, {
+                        correlationId: ctx.correlationId,
+                        rootCorrelationId: ctx.rootCorrelationId,
+                        automationId: ctx.automationId,
+                    });
+                }
+                await this.deps.mqttClient.publishAsync(action.topic, action.payload, { retain: action.retain ?? false });
+                break;
+            case 'timer.start':
+                this.deps.timerManager.start(action.timerKey, action.delayMs);
+                break;
+            case 'timer.cancel':
+                this.deps.timerManager.cancel(action.timerKey);
+                break;
+            default: {
+                const unknown = action.type;
+                throw new Error(`unknown action type: ${unknown}`);
+            }
+        }
+    }
+    baseFields(ctx) {
+        return {
+            schema: 'home.events.v2',
+            correlation_id: ctx.correlationId,
+            root_correlation_id: ctx.rootCorrelationId ?? ctx.correlationId,
+            automation_id: ctx.automationId,
+            location: ctx.location,
+            subsystem: ctx.subsystem,
+            timestamp: new Date().toISOString(),
+            ...(this.deps.dryRun ? { dry_run: true } : {}),
+            ...(ctx.parentCorrelationId && { parent_correlation_id: ctx.parentCorrelationId }),
+            ...(ctx.parentAutomationId && { parent_automation_id: ctx.parentAutomationId }),
+        };
+    }
+    makeStartedEvent(ctx, action) {
+        return { ...this.baseFields(ctx), event_type: 'action_started', action };
+    }
+    makeResultEvent(ctx, action, status, error) {
+        return {
+            ...this.baseFields(ctx),
+            event_type: 'action_result',
+            action,
+            status,
+            ...(error !== undefined && { error }),
+        };
+    }
+}

package/dist/src/framework/api-server.d.ts

@@ -0,0 +1,35 @@
+import type { AutomationRegistry } from './registry.js';
+import type { EventPublisher } from './event-publisher.js';
+import type { Automation } from '../types/automation.js';
+import type { TriggerEvent } from '../types/triggers.js';
+export interface MetricsProvider {
+    getMetrics(): Promise<string>;
+    contentType: string;
+}
+export interface ApiServerDeps {
+    registry: AutomationRegistry;
+    onTrigger: (automation: Automation<unknown>, event: TriggerEvent) => void;
+    onReload: () => Promise<void>;
+    isReady: () => boolean;
+    entityCount: () => number;
+    eventPublisher: EventPublisher;
+    dryRun?: boolean;
+    metrics?: MetricsProvider;
+}
+export declare class ApiServer {
+    private readonly deps;
+    private server;
+    private _port;
+    constructor(deps: ApiServerDeps);
+    get port(): number | null;
+    start(port?: number): Promise<void>;
+    stop(): Promise<void>;
+    private handle;
+    private getAutomations;
+    private postTrigger;
+    private postReload;
+    private getHealthLive;
+    private getHealthReady;
+    private getMetrics;
+    private getEvents;
+}

package/dist/src/framework/api-server.js

@@ -0,0 +1,132 @@
+import { createServer } from 'node:http';
+export class ApiServer {
+    deps;
+    server = null;
+    _port = null;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    get port() {
+        return this._port;
+    }
+    start(port = 7070) {
+        return new Promise((resolve, reject) => {
+            this.server = createServer((req, res) => this.handle(req, res));
+            this.server.listen(port, '0.0.0.0', () => {
+                const addr = this.server.address();
+                this._port = typeof addr === 'object' && addr ? addr.port : port;
+                console.log(`[homerun] API server listening on port ${this._port}`);
+                resolve();
+            });
+            this.server.once('error', reject);
+        });
+    }
+    stop() {
+        return new Promise((resolve, reject) => {
+            if (!this.server)
+                return resolve();
+            this.server.close((err) => (err ? reject(err) : resolve()));
+        });
+    }
+    handle(req, res) {
+        const method = req.method ?? 'GET';
+        const url = req.url ?? '/';
+        if (method === 'GET' && url === '/automations')
+            return this.getAutomations(res);
+        if (method === 'POST' && url === '/reload')
+            return this.postReload(res);
+        if (method === 'GET' && url === '/health/live')
+            return this.getHealthLive(res);
+        if (method === 'GET' && url === '/health/ready')
+            return this.getHealthReady(res);
+        if (method === 'GET' && url === '/events')
+            return this.getEvents(req, res);
+        if (method === 'GET' && url === '/metrics')
+            return this.getMetrics(res);
+        const triggerMatch = method === 'POST' && url.match(/^\/automations\/(.+)\/trigger$/);
+        if (triggerMatch)
+            return this.postTrigger(triggerMatch[1], res);
+        json(res, 404, { error: 'not found' });
+    }
+    getAutomations(res) {
+        const automations = this.deps.registry.getAll().map((a) => ({
+            id: a.id,
+            location: a.location,
+            subsystem: a.subsystem,
+            enabled: a.enabled ?? true,
+            triggers: a.triggers.map(serializeTrigger),
+        }));
+        json(res, 200, automations);
+    }
+    postTrigger(id, res) {
+        const automation = this.deps.registry.getById(id);
+        if (!automation) {
+            json(res, 404, { error: `no automation with id "${id}"` });
+            return;
+        }
+        const correlation_id = crypto.randomUUID();
+        this.deps.onTrigger(automation, { type: 'on_start', correlation_id, root_correlation_id: correlation_id });
+        json(res, 200, { ok: true });
+    }
+    postReload(res) {
+        this.deps.onReload()
+            .then(() => json(res, 200, { ok: true }))
+            .catch((err) => {
+            console.error('[ApiServer] reload failed:', err);
+            json(res, 500, { error: 'reload failed' });
+        });
+    }
+    getHealthLive(res) {
+        json(res, 200, { status: 'live' });
+    }
+    getHealthReady(res) {
+        if (!this.deps.isReady()) {
+            json(res, 503, { status: 'starting' });
+            return;
+        }
+        json(res, 200, {
+            status: 'ready',
+            entities: this.deps.entityCount(),
+            automations: this.deps.registry.getAll().length,
+            ...(this.deps.dryRun && { dry_run: true }),
+        });
+    }
+    getMetrics(res) {
+        if (!this.deps.metrics) {
+            json(res, 404, { error: 'metrics not enabled' });
+            return;
+        }
+        this.deps.metrics.getMetrics()
+            .then((output) => {
+            res.writeHead(200, { 'Content-Type': this.deps.metrics.contentType });
+            res.end(output);
+        })
+            .catch((err) => {
+            console.error('[ApiServer] metrics scrape failed:', err);
+            json(res, 500, { error: 'metrics scrape failed' });
+        });
+    }
+    getEvents(req, res) {
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive',
+        });
+        res.flushHeaders();
+        const unsubscribe = this.deps.eventPublisher.subscribe((event) => {
+            res.write(`data: ${JSON.stringify(event)}\n\n`);
+        });
+        req.on('close', unsubscribe);
+    }
+}
+function serializeTrigger(trigger) {
+    if (trigger.type === 'state_changed' && trigger.entity instanceof RegExp) {
+        return { ...trigger, entity: trigger.entity.toString() };
+    }
+    return trigger;
+}
+function json(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(payload);
+}

package/dist/src/framework/config.d.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+declare const ConfigSchema: z.ZodObject<{
+    homeassistant: z.ZodObject<{
+        url: z.ZodString;
+        token: z.ZodString;
+    }, z.core.$strip>;
+    mqtt: z.ZodObject<{
+        url: z.ZodString;
+    }, z.core.$strip>;
+    automations: z.ZodObject<{
+        dir: z.ZodString;
+    }, z.core.$strip>;
+    server: z.ZodDefault<z.ZodObject<{
+        port: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+        shutdown_timeout_ms: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    }, z.core.$strip>>;
+    options: z.ZodDefault<z.ZodObject<{
+        dry_run: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    metrics: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    events: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    commandAck: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        timeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type HomerunConfig = z.infer<typeof ConfigSchema>;
+export declare function parseConfig(configContent: string, secretsContent?: string): HomerunConfig;
+export declare function loadConfig(configPath?: string): Promise<HomerunConfig>;
+export {};

package/dist/src/framework/config.js

@@ -0,0 +1,93 @@
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { load, CORE_SCHEMA, defineScalarTag } from 'js-yaml';
+import { z } from 'zod';
+function isSecretRef(v) {
+    return typeof v === 'object' && v !== null && '__secret' in v;
+}
+const secretTag = defineScalarTag('!secret', {
+    implicit: false,
+    resolve: (source) => ({ __secret: source }),
+    // Load-only tag — config is never dumped back to YAML, so identify() is unreachable.
+    identify: () => false,
+});
+const SCHEMA_WITH_SECRET = CORE_SCHEMA.withTags(secretTag);
+const ConfigSchema = z.object({
+    homeassistant: z.object({
+        url: z.string().min(1, 'homeassistant.url is required'),
+        token: z.string().min(1, 'homeassistant.token is required'),
+    }),
+    mqtt: z.object({
+        url: z.string().min(1, 'mqtt.url is required'),
+    }),
+    automations: z.object({
+        dir: z.string().min(1, 'automations.dir is required'),
+    }),
+    server: z.object({
+        port: z.coerce.number().int().min(1).max(65535).default(7070),
+        shutdown_timeout_ms: z.coerce.number().int().min(0).default(10_000),
+    }).default({ port: 7070, shutdown_timeout_ms: 10_000 }),
+    options: z.object({
+        dry_run: z.boolean().default(false),
+    }).default({ dry_run: false }),
+    metrics: z.object({
+        enabled: z.boolean().default(false),
+    }).default({ enabled: false }),
+    events: z.object({
+        // Defaults to true — preserves existing behaviour for deployments that don't set this.
+        enabled: z.boolean().default(true),
+    }).default({ enabled: true }),
+    commandAck: z.object({
+        // Opt-in: unlike events.enabled, this is new/experimental behaviour with no prior
+        // installed base to preserve, so it defaults off rather than needing a reason to disable.
+        enabled: z.boolean().default(false),
+        // Needs to accommodate slow Zigbee mesh round-trips, not just fast local calls.
+        timeoutMs: z.coerce.number().int().min(0).default(8_000),
+    }).default({ enabled: false, timeoutMs: 8_000 }),
+});
+function resolveSecrets(value, secrets) {
+    if (isSecretRef(value)) {
+        const key = value.__secret;
+        if (!(key in secrets)) {
+            throw new Error(`!secret '${key}' not found in secrets.yaml`);
+        }
+        return secrets[key];
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => resolveSecrets(item, secrets));
+    }
+    if (typeof value === 'object' && value !== null) {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, resolveSecrets(v, secrets)]));
+    }
+    return value;
+}
+export function parseConfig(configContent, secretsContent) {
+    const raw = (load(configContent, { schema: SCHEMA_WITH_SECRET }) ?? {});
+    const secrets = secretsContent
+        ? (load(secretsContent) ?? {})
+        : {};
+    const resolved = resolveSecrets(raw, secrets);
+    const result = ConfigSchema.safeParse(resolved);
+    if (!result.success) {
+        const errors = result.error.issues
+            .map((i) => `  ${i.path.join('.') || '(root)'}: ${i.message}`)
+            .join('\n');
+        throw new Error(`[homerun] Invalid configuration:\n${errors}`);
+    }
+    return result.data;
+}
+export async function loadConfig(configPath) {
+    const absPath = path.resolve(configPath ?? process.env.HOMERUN_CONFIG ?? './configuration.yaml');
+    if (!existsSync(absPath)) {
+        throw new Error(`[homerun] Config file not found: ${absPath}\n` +
+            'Create configuration.yaml or set HOMERUN_CONFIG to point to your config file.\n' +
+            'See configuration.yaml.example for reference.');
+    }
+    const configContent = await readFile(absPath, 'utf8');
+    const secretsPath = path.join(path.dirname(absPath), 'secrets.yaml');
+    const secretsContent = existsSync(secretsPath)
+        ? await readFile(secretsPath, 'utf8')
+        : undefined;
+    return parseConfig(configContent, secretsContent);
+}

package/dist/src/framework/event-publisher.d.ts

@@ -0,0 +1,65 @@
+import type { MqttClient } from 'mqtt';
+import type { Action } from '../types/actions.js';
+import type { TriggerSummary } from '../types/triggers.js';
+type ObsEventBase = {
+    schema: 'home.events.v2';
+    correlation_id: string;
+    root_correlation_id: string;
+    parent_correlation_id?: string;
+    parent_automation_id?: string;
+    automation_id: string;
+    location: string;
+    subsystem: string;
+    timestamp: string;
+    dry_run?: boolean;
+};
+export type ObsEvent = ObsEventBase & ({
+    event_type: 'decision';
+    trigger: TriggerSummary;
+    decision: string;
+    reason?: string;
+    conditions?: Record<string, unknown>;
+    actions: Action[];
+    hasAction: boolean;
+} | {
+    event_type: 'abort';
+    trigger: TriggerSummary;
+    abort_kind: 'disabled' | 'unhandled_error' | 'guard' | 'unavailable_input';
+    reason?: string;
+    entity?: string;
+} | {
+    event_type: 'action_started';
+    action: Action;
+} | {
+    event_type: 'action_result';
+    action: Action;
+    status: 'ok' | 'error';
+    error?: string;
+} | {
+    event_type: 'action_ack_timeout';
+    action: Action;
+    entity: string;
+    expected: Record<string, unknown>;
+});
+export type LifecycleEventType = 'server_started' | 'server_stopping' | 'rescan_complete' | 'ha_reconnected';
+export interface LifecycleEvent {
+    schema: 'home.lifecycle.v1';
+    type: LifecycleEventType;
+    automation_count: number;
+    timestamp: string;
+    dry_run?: boolean;
+}
+export declare class EventPublisher {
+    private readonly mqtt;
+    private readonly enabled;
+    private readonly listeners;
+    constructor(mqtt: MqttClient, enabled?: boolean);
+    subscribe(listener: (event: ObsEvent) => void): () => void;
+    publishDecision(event: ObsEvent): void;
+    publishActionEvent(event: ObsEvent): void;
+    publishLifecycle(type: LifecycleEventType, automationCount: number, dryRun?: boolean): void;
+    private publish;
+    private safeSerialize;
+    private notifyListeners;
+}
+export {};

package/dist/src/framework/event-publisher.js

@@ -0,0 +1,85 @@
+export class EventPublisher {
+    mqtt;
+    enabled;
+    listeners = [];
+    // `enabled` gates MQTT publishing of decision/action ObsEvents only (mirrors metrics.enabled;
+    // see #144) — publishLifecycle (status/online heartbeat) is unaffected, and listeners (the
+    // /events SSE endpoint, any future persistent store) are always notified regardless, so
+    // consumers that don't want the MQTT stream aren't forced to lose in-process observability too.
+    constructor(mqtt, enabled = true) {
+        this.mqtt = mqtt;
+        this.enabled = enabled;
+    }
+    subscribe(listener) {
+        this.listeners.push(listener);
+        return () => {
+            const idx = this.listeners.indexOf(listener);
+            if (idx !== -1)
+                this.listeners.splice(idx, 1);
+        };
+    }
+    publishDecision(event) {
+        if (this.enabled) {
+            const payload = this.safeSerialize(event);
+            if (payload !== undefined) {
+                const ns = event.dry_run ? 'homerun/dev' : 'homerun';
+                this.publish(`${ns}/events`, payload, false);
+                this.publish(`${ns}/${event.location}/${event.subsystem}/decision`, payload, true);
+            }
+        }
+        this.notifyListeners(event);
+    }
+    publishActionEvent(event) {
+        if (this.enabled) {
+            const payload = this.safeSerialize(event);
+            if (payload !== undefined) {
+                const ns = event.dry_run ? 'homerun/dev' : 'homerun';
+                this.publish(`${ns}/events`, payload, false);
+            }
+        }
+        this.notifyListeners(event);
+    }
+    publishLifecycle(type, automationCount, dryRun = false) {
+        const event = {
+            schema: 'home.lifecycle.v1',
+            type,
+            automation_count: automationCount,
+            timestamp: new Date().toISOString(),
+            ...(dryRun && { dry_run: true }),
+        };
+        const ns = dryRun ? 'homerun/dev' : 'homerun';
+        const payload = JSON.stringify(event);
+        this.publish(`${ns}/lifecycle`, payload, false);
+        this.publish(`${ns}/status`, JSON.stringify({ status: 'online', automation_count: automationCount, timestamp: event.timestamp }), true);
+    }
+    publish(topic, payload, retain) {
+        this.mqtt.publishAsync(topic, payload, { retain }).catch((err) => {
+            console.error(`[EventPublisher] MQTT publish failed on ${topic}:`, err);
+        });
+    }
+    // Observability must never affect automation behaviour — a decision/action event that fails
+    // to serialize (e.g. conditions defaulting to a context object with a circular reference) must
+    // not throw, since runPipeline awaits this alongside actionRuntime.execute() in the same
+    // Promise.all; a synchronous throw here would silently prevent real actions from ever running.
+    safeSerialize(event) {
+        try {
+            return JSON.stringify(event);
+        }
+        catch (err) {
+            console.error(`[EventPublisher] failed to serialize ${event.event_type} event for ${event.automation_id} — MQTT publish skipped:`, err);
+            return undefined;
+        }
+    }
+    // Isolates listeners from each other and from the publisher — the same reliability principle
+    // applied to subscribers (e.g. the /events SSE endpoint) as to serialization above.
+    notifyListeners(event) {
+        for (const l of this.listeners) {
+            try {
+                l(event);
+            }
+            catch (err) {
+                console.error('[EventPublisher] listener threw, continuing:', err);
+            }
+        }
+    }
+}