svelte-kit-vice/src/uix/sema/engine.ts

/**
 * EngineSemantic — registry de canales perceptivos + dispatch.
 *
 * El engine no conoce DOM, ni hold, ni atributos de estado. Su trabajo es:
 *
 *   1. Asignar un id estable a cada ocurrencia.
 *   2. Ejecutar `channel.prepare(...)` antes de la cascade para que los
 *      canales publiquen su superficie temporal si la necesitan.
 *   3. Resolver la `EffectiveSignature` con las 5 capas de cascade.
 *   4. Despachar a cada canal registrado.
 *   5. Esperar al canal visual y limpiar los handles de preparación.
 *
 * Override layers (ver `resolver.ts`):
 *   1. family base                  — SEMA_MAP.families
 *   2. intent deltas                — SEMA_MAP.intents (any family with intent)
 *   3. morfo per-event              — signal.overrides + signal.channels
 *   4. runtime path overrides       — engineOpts.overrides.runtime
 *                                     (applied to map at construction)
 *   5a. pack cascade                — engineOpts.components (per-component
 *                                     packs, prepended)
 *   5b. app cascade                 — engineOpts.overrides.cascade
 *                                     (app-level rules appended; win on tie)
 */

import type { Channel, ChannelPreparation } from './chans/types';
import type { DomApplier } from '$adom';
import type { Logger } from '$libs/logger';
import { HapticChannel, type HapticChannelDom, type HapticChannelOptions } from './chans/haptic';
import { SoundChannel, type SoundChannelDom, type SoundChannelOptions } from './chans/sound';
import type { EngineSound } from '$sound';
import { VisualChannel, type VisualChannelOptions } from './chans/visual';
import {
	AnnounceChannel,
	type AnnounceChannelDom,
	type AnnounceChannelOptions
} from './chans/announce';
import { SemaDuplicateChannelError } from './errors';
import {
	applyMapOverrides,
	resolveSignature,
	type EffectiveSignature,
	type SemaCascadeRule
} from './resolver';
import { SEMA_MAP, type SemaMap, type Sema } from './sema-map';
import type { DeltaValue, SemaPreferences } from './channels';
import type { SemanticSignal } from './signal';
import type { SignalProjector } from './projection';
import { semaDelay, type SemaTimerScheduler, type SemaTimerHandle } from './timers';

export interface EngineSemanticOverrides {
	/**
	 * Path-based mutations of the SEMA_MAP applied at construction. The
	 * canonical map is not mutated; only the overridden object path is cloned.
	 */
	runtime?: Record<string, DeltaValue>;

	/**
	 * App-level cascade rules (CSS-style). Concatenated AFTER all
	 * per-component packs so app rules win on tie (declaration order).
	 */
	cascade?: readonly SemaCascadeRule[];
}

export interface EngineSemanticOptions {
	/** VisualChannel built-in. `false` to disable; object for opts; Channel to replace. */
	visual?: false | VisualChannelOptions | Channel;
	/** SoundChannel built-in. `true`/object/Channel to enable; `false`/undef to skip. */
	sound?: true | false | SoundChannelOptions | Channel;
	/**
	 * The shared Web Audio runtime (`$sound`), injected by the composition root
	 * as `uix.sound`. Forwarded to the built-in `SoundChannel` so the whole
	 * document meets at ONE `AudioContext`: the browser caps them and the
	 * autoplay unlock gesture is per-context, so a second engine would leave
	 * one of the two mute. The engine is NOT owned here — whoever created it
	 * disposes it (`ownsSound` in `active-uix`). When absent, the channel
	 * creates and owns a private one (direct construction / unit tests).
	 */
	soundEngine?: EngineSound;
	/** HapticChannel built-in. `true`/object/Channel to enable; `false`/undef to skip. */
	haptic?: true | false | HapticChannelOptions | Channel;
	/**
	 * AnnounceChannel built-in (accessible ARIA live region). `true`/object to
	 * enable; `false`/undef to skip. Opt-in like sound / haptic. Pass
	 * `{ announce }` to delegate to an existing announcer (e.g.
	 * `ActiveUix.announce`); otherwise it owns a pair of live regions built from
	 * the injected `dom`. Book `BK-SIGNAL-A11Y` / `BK-A11Y-CRITICAL`.
	 */
	announce?: true | false | AnnounceChannelOptions | Channel;

	/**
	 * Optional diagnostics logger. When omitted, channel failures stay
	 * silent — a deliberate purity rule: the engine knows no platform, so it
	 * never falls back to `console` (the layer contract guards this). In
	 * practice the failures are NOT silent in apps: the ActiveUix
	 * composition root always injects its logger
	 * (`active-uix.svelte.ts` — `logger: eventsOpts.logger ?? logger`), so a
	 * silent engine only exists in bare constructions (unit tests /
	 * headless), by choice (SEM-2 adjudication, 2026-07-11).
	 */
	logger?: Logger;

	/**
	 * Per-component packs of perceptual defaults. Each pack ships with
	 * the component (`src/uix/sema/components/{name}.ts`) and is
	 * concatenated into the cascade BEFORE `overrides.cascade`. Tree-
	 * shakable: only packs the app imports get included.
	 */
	components?: readonly Sema[];

	/** Override layers 4 (runtime path) + 5b (app cascade). */
	overrides?: EngineSemanticOverrides;

	/**
	 * Projector forwarded to the built-in VisualChannel. The engine stores no
	 * projector itself; channels own their prepare/materialization details.
	 */
	projector?: SignalProjector;

	/**
	 * DOM writer forwarded to the built-in VisualChannel's default projector.
	 * In `active-uix` this is `uix.dom`, so sema projects event attrs through
	 * the same DOM owner as soma.
	 */
	dom?: DomApplier | (DomApplier & SoundChannelDom);

	/**
	 * Managed timer scheduler (`uix.timers`) forwarded to the built-in
	 * channels. Every perceptual timer — the visual hold, the haptic delay,
	 * the sound earcon completion — runs on it instead of a raw `setTimeout`,
	 * so timing is cancellable, observable and test-deterministic. `active-uix`
	 * injects `uix.timers`; omitting it makes the channels fall back to
	 * `setTimeout` (unit-test / degraded path only).
	 */
	timers?: SemaTimerScheduler;

	/**
	 * Per-channel reduction preferences (BK-REDUCTIONS, book ch. 32 §12 / ch.
	 * 33 §7). Forwarded to the built-in `sound` + `haptic` channels so an app
	 * can attenuate (`'reduce'`) or silence (`'off'`) a modality symmetrically.
	 * Read at dispatch, so backing it with reactive state makes it live.
	 * Visual-motion reduction lives in eidos CSS, not here.
	 */
	preferences?: SemaPreferences;

	/**
	 * Frequency memory (BK-FREQ-MEMORY, book ch. 32 §11): repeated occurrences
	 * of the SAME event attenuate their non-visual channels so the 50th
	 * autosave does not sound like the first. `threat` is never damped. Default
	 * ON; set `false` to disable. Requires a `timers` scheduler for the decay
	 * window (falls back to a raw timeout in unit tests).
	 */
	frequencyMemory?: boolean;

	/**
	 * Dominance arbiter (BK-DOMINANCE, book ch. 30 §7): when signals overlap in
	 * time, a signal dominated by a still-active one (evaluable > structural;
	 * higher activation; recency) has its non-visual channels muted while its
	 * visual hold survives. `threat` is never muted. Default ON; set `false` to
	 * disable.
	 */
	dominance?: boolean;
}

interface PersistentSignalEntry {
	readonly preparations: readonly ChannelPreparation[];
	readonly target: HTMLElement | undefined;
}

// ── Frequency memory (C-2) + dominance (C-3) tuning ───────────────────────────
/** Non-threat signals of the same key start attenuating after this count. */
const FREQ_THRESHOLD = 2;
/** Attenuation lost per repeat past the threshold. */
const FREQ_STEP = 0.15;
/** Attenuation floor — repeated signals never fall below this fraction. */
const FREQ_FLOOR = 0.25;
/** Window of silence (ms) after which a key's repeat count resets to full. */
const FREQ_WINDOW_MS = 2000;
/** How long (ms) an occurrence counts as "active" for dominance overlap. */
const DOMINANCE_WINDOW_MS = 400;

/**
 * Scale (or, at `factor <= 0`, mute) the non-visual channels. Muting DROPS
 * `sound` / `haptic` from `activeChannels` rather than scaling to zero, because
 * haptic intensity is floored (a `0` still buzzes). The visual hold and the
 * accessible `announce` channel are never touched.
 */
function attenuateNonVisual(effective: EffectiveSignature, factor: number): EffectiveSignature {
	if (factor >= 1) return effective;
	if (factor <= 0) {
		return {
			...effective,
			activeChannels: effective.activeChannels.filter((c) => c !== 'sound' && c !== 'haptic')
		};
	}
	const next: EffectiveSignature = { ...effective };
	if (next.sound) next.sound = { ...next.sound, gain: next.sound.gain * factor };
	if (next.haptic) next.haptic = { ...next.haptic, intensity: next.haptic.intensity * factor };
	return next;
}

/** Activation level implied by an intent (book ch. 31 §5 / ch. 32 §2). */
function activationOf(intent: EffectiveSignature['intent']): number {
	switch (intent) {
		case 'threat':
			return 4;
		case 'fulfill':
			return 3;
		case 'risk':
			return 2;
		case 'loss':
		case 'affirm':
			return 1;
		default:
			return 0;
	}
}

/**
 * Dominance rank of an occurrence (higher wins). One comparable number for the
 * book's criteria: an evaluable event (commit / signal) outranks a structural
 * one; within that, higher activation outranks lower. Recency is handled by the
 * caller using a strict `>` so an equal-ranked newcomer stays audible.
 */
function occurrenceRank(effective: EffectiveSignature): number {
	const evaluable = effective.family === 'commit' || effective.family === 'signal' ? 1 : 0;
	return evaluable * 10 + activationOf(effective.intent);
}

export class EngineSemantic {
	private readonly channels = new Map<string, Channel>();
	private nextSignalId = 0;

	private readonly map: SemaMap;
	private readonly cascade: readonly SemaCascadeRule[];
	private readonly logger: Logger | undefined;

	/**
	 * Active non-transient signals — projection handles kept alive past the
	 * hold for `untilAction` / `untilFix` / `stateBound`. Cleared via
	 * `clear(id)` or `clearTarget(target)`. Per book §6.1: persistence is
	 * caller-managed; the engine only holds the cleanup handle.
	 */
	private readonly active = new Map<string, PersistentSignalEntry>();

	private readonly timers: SemaTimerScheduler | undefined;
	private readonly frequencyMemory: boolean;
	private readonly dominance: boolean;
	/** Per-event-key repeat counts for frequency memory (C-2). */
	private readonly freqCounts = new Map<string, { count: number; reset?: SemaTimerHandle }>();
	/** Occurrences still "active" for dominance (C-3), keyed by occurrence id. */
	private readonly activeOccurrences = new Map<string, { rank: number; expire: SemaTimerHandle }>();

	constructor(opts: EngineSemanticOptions = {}) {
		this.logger = opts.logger;
		this.timers = opts.timers;
		this.frequencyMemory = opts.frequencyMemory ?? true;
		this.dominance = opts.dominance ?? true;

		// Layer 4 — runtime path overrides baked into the map at construction.
		this.map = applyMapOverrides(SEMA_MAP, opts.overrides?.runtime);

		// Layers 5a/5b — flatten per-component packs (lower precedence) +
		// app-level cascade (higher precedence on tie).
		const packCascade: SemaCascadeRule[] = [];
		const preloadUrls = new Set<string>();
		for (const pack of opts.components ?? []) {
			for (const rule of pack.cascade) {
				packCascade.push(rule as SemaCascadeRule);
			}
			for (const url of pack.preloadSamples ?? []) {
				preloadUrls.add(url);
			}
		}
		this.cascade = [...packCascade, ...(opts.overrides?.cascade ?? [])];

		// Channels.
		if (opts.visual !== false) {
			const visualChannel: Channel = isChannel(opts.visual)
				? opts.visual
				: new VisualChannel({
						...(opts.visual ?? {}),
						dom: opts.dom,
						projector: opts.projector,
						timers: opts.timers
					});
			this.register(visualChannel);
		}

		if (opts.sound !== undefined && opts.sound !== false) {
			let soundChannel: Channel;
			if (isChannel(opts.sound)) {
				soundChannel = opts.sound;
			} else {
				const soundOptions = opts.sound === true ? {} : opts.sound;
				soundChannel = new SoundChannel({
					...soundOptions,
					engine: soundOptions.engine ?? opts.soundEngine,
					dom: soundOptions.dom ?? (isSoundChannelDom(opts.dom) ? opts.dom : undefined),
					timers: soundOptions.timers ?? opts.timers,
					preferences: soundOptions.preferences ?? opts.preferences,
					logger: opts.logger
				});
			}
			this.register(soundChannel);

			// Pre-decode the WAVs declared by component packs so the first
			// emit doesn't pay the fetch + decode latency. The built-in channel
			// delegates to its engine; a REPLACEMENT channel (`opts.sound` as a
			// Channel) has no such method, so the shared engine — when the root
			// injected one — is preloaded directly. Before the extraction that
			// case simply skipped the preload.
			if (preloadUrls.size > 0) {
				if (soundChannel instanceof SoundChannel) {
					void soundChannel.preloadSamples([...preloadUrls]);
				} else if (opts.soundEngine) {
					void opts.soundEngine.preload([...preloadUrls]);
				}
			}
		}

		if (opts.announce !== undefined && opts.announce !== false) {
			let announceChannel: Channel;
			if (isChannel(opts.announce)) {
				announceChannel = opts.announce;
			} else {
				const announceOptions = opts.announce === true ? {} : opts.announce;
				announceChannel = new AnnounceChannel({
					...announceOptions,
					dom: announceOptions.dom ?? (isAnnounceChannelDom(opts.dom) ? opts.dom : undefined)
				});
			}
			this.register(announceChannel);
		}

		if (opts.haptic !== undefined && opts.haptic !== false) {
			let hapticChannel: Channel;
			if (isChannel(opts.haptic)) {
				hapticChannel = opts.haptic;
			} else {
				const hapticOptions = opts.haptic === true ? {} : opts.haptic;
				hapticChannel = new HapticChannel({
					...hapticOptions,
					dom: hapticOptions.dom ?? (isHapticChannelDom(opts.dom) ? opts.dom : undefined),
					timers: hapticOptions.timers ?? opts.timers,
					preferences: hapticOptions.preferences ?? opts.preferences
				});
			}
			this.register(hapticChannel);
		}
	}

	register(channel: Channel): void {
		if (this.channels.has(channel.id)) {
			throw new SemaDuplicateChannelError(channel.id);
		}
		this.channels.set(channel.id, channel);
	}

	/**
	 * Despacha una señal a todos los canales registrados.
	 *
	 * Lifecycle:
	 *   1. Generate id and run channel prepare hooks.
	 *      VisualChannel.prepare() projects `data-event-*` on target.
	 *   2. resolveSignature → cascade selectors match against the now-
	 *      projected target via native `target.matches()`.
	 *   3. Fire-and-forget non-visual channels.
	 *   4. Await visual channel hold.
	 *   5. Cleanup prepare handles.
	 *
	 * Sequential strict: the caller's structural commit happens AFTER
	 * cleanup. State change is strictly ordered after the perceptual window.
	 */
	async emit(signal: SemanticSignal): Promise<string> {
		const id = signal.id ?? `sig-${this.nextSignalId++}`;
		const enriched: SemanticSignal = { ...signal, id };

		// Explicit silence (capa 3 morfo override): `signal.channels: []`
		// skips EVERYTHING — no projection, no dispatch, no hold. The morfo
		// declared this event has no perceptual surface. Other paths to an
		// empty `effective.activeChannels` (e.g. signal with no family —
		// degenerate case) still go through dispatch so individual channels
		// can self-skip via their own activeChannels check.
		if (signal.channels !== undefined && signal.channels.length === 0) {
			return id;
		}

		const preparations: ChannelPreparation[] = [];
		for (const channel of this.channels.values()) {
			const handle = channel.prepare?.(enriched);
			if (handle) preparations.push(handle);
		}

		const persistence = signal.persistence ?? 'transient';
		const shouldAutoCleanup = persistence === 'transient';
		let cleanedUp = false;

		try {
			let effective = resolveSignature(enriched, {
				map: this.map,
				cascade: this.cascade
			});

			// Post-resolution perceptual modulation. Both touch ONLY the
			// non-visual channels (sound / haptic); the visual hold is never
			// altered, so eidos's CSS reactions are unaffected.
			//   C-2 frequency memory — repeated same-key signals attenuate.
			//   C-3 dominance — a signal dominated by a still-active one is muted.
			effective = this.applyFrequencyMemory(enriched, effective);
			effective = this.applyDominance(enriched, effective);

			const visualChannel = this.channels.get('visual');
			const otherChannels: Channel[] = [];
			for (const channel of this.channels.values()) {
				if (channel.id !== 'visual') otherChannels.push(channel);
			}

			for (const channel of otherChannels) {
				channel.handle(enriched, effective).catch((err) => {
					this.logger?.error('sema', `channel "${channel.id}" failed`, {
						error: err,
						context: { channel: channel.id, signal: enriched.id }
					});
				});
			}

			// Visual owns the hold timing. It runs whenever there are ANY
			// active channels — the empty-channels case was already handled
			// by the early return above. Visual isn't in family activeChannels
			// (those describe real runtime channels like sound / haptic) —
			// it's a meta channel that gates the data-event-* hold for eidos
			// CSS reactions.
			if (visualChannel) {
				await visualChannel.handle(enriched, effective);
			}
		} finally {
			if (shouldAutoCleanup) {
				for (const handle of [...preparations].reverse()) {
					handle.cleanup();
				}
				cleanedUp = true;
			}
		}

		// Persistent signals: keep projection alive past the hold. Caller
		// (typically a soma provider) clears via `clear(id)` or
		// `clearTarget(target)` when the relevant condition is met. If the
		// caller never clears, the projection lingers until dispose() — by
		// design: persistence is caller-managed per book §6.1.
		if (!cleanedUp) {
			this.active.set(id, { preparations, target: signal.target });
		}

		return id;
	}

	/**
	 * Clear an active persistent signal by id. Returns `true` if the signal
	 * was found and cleared, `false` if it didn't exist (already cleared,
	 * was transient, or never emitted).
	 *
	 * Call this from the caller that originally emitted the signal when
	 * the underlying condition is met:
	 *   - `untilAction` — user acknowledged the alert.
	 *   - `untilFix`    — the validation error was corrected.
	 *   - `stateBound`  — the state ended.
	 */
	clear(id: string): boolean {
		const entry = this.active.get(id);
		if (!entry) return false;
		this.active.delete(id);
		for (const handle of [...entry.preparations].reverse()) {
			handle.cleanup();
		}
		return true;
	}

	/**
	 * Clear all active persistent signals whose `target` matches the given
	 * element. Returns the count of signals cleared. Useful when a single
	 * gesture invalidates multiple persistent signals on the same surface
	 * (e.g. a form with three field warnings: one form-valid clears all).
	 */
	clearTarget(target: HTMLElement): number {
		let count = 0;
		for (const [id, entry] of this.active) {
			if (entry.target === target) {
				this.active.delete(id);
				for (const handle of [...entry.preparations].reverse()) {
					handle.cleanup();
				}
				count++;
			}
		}
		return count;
	}

	/**
	 * Whether a persistent signal id is currently active. Read-only helper
	 * for diagnostics and tests; production code should not branch on this.
	 */
	hasActive(id: string): boolean {
		return this.active.has(id);
	}

	/**
	 * C-2 — frequency memory (BK-FREQ-MEMORY, book ch. 32 §11). Attenuates the
	 * non-visual channels of a signal repeated within a short window so a burst
	 * of the same event fades instead of hammering. `threat` is exempt. A pause
	 * of `FREQ_WINDOW_MS` resets the key to full intensity.
	 */
	private applyFrequencyMemory(
		signal: SemanticSignal,
		effective: EffectiveSignature
	): EffectiveSignature {
		if (!this.frequencyMemory) return effective;
		if (effective.intent === 'threat') return effective;

		const key = signal.name || `${effective.family ?? ''}:${effective.intent ?? ''}`;
		const entry = this.freqCounts.get(key) ?? { count: 0 };
		entry.count += 1;
		entry.reset?.cancel();
		entry.reset = semaDelay(this.timers, FREQ_WINDOW_MS, () => this.freqCounts.delete(key), {
			channel: 'frequency'
		});
		this.freqCounts.set(key, entry);

		const over = entry.count - FREQ_THRESHOLD;
		if (over <= 0) return effective;
		const atten = Math.max(FREQ_FLOOR, 1 - over * FREQ_STEP);
		return attenuateNonVisual(effective, atten);
	}

	/**
	 * C-3 — dominance arbiter (BK-DOMINANCE, book ch. 30 §7). Registers each
	 * occurrence as active for a short overlap window and mutes the non-visual
	 * channels of an INCOMING signal that a still-active occurrence out-ranks
	 * (evaluable > structural; higher activation; recency breaks ties in favour
	 * of the newcomer). `threat` is never muted. The visual hold survives so the
	 * dominated event still reads structurally.
	 */
	private applyDominance(
		signal: SemanticSignal,
		effective: EffectiveSignature
	): EffectiveSignature {
		if (!this.dominance) return effective;
		// `emit` always enriches the signal with an id before this runs. The
		// old `?? sig-N++` fallback here was dead — and, had it ever fired, it
		// would have minted an id DIFFERENT from the one the rest of the
		// pipeline uses, desyncing the occurrence bookkeeping (SEM-3). A
		// degenerate un-enriched call now skips dominance instead.
		const id = signal.id;
		if (id === undefined) return effective;
		const rank = occurrenceRank(effective);

		let dominated = false;
		if (effective.intent !== 'threat') {
			for (const active of this.activeOccurrences.values()) {
				if (active.rank > rank) {
					dominated = true;
					break;
				}
			}
		}

		this.activeOccurrences.get(id)?.expire.cancel();
		const expire = semaDelay(
			this.timers,
			DOMINANCE_WINDOW_MS,
			() => this.activeOccurrences.delete(id),
			{ channel: 'dominance' }
		);
		this.activeOccurrences.set(id, { rank, expire });

		return dominated ? attenuateNonVisual(effective, 0) : effective;
	}

	getChannel(id: string): Channel | undefined {
		return this.channels.get(id);
	}

	dispose(): void {
		// Clean up any lingering persistent signal projections before tearing
		// down channels, so DOM doesn't keep stale data-event-* attrs.
		for (const entry of this.active.values()) {
			for (const handle of [...entry.preparations].reverse()) {
				handle.cleanup();
			}
		}
		this.active.clear();

		// Cancel the frequency-memory and dominance decay timers.
		for (const entry of this.freqCounts.values()) entry.reset?.cancel();
		this.freqCounts.clear();
		for (const entry of this.activeOccurrences.values()) entry.expire.cancel();
		this.activeOccurrences.clear();

		for (const channel of this.channels.values()) {
			channel.dispose?.();
		}
		this.channels.clear();
	}
}

function isChannel(value: unknown): value is Channel {
	return (
		value !== null &&
		typeof value === 'object' &&
		typeof (value as Channel).id === 'string' &&
		typeof (value as Channel).handle === 'function'
	);
}

function isSoundChannelDom(value: unknown): value is SoundChannelDom {
	return (
		value !== null &&
		typeof value === 'object' &&
		typeof (value as SoundChannelDom).getDocument === 'function' &&
		typeof (value as SoundChannelDom).listen === 'function'
	);
}

function isAnnounceChannelDom(value: unknown): value is AnnounceChannelDom {
	return (
		value !== null &&
		typeof value === 'object' &&
		typeof (value as AnnounceChannelDom).getDocument === 'function'
	);
}

function isHapticChannelDom(value: unknown): value is HapticChannelDom {
	return (
		value !== null &&
		typeof value === 'object' &&
		typeof (value as HapticChannelDom).prefersReducedMotion === 'object' &&
		(value as HapticChannelDom).prefersReducedMotion !== null
	);
}