@ajclarkson/homerun 0.0.1-edge.0131fc6

package/dist/src/framework/ha-client.d.ts

@@ -0,0 +1,85 @@
+import { type HassServiceTarget } from 'home-assistant-js-websocket';
+import { EventEmitter } from 'node:events';
+import type { Action } from '../types/actions.js';
+export interface EntityState {
+    entity_id: string;
+    state: string;
+    attributes: Record<string, unknown>;
+    last_changed: string;
+    last_updated: string;
+}
+declare global {
+    interface HAEntities {
+    }
+}
+type _HAStateKey = keyof HAEntities extends never ? string : keyof HAEntities;
+export type HAState = <E extends _HAStateKey>(entity: E) => (E extends keyof HAEntities ? EntityState & HAEntities[E] : EntityState) | undefined;
+export interface HAContext {
+    entitiesByLabel: (label: string) => string[];
+    labelsFor: (entity: string) => string[];
+    entitiesByArea: (area: string) => string[];
+}
+export interface StateChangedEvent {
+    entity_id: string;
+    old_state: EntityState | undefined;
+    new_state: EntityState;
+    correlation_id: string;
+    parent_correlation_id?: string;
+    root_correlation_id?: string;
+    parent_automation_id?: string;
+}
+export interface WriteOrigin {
+    correlationId: string;
+    rootCorrelationId?: string;
+    automationId: string;
+}
+export interface AckOrigin {
+    correlationId: string;
+    rootCorrelationId?: string;
+    automationId: string;
+    location: string;
+    subsystem: string;
+    action: Action;
+    expected: Record<string, unknown>;
+}
+export interface AckTimeoutEvent extends AckOrigin {
+    entity_id: string;
+}
+export declare interface HAClient {
+    on(event: 'state_changed', listener: (e: StateChangedEvent) => void): this;
+    on(event: 'ready', listener: () => void): this;
+    on(event: 'reconnected', listener: () => void): this;
+    on(event: 'action_ack_timeout', listener: (e: AckTimeoutEvent) => void): this;
+    emit(event: 'state_changed', e: StateChangedEvent): boolean;
+    emit(event: 'ready'): boolean;
+    emit(event: 'reconnected'): boolean;
+    emit(event: 'action_ack_timeout', e: AckTimeoutEvent): boolean;
+}
+export declare class HAClient extends EventEmitter {
+    private readonly stateCache;
+    private readonly labelToEntities;
+    private readonly entityToLabels;
+    private readonly areaToEntities;
+    private readonly pendingWrites;
+    private readonly pendingAcks;
+    private connection;
+    private reconnecting;
+    private _readyResolve;
+    readonly ready: Promise<void>;
+    readonly state: HAState;
+    readonly context: HAContext;
+    get entityCount(): number;
+    get registryStats(): {
+        labels: number;
+        areas: number;
+    };
+    callService(domain: string, service: string, target?: HassServiceTarget, data?: Record<string, unknown>, origin?: WriteOrigin): Promise<void>;
+    registerPendingWrite(entityId: string, origin: WriteOrigin): void;
+    registerPendingAck(entityId: string, origin: AckOrigin, timeoutMs: number): void;
+    disconnect(): void;
+    connect(url: string, token: string): Promise<void>;
+    private repopulateCache;
+    private diffAndUpdate;
+    private loadEntityRegistry;
+}
+export {};

package/dist/src/framework/ha-client.js

@@ -0,0 +1,201 @@
+import { callService, createConnection, createLongLivedTokenAuth, subscribeEntities, } from 'home-assistant-js-websocket';
+import { EventEmitter } from 'node:events';
+const PENDING_WRITE_TTL_MS = 2000;
+function ackSatisfied(expected, state) {
+    // HA represents every entity's state as a string, even numeric domains (number,
+    // input_number, ...) — a dispatched call's data.value is typically a plain JS number, so
+    // comparing `state` with strict equality never matches regardless of what HA does. See #158.
+    return Object.entries(expected).every(([key, value]) => key === 'state' ? String(state.state) === String(value) : state.attributes[key] === value);
+}
+export class HAClient extends EventEmitter {
+    stateCache = new Map();
+    labelToEntities = new Map();
+    entityToLabels = new Map();
+    areaToEntities = new Map();
+    // entity_id -> origin of the write that's expected to produce a state_changed for it.
+    // Self-evicts after PENDING_WRITE_TTL_MS; consumed (deleted) the moment it's matched.
+    pendingWrites = new Map();
+    // entity_id -> ack tracking for a dispatched call awaiting its expected state/attribute
+    // change. Consumed (timer cleared, deleted) the moment diffAndUpdate sees a satisfying
+    // state_changed; otherwise self-fires action_ack_timeout after its own timeout.
+    pendingAcks = new Map();
+    connection = null;
+    // True between a disconnect event and the next subscribeEntities callback.
+    // During this window we repopulate silently — no state_changed events emitted.
+    reconnecting = false;
+    _readyResolve;
+    ready = new Promise((resolve) => {
+        this._readyResolve = resolve;
+    });
+    // Synchronous accessors passed into context builders.
+    state = ((entity) => this.stateCache.get(entity));
+    context = {
+        entitiesByLabel: (label) => Array.from(this.labelToEntities.get(label) ?? []),
+        labelsFor: (entity) => this.entityToLabels.get(entity) ?? [],
+        entitiesByArea: (area) => Array.from(this.areaToEntities.get(area) ?? []),
+    };
+    get entityCount() {
+        return this.stateCache.size;
+    }
+    get registryStats() {
+        return { labels: this.labelToEntities.size, areas: this.areaToEntities.size };
+    }
+    async callService(domain, service, target, data, origin) {
+        if (!this.connection)
+            throw new Error('HAClient not connected');
+        const entityId = target?.entity_id;
+        if (origin && entityId)
+            this.registerPendingWrite(entityId, origin);
+        await callService(this.connection, domain, service, data, target);
+    }
+    // Registers that `origin` is expected to produce a state_changed for `entityId` — consumed
+    // (and stamped as parent_correlation_id/parent_automation_id) by diffAndUpdate on match, or
+    // self-evicted after PENDING_WRITE_TTL_MS if nothing arrives. Used by ha.call_service writes
+    // (automatically, via target.entity_id) and by mqtt.publish writes that declare `impliesEntity`
+    // (explicitly, since a topic alone carries no entity information — see #28, #138).
+    registerPendingWrite(entityId, origin) {
+        this.pendingWrites.set(entityId, origin);
+        setTimeout(() => this.pendingWrites.delete(entityId), PENDING_WRITE_TTL_MS);
+    }
+    // Registers that `entityId` is expected to reach `origin.expected` (a field/attribute ->
+    // value map) within `timeoutMs`. Consumed (timer cleared, deleted) by diffAndUpdate the
+    // moment a satisfying state_changed arrives; otherwise emits action_ack_timeout on expiry
+    // with the same origin, so a listener has everything needed to publish a self-sufficient
+    // ObsEvent without HAClient itself knowing about observability. See #55.
+    registerPendingAck(entityId, origin, timeoutMs) {
+        const timer = setTimeout(() => {
+            this.pendingAcks.delete(entityId);
+            this.emit('action_ack_timeout', { ...origin, entity_id: entityId });
+        }, timeoutMs);
+        this.pendingAcks.set(entityId, { ...origin, timer });
+    }
+    disconnect() {
+        this.connection?.close();
+        this.connection = null;
+    }
+    async connect(url, token) {
+        const auth = createLongLivedTokenAuth(url, token);
+        this.connection = await createConnection({ auth });
+        // Reload registry and repopulate cache silently on reconnect.
+        this.connection.addEventListener('disconnected', () => {
+            this.reconnecting = true;
+        });
+        await this.loadEntityRegistry();
+        this.connection.subscribeEvents(() => {
+            console.log('[ha-client] entity_registry_updated received — reloading registry');
+            this.loadEntityRegistry()
+                .then(() => {
+                console.log(`[ha-client] registry reloaded (${this.labelToEntities.size} labels, ${this.areaToEntities.size} areas)`);
+            })
+                .catch((err) => {
+                console.error('[ha-client] registry reload failed after entity_registry_updated:', err);
+            });
+        }, 'entity_registry_updated').catch((err) => {
+            console.error('[ha-client] failed to subscribe to entity_registry_updated:', err);
+        });
+        let firstSnapshot = true;
+        subscribeEntities(this.connection, (entities) => {
+            if (firstSnapshot) {
+                firstSnapshot = false;
+                this.repopulateCache(entities);
+                this._readyResolve();
+                this.emit('ready');
+            }
+            else if (this.reconnecting) {
+                this.reconnecting = false;
+                // Reload registry in the background — don't block the cache repopulate.
+                this.loadEntityRegistry().catch((err) => {
+                    console.error('[ha-client] registry reload failed after reconnect:', err);
+                });
+                this.repopulateCache(entities);
+                this.emit('reconnected');
+            }
+            else {
+                this.diffAndUpdate(entities);
+            }
+        });
+    }
+    // ---------- Private ----------
+    repopulateCache(entities) {
+        this.stateCache.clear();
+        for (const [id, entity] of Object.entries(entities)) {
+            this.stateCache.set(id, toEntityState(id, entity));
+        }
+    }
+    diffAndUpdate(entities) {
+        for (const [id, rawEntity] of Object.entries(entities)) {
+            const old_state = this.stateCache.get(id);
+            const new_state = toEntityState(id, rawEntity);
+            // last_updated changes whenever state or attributes change in HA. It's also compared as
+            // a millisecond-precision string (see toEntityState), so two distinct state changes to
+            // the same entity within the same millisecond collide on last_updated alone — compare
+            // state directly too so a genuine transition is never silently dropped. See #170.
+            if (!old_state || old_state.state !== new_state.state || old_state.last_updated !== new_state.last_updated) {
+                this.stateCache.set(id, new_state);
+                const ack = this.pendingAcks.get(id);
+                if (ack && ackSatisfied(ack.expected, new_state)) {
+                    clearTimeout(ack.timer);
+                    this.pendingAcks.delete(id);
+                }
+                const correlation_id = crypto.randomUUID();
+                const origin = this.pendingWrites.get(id);
+                if (origin)
+                    this.pendingWrites.delete(id);
+                this.emit('state_changed', {
+                    entity_id: id,
+                    old_state,
+                    new_state,
+                    correlation_id,
+                    root_correlation_id: origin ? (origin.rootCorrelationId ?? origin.correlationId) : correlation_id,
+                    ...(origin && { parent_correlation_id: origin.correlationId, parent_automation_id: origin.automationId }),
+                });
+            }
+        }
+        // Prune entities that disappeared from the snapshot.
+        for (const id of this.stateCache.keys()) {
+            if (!(id in entities)) {
+                this.stateCache.delete(id);
+            }
+        }
+    }
+    async loadEntityRegistry() {
+        if (!this.connection)
+            return;
+        const entries = (await this.connection.sendMessagePromise({
+            type: 'config/entity_registry/list',
+        }));
+        this.labelToEntities.clear();
+        this.entityToLabels.clear();
+        this.areaToEntities.clear();
+        for (const entry of entries) {
+            const labels = entry.labels ?? [];
+            this.entityToLabels.set(entry.entity_id, labels);
+            for (const label of labels) {
+                let set = this.labelToEntities.get(label);
+                if (!set) {
+                    set = new Set();
+                    this.labelToEntities.set(label, set);
+                }
+                set.add(entry.entity_id);
+            }
+            if (entry.area_id) {
+                let set = this.areaToEntities.get(entry.area_id);
+                if (!set) {
+                    set = new Set();
+                    this.areaToEntities.set(entry.area_id, set);
+                }
+                set.add(entry.entity_id);
+            }
+        }
+    }
+}
+// ---------- Helpers ----------
+function toEntityState(entity_id, entity) {
+    return {
+        entity_id,
+        state: entity.state,
+        attributes: entity.attributes,
+        last_changed: entity.last_changed,
+        last_updated: entity.last_updated,
+    };
+}

package/dist/src/framework/hot-reload.d.ts

@@ -0,0 +1,9 @@
+import type { AutomationRegistry } from './registry.js';
+type Importer = (dataUri: string) => Promise<{
+    default: unknown;
+}>;
+export declare function _reloadFile(filePath: string, registry: AutomationRegistry, importer?: Importer, fileToIds?: Map<string, string[]>): Promise<void>;
+export declare function _deleteFile(filePath: string, registry: AutomationRegistry, fileToIds?: Map<string, string[]>): void;
+export declare function rescanAutomations(automationsDir: string, registry: AutomationRegistry, fileToIds?: Map<string, string[]>, importer?: Importer): Promise<void>;
+export declare function startHotReload(automationsDir: string, registry: AutomationRegistry): void;
+export {};

package/dist/src/framework/hot-reload.js

@@ -0,0 +1,88 @@
+import path from 'node:path';
+import { watch } from 'chokidar';
+import { build } from 'esbuild';
+const defaultImporter = (dataUri) => import(dataUri);
+// Module-level file→IDs map used in production. Tests pass their own instance.
+const moduleFileToIds = new Map();
+export async function _reloadFile(filePath, registry, importer = defaultImporter, fileToIds = moduleFileToIds) {
+    try {
+        const result = await build({
+            entryPoints: [filePath],
+            bundle: true,
+            platform: 'node',
+            format: 'esm',
+            write: false,
+            alias: {
+                '@ajclarkson/homerun/testing': path.resolve(import.meta.dirname, '../testing.js'),
+                '@ajclarkson/homerun': path.resolve(import.meta.dirname, '../lib.js'),
+            },
+        });
+        const code = result.outputFiles[0].text;
+        const dataUri = `data:text/javascript;base64,${Buffer.from(code).toString('base64')}`;
+        const mod = await importer(dataUri);
+        if (!mod.default) {
+            throw new Error(`${filePath} has no default export`);
+        }
+        const automations = Array.isArray(mod.default)
+            ? mod.default
+            : [mod.default];
+        // Deregister previous automations from this file only after successful load.
+        for (const id of fileToIds.get(filePath) ?? []) {
+            registry.unregister(id);
+        }
+        for (const auto of automations) {
+            registry.register(auto);
+        }
+        fileToIds.set(filePath, automations.map((a) => a.id));
+    }
+    catch (err) {
+        console.error(`[hot-reload] failed to reload ${filePath}:`, err);
+    }
+}
+export function _deleteFile(filePath, registry, fileToIds = moduleFileToIds) {
+    for (const id of fileToIds.get(filePath) ?? []) {
+        registry.unregister(id);
+    }
+    fileToIds.delete(filePath);
+}
+const EXCLUDED_DIRS = new Set(['types', 'lib']);
+const isAutomationFile = (f) => f.endsWith('.ts') &&
+    !f.endsWith('.test.ts') &&
+    !f.includes('node_modules') &&
+    !f.includes('.d.ts') &&
+    !f.split(path.sep).some(seg => EXCLUDED_DIRS.has(seg));
+export async function rescanAutomations(automationsDir, registry, fileToIds = moduleFileToIds, importer = defaultImporter) {
+    let files = [];
+    try {
+        const { readdir } = await import('node:fs/promises');
+        files = (await readdir(automationsDir, { recursive: true }));
+    }
+    catch {
+        console.warn(`[homerun] AUTOMATIONS_DIR not found: ${automationsDir} — starting with no automations`);
+    }
+    const currentPaths = new Set(files.filter(isAutomationFile).map((f) => path.join(automationsDir, f)));
+    for (const trackedPath of [...fileToIds.keys()]) {
+        if (!currentPaths.has(trackedPath)) {
+            _deleteFile(trackedPath, registry, fileToIds);
+        }
+    }
+    for (const filePath of currentPaths) {
+        await _reloadFile(filePath, registry, importer, fileToIds);
+    }
+}
+export function startHotReload(automationsDir, registry) {
+    const target = process.env.AUTOMATION
+        ? path.join(automationsDir, `${process.env.AUTOMATION}.ts`)
+        : `${automationsDir}/**/*.ts`;
+    const watcher = watch(target, { ignoreInitial: true, ignored: [/node_modules/, /\.test\.ts$/] });
+    const reload = (filePath) => {
+        _reloadFile(filePath, registry).catch((err) => {
+            console.error('[hot-reload] unexpected error:', err);
+        });
+    };
+    watcher.on('add', reload);
+    watcher.on('change', reload);
+    watcher.on('unlink', (filePath) => {
+        _deleteFile(filePath, registry);
+    });
+}

package/dist/src/framework/metrics-prom.d.ts

@@ -0,0 +1,18 @@
+import { Registry } from 'prom-client';
+import type { MetricsBackend } from './metrics.js';
+export declare class PromMetricsBackend implements MetricsBackend {
+    readonly registry: Registry<"text/plain; version=0.0.4; charset=utf-8">;
+    private readonly haEventsTotal;
+    private readonly pipelineRunsTotal;
+    private readonly actionsDispatchedTotal;
+    private readonly actionsSucceededTotal;
+    private readonly actionsFailedTotal;
+    private readonly actionDurationSeconds;
+    private readonly automationsLoaded;
+    constructor(collectDefaults?: boolean);
+    incrementCounter(name: string, labels?: Record<string, string>): void;
+    observeHistogram(name: string, value: number, labels?: Record<string, string>): void;
+    setGauge(name: string, value: number): void;
+    getMetrics(): Promise<string>;
+    get contentType(): string;
+}

package/dist/src/framework/metrics-prom.js

@@ -0,0 +1,93 @@
+import { Registry, Counter, Gauge, Histogram, collectDefaultMetrics } from 'prom-client';
+export class PromMetricsBackend {
+    registry = new Registry();
+    haEventsTotal;
+    pipelineRunsTotal;
+    actionsDispatchedTotal;
+    actionsSucceededTotal;
+    actionsFailedTotal;
+    actionDurationSeconds;
+    automationsLoaded;
+    constructor(collectDefaults = false) {
+        if (collectDefaults) {
+            collectDefaultMetrics({ register: this.registry });
+        }
+        this.haEventsTotal = new Counter({
+            name: 'homerun_ha_events_received_total',
+            help: 'Total HA and MQTT events received by homerun',
+            labelNames: ['event_type'],
+            registers: [this.registry],
+        });
+        this.pipelineRunsTotal = new Counter({
+            name: 'homerun_pipeline_runs_total',
+            help: 'Total automation pipeline runs',
+            labelNames: ['location', 'trigger_type'],
+            registers: [this.registry],
+        });
+        this.actionsDispatchedTotal = new Counter({
+            name: 'homerun_actions_dispatched_total',
+            help: 'Total actions dispatched by the action runtime',
+            labelNames: ['location', 'action_type'],
+            registers: [this.registry],
+        });
+        this.actionsSucceededTotal = new Counter({
+            name: 'homerun_actions_succeeded_total',
+            help: 'Total actions that completed successfully',
+            labelNames: ['location', 'action_type'],
+            registers: [this.registry],
+        });
+        this.actionsFailedTotal = new Counter({
+            name: 'homerun_actions_failed_total',
+            help: 'Total actions that failed with an error',
+            labelNames: ['location', 'action_type'],
+            registers: [this.registry],
+        });
+        this.actionDurationSeconds = new Histogram({
+            name: 'homerun_action_duration_seconds',
+            help: 'Duration of action execution in seconds',
+            labelNames: ['location', 'action_type'],
+            buckets: [0.01, 0.05, 0.1, 0.5, 1, 2, 5],
+            registers: [this.registry],
+        });
+        this.automationsLoaded = new Gauge({
+            name: 'homerun_automations_loaded',
+            help: 'Number of automations currently loaded',
+            registers: [this.registry],
+        });
+    }
+    incrementCounter(name, labels = {}) {
+        switch (name) {
+            case 'homerun_ha_events_received_total':
+                this.haEventsTotal.inc(labels);
+                break;
+            case 'homerun_pipeline_runs_total':
+                this.pipelineRunsTotal.inc(labels);
+                break;
+            case 'homerun_actions_dispatched_total':
+                this.actionsDispatchedTotal.inc(labels);
+                break;
+            case 'homerun_actions_succeeded_total':
+                this.actionsSucceededTotal.inc(labels);
+                break;
+            case 'homerun_actions_failed_total':
+                this.actionsFailedTotal.inc(labels);
+                break;
+        }
+    }
+    observeHistogram(name, value, labels = {}) {
+        if (name === 'homerun_action_duration_seconds') {
+            this.actionDurationSeconds.observe(labels, value);
+        }
+    }
+    setGauge(name, value) {
+        if (name === 'homerun_automations_loaded') {
+            this.automationsLoaded.set(value);
+        }
+    }
+    async getMetrics() {
+        return this.registry.metrics();
+    }
+    get contentType() {
+        return this.registry.contentType;
+    }
+}

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

@@ -0,0 +1,10 @@
+export interface MetricsBackend {
+    incrementCounter(name: string, labels?: Record<string, string>): void;
+    observeHistogram(name: string, value: number, labels?: Record<string, string>): void;
+    setGauge(name: string, value: number, labels?: Record<string, string>): void;
+}
+export declare class NoopMetricsBackend implements MetricsBackend {
+    incrementCounter(): void;
+    observeHistogram(): void;
+    setGauge(): void;
+}

package/dist/src/framework/metrics.js

@@ -0,0 +1,5 @@
+export class NoopMetricsBackend {
+    incrementCounter() { }
+    observeHistogram() { }
+    setGauge() { }
+}

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

@@ -0,0 +1,14 @@
+import type { Automation } from '../types/automation.js';
+import type { TriggerEvent } from '../types/triggers.js';
+import type { HAClient } from './ha-client.js';
+import type { EventPublisher } from './event-publisher.js';
+import type { ActionRuntime } from './action-runtime.js';
+import type { MetricsBackend } from './metrics.js';
+interface Deps {
+    eventPublisher: EventPublisher;
+    actionRuntime: ActionRuntime;
+    dryRun?: boolean;
+    metrics?: MetricsBackend;
+}
+export declare function runPipeline(automation: Automation<unknown>, event: TriggerEvent, haClient: HAClient, deps: Deps): Promise<void>;
+export {};

package/dist/src/framework/pipeline.js

@@ -0,0 +1,85 @@
+import { summarizeTrigger } from '../types/triggers.js';
+import { isAbort, UnavailableInputError } from '../types/automation.js';
+export async function runPipeline(automation, event, haClient, deps) {
+    deps.metrics?.incrementCounter('homerun_pipeline_runs_total', {
+        location: automation.location,
+        trigger_type: event.type,
+    });
+    const correlationId = event.correlation_id;
+    const rootCorrelationId = event.root_correlation_id ?? correlationId;
+    const timestamp = new Date().toISOString();
+    const trigger = summarizeTrigger(event);
+    const base = {
+        schema: 'home.events.v2',
+        correlation_id: correlationId,
+        root_correlation_id: rootCorrelationId,
+        automation_id: automation.id,
+        location: automation.location,
+        subsystem: automation.subsystem,
+        timestamp,
+        ...(deps.dryRun ? { dry_run: true } : {}),
+        ...(event.parent_correlation_id && { parent_correlation_id: event.parent_correlation_id }),
+        ...(event.parent_automation_id && { parent_automation_id: event.parent_automation_id }),
+    };
+    // Step 1: Enabled check
+    if (automation.enabled === false) {
+        deps.eventPublisher.publishDecision({ ...base, event_type: 'abort', abort_kind: 'disabled', trigger });
+        return;
+    }
+    // Step 2: Context
+    let ctx;
+    try {
+        ctx = automation.context(haClient.state, haClient.context, event);
+    }
+    catch (err) {
+        if (err instanceof UnavailableInputError) {
+            deps.eventPublisher.publishDecision({ ...base, event_type: 'abort', abort_kind: 'unavailable_input', entity: err.entityId, trigger });
+        }
+        else {
+            deps.eventPublisher.publishDecision({ ...base, event_type: 'abort', abort_kind: 'unhandled_error', trigger });
+        }
+        return;
+    }
+    if (isAbort(ctx)) {
+        deps.eventPublisher.publishDecision({ ...base, event_type: 'abort', abort_kind: 'guard', reason: ctx.reason, trigger });
+        return;
+    }
+    // Step 3: Reduce
+    let result;
+    try {
+        result = automation.reduce(ctx);
+    }
+    catch {
+        deps.eventPublisher.publishDecision({ ...base, event_type: 'abort', abort_kind: 'unhandled_error', trigger });
+        return;
+    }
+    // Step 4: Validate — safe defaults
+    const actions = result.actions ?? [];
+    // Defaults to the full context object so authors get observability "for free" without
+    // hand-duplicating context fields into conditions — reduce() can still override with its
+    // own (e.g. trimmed) conditions when the full context isn't what should be published.
+    const conditions = result.conditions ?? ctx;
+    const decision = {
+        ...base,
+        event_type: 'decision',
+        trigger,
+        decision: result.decision,
+        reason: result.reason,
+        conditions,
+        actions,
+        hasAction: actions.length > 0,
+    };
+    // Step 5: Fanout
+    await Promise.all([
+        Promise.resolve(deps.eventPublisher.publishDecision(decision)),
+        deps.actionRuntime.execute(actions, {
+            correlationId,
+            automationId: automation.id,
+            location: automation.location,
+            subsystem: automation.subsystem,
+            rootCorrelationId,
+            ...(event.parent_correlation_id && { parentCorrelationId: event.parent_correlation_id }),
+            ...(event.parent_automation_id && { parentAutomationId: event.parent_automation_id }),
+        }),
+    ]);
+}

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

@@ -0,0 +1,10 @@
+import type { Automation } from '../types/automation.js';
+export declare class AutomationRegistry {
+    private readonly automations;
+    private readonly changeCallbacks;
+    onChange(cb: () => void): void;
+    register(automation: Automation<unknown>): void;
+    unregister(id: string): void;
+    getAll(): Automation<unknown>[];
+    getById(id: string): Automation<unknown> | undefined;
+}

package/dist/src/framework/registry.js

@@ -0,0 +1,24 @@
+export class AutomationRegistry {
+    automations = new Map();
+    changeCallbacks = [];
+    onChange(cb) {
+        this.changeCallbacks.push(cb);
+    }
+    register(automation) {
+        this.automations.set(automation.id, automation);
+        for (const cb of this.changeCallbacks)
+            cb();
+    }
+    unregister(id) {
+        if (!this.automations.delete(id))
+            return;
+        for (const cb of this.changeCallbacks)
+            cb();
+    }
+    getAll() {
+        return Array.from(this.automations.values());
+    }
+    getById(id) {
+        return this.automations.get(id);
+    }
+}

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

@@ -0,0 +1,13 @@
+import type { Automation } from '../types/automation.js';
+import type { TriggerEvent } from '../types/triggers.js';
+export declare class Scheduler {
+    private readonly automations;
+    private readonly dispatch;
+    private readonly ready;
+    private readonly cleanups;
+    constructor(automations: Automation<unknown>[], dispatch: (event: TriggerEvent) => void, ready: Promise<void>);
+    start(): void;
+    sync(automations: Automation<unknown>[]): void;
+    stop(): void;
+    private registerCronTriggers;
+}