@camstack/types 1.2.267 → 1.2.269

package/dist/composition-D5BQywfe.mjs

@@ -0,0 +1,2055 @@
+import { a as DeviceType, i as DeviceRole } from "./err-msg-DX6i_MY4.mjs";
+import { z } from "zod";
+import { createHash } from "node:crypto";
+//#region src/ffmpeg/invocation.ts
+var AUDIO_ENCODER_BY_CODEC = {
+	opus: "libopus",
+	aac: "aac",
+	pcmu: "pcm_mulaw",
+	pcma: "pcm_alaw"
+};
+/**
+* Camera-microphone audio, per codec. Lives HERE rather than in
+* `encode-defaults.ts` only to avoid an import cycle (`encode-defaults` depends
+* on these types); it is re-exported from there, which is where to read it.
+*
+* Every source in this repo is a mono camera mic. The former broker preset
+* encoded Opus at `channels: 2`, spending bitrate duplicating one channel —
+* that is the value this consolidation changed.
+*/
+var AUDIO_PRESETS = {
+	aac: {
+		kind: "encode",
+		codec: "aac",
+		bitrateKbps: 128,
+		sampleRateHz: 48e3,
+		channels: 1
+	},
+	opus: {
+		kind: "encode",
+		codec: "opus",
+		bitrateKbps: 64,
+		sampleRateHz: 48e3,
+		channels: 1
+	},
+	pcmu: {
+		kind: "encode",
+		codec: "pcmu",
+		sampleRateHz: 8e3,
+		channels: 1
+	}
+};
+/** `-hide_banner -loglevel <level>` — every ffmpeg site opens with this. */
+function logBannerArgs(level) {
+	return [
+		"-hide_banner",
+		"-loglevel",
+		level
+	];
+}
+/** `true` when the resolved value means "decode in software" (⇒ no `-hwaccel`). */
+function isSoftwareDecode(decodeHwAccel) {
+	return !decodeHwAccel || decodeHwAccel === "none" || decodeHwAccel === "copy";
+}
+/**
+* Every INPUT option, in order, terminated by `-i <url>`. Nothing may be
+* appended to this list by a caller — that is the whole point of the function.
+*/
+function buildInputArgs(input, decodeHwAccel) {
+	const args = [];
+	if (!isSoftwareDecode(decodeHwAccel)) args.push("-hwaccel", String(decodeHwAccel));
+	if (input.extraArgs?.length) args.push(...input.extraArgs);
+	if (input.decodeThreadCount !== void 0 && input.decodeThreadCount > 0) args.push("-threads", String(input.decodeThreadCount));
+	if (input.analyzeDurationUs !== void 0) args.push("-analyzeduration", String(input.analyzeDurationUs));
+	if (input.probeSizeBytes !== void 0) args.push("-probesize", String(input.probeSizeBytes));
+	if (input.lowDelay === true) args.push("-flags", "low_delay");
+	if (input.useWallclockTimestamps === true) args.push("-use_wallclock_as_timestamps", "1");
+	if (input.fflags?.length) for (const flag of input.fflags) args.push("-fflags", flag);
+	if (input.rtspTransport) args.push("-rtsp_transport", input.rtspTransport);
+	if (input.rawVideo !== void 0) {
+		const raw = input.rawVideo;
+		args.push("-f", "rawvideo", "-pix_fmt", raw.pixelFormat, "-video_size", `${String(raw.width)}x${String(raw.height)}`, "-framerate", String(raw.framerate));
+	}
+	args.push("-i", input.url);
+	return args;
+}
+/**
+* Derive the output `-map` selectors. The three cases, in the order they are
+* decided:
+*
+* 1. **A filter graph** — the picture is the graph's declared video pad, and
+*    the audio is its audio pad when it has one, otherwise input 0's mic. A
+*    graph's output is not addressable any other way.
+* 2. **N inputs, no graph** — map input 0 EXPLICITLY. ffmpeg's own selection
+*    picks the "best" stream across ALL inputs, so the egress would silently
+*    become whichever camera happens to have the largest frame.
+* 3. **One input, no graph** — no `-map`. Anything else would change the argv
+*    of every call site that exists today for no gain.
+*/
+function resolveStreamMaps(selection) {
+	const graph = selection.filterGraph;
+	if (graph) return {
+		video: `[${graph.videoOutLabel}]`,
+		audio: graph.audioOutLabel ? `[${graph.audioOutLabel}]` : "0:a:0?"
+	};
+	if (selection.extraInputs?.length) return {
+		video: "0:v:0",
+		audio: "0:a:0?"
+	};
+	return {
+		video: null,
+		audio: null
+	};
+}
+/** The `-vf` filter args, or `[]` when a consumer `-vf` already claims the slot. */
+function buildVideoFilterArgs(scale, outputArgs, filterGraph, hwUpload) {
+	if (filterGraph) {
+		if (scale) throw new Error("FfmpegInvocation: video.scale cannot be combined with a filter graph — scale inside the graph instead (the -vf would feed an output the graph already feeds)");
+		if (outputArgs.some((a) => a === "-vf")) throw new Error("FfmpegInvocation: outputArgs carries a -vf while a filter graph feeds the same output — fold the filter into the graph");
+		return [];
+	}
+	if (outputArgs.some((a) => a === "-vf")) return [];
+	if (!scale) return hwUpload.length > 0 ? ["-vf", hwUpload] : [];
+	const suffix = hwUpload.length > 0 ? `,${hwUpload}` : "";
+	if (scale.mode === "exact") return ["-vf", `scale=${scale.width}:${scale.height}${suffix}`];
+	return ["-vf", `scale='min(${scale.width},iw)':'min(${scale.height},ih)':force_original_aspect_ratio=decrease:force_divisible_by=2${suffix}`];
+}
+/**
+* The upload filter a hardware encode needs, or `''`.
+*
+* Nothing is uploaded when the DECODE already left the frames on the GPU
+* (`-hwaccel vaapi`): they are surfaces already, and uploading a surface is an
+* error rather than a no-op.
+*/
+function resolveHwUpload(device, decodeHwAccel) {
+	if (device === void 0) return "";
+	if (!isSoftwareDecode(decodeHwAccel)) return "";
+	return "format=nv12,hwupload";
+}
+/** Rate-control args for an encode plan. */
+function buildRateControlArgs(video) {
+	const kbps = video.bitrateKbps;
+	if (kbps === void 0) return [];
+	const rc = video.rateControl ?? {
+		kind: "cap",
+		vbvSeconds: 2
+	};
+	const bufsize = Math.max(1, Math.round(kbps * rc.vbvSeconds));
+	return [
+		...rc.kind === "cbr" ? ["-b:v", `${kbps}k`] : [],
+		"-maxrate",
+		`${kbps}k`,
+		"-bufsize",
+		`${bufsize}k`
+	];
+}
+/** The whole video block (`-vf` … `-c:v` … knobs), after `-i`. */
+function buildVideoArgs(video, outputArgs, filterGraph, hwEncode) {
+	if (video.kind === "raw") {
+		if (filterGraph && video.filter !== void 0) throw new Error("FfmpegInvocation: video.filter cannot be combined with a filter graph — fold the filter into the graph");
+		return [
+			...video.filter !== void 0 ? ["-vf", video.filter] : [],
+			"-c:v",
+			"rawvideo",
+			"-pix_fmt",
+			video.pixelFormat,
+			...video.fps !== void 0 ? ["-r", String(video.fps)] : []
+		];
+	}
+	if (video.kind === "copy") {
+		if (filterGraph) throw new Error("FfmpegInvocation: a filter graph produces a NEW picture, so video.kind must be `encode`");
+		return [
+			"-c:v",
+			"copy",
+			...video.bitstreamFilter ? ["-bsf:v", video.bitstreamFilter] : []
+		];
+	}
+	const hwUpload = hwEncode === void 0 ? "" : resolveHwUpload(hwEncode.device, hwEncode.decodeHwAccel);
+	if (hwEncode !== void 0 && filterGraph) throw new Error("FfmpegInvocation: a hardware encode fed by a filter graph must upload INSIDE the graph — hwEncodeDevice cannot be combined with filterGraph");
+	const args = [
+		...buildVideoFilterArgs(video.scale, outputArgs, filterGraph, hwUpload),
+		"-c:v",
+		video.encoder
+	];
+	if (video.preset !== void 0) args.push("-preset", video.preset);
+	if (video.tune !== void 0) args.push("-tune", video.tune);
+	if (video.singleSlicePerFrame === true && video.encoder === "libx264") args.push("-x264-params", "sliced-threads=0");
+	if (video.profile !== void 0) args.push("-profile:v", video.profile);
+	if (video.level !== void 0) args.push("-level", video.level);
+	if (video.pixelFormat !== void 0) args.push("-pix_fmt", video.pixelFormat);
+	if (video.fps !== void 0) args.push("-r", String(video.fps));
+	if (video.gopFrames !== void 0) args.push("-g", String(video.gopFrames));
+	if (video.forceKeyFramesSeconds !== void 0) args.push("-force_key_frames", `expr:gte(t,n_forced*${video.forceKeyFramesSeconds})`);
+	if (video.bf !== void 0) args.push("-bf", String(video.bf));
+	args.push(...buildRateControlArgs(video));
+	if (video.bitstreamFilter !== void 0) args.push("-bsf:v", video.bitstreamFilter);
+	return args;
+}
+/** The whole audio block, after `-i`. */
+function buildAudioArgs(audio) {
+	if (audio.kind === "none") return ["-an"];
+	if (audio.kind === "copy") return ["-c:a", "copy"];
+	const args = [];
+	if (audio.filter !== void 0) args.push("-af", audio.filter);
+	args.push("-c:a", AUDIO_ENCODER_BY_CODEC[audio.codec]);
+	if (audio.application !== void 0) args.push("-application", audio.application);
+	if (audio.frameDurationMs !== void 0) args.push("-frame_duration", String(audio.frameDurationMs));
+	if (audio.globalHeader === true) args.push("-flags", "+global_header");
+	if (audio.sampleRateHz !== void 0) args.push("-ar", String(audio.sampleRateHz));
+	if (audio.bitrateKbps !== void 0) args.push("-b:a", `${audio.bitrateKbps}k`);
+	if (audio.vbvBufferKbits !== void 0) args.push("-bufsize", `${audio.vbvBufferKbits}k`);
+	if (audio.channels !== void 0) args.push("-ac", String(audio.channels));
+	return args;
+}
+/** RTP output-leg args (`-payload_type`, `-ssrc`, `-sdp_file`, `-f rtp <url>`). */
+function buildRtpOutputArgs(out) {
+	const args = [];
+	if (out.payloadType !== void 0) args.push("-payload_type", String(out.payloadType));
+	if (out.ssrc !== void 0) args.push("-ssrc", String(out.ssrc));
+	if (out.sdpFile !== void 0) args.push("-sdp_file", out.sdpFile);
+	args.push("-f", "rtp", out.url);
+	return args;
+}
+/** `true` when the sink is a raw elementary bytestream that cannot mux audio. */
+function isElementaryVideoSink(sink) {
+	return sink.kind === "stdout" && (sink.container === "h264" || sink.container === "hevc");
+}
+/**
+* The fragmented-MP4 muxer flags, in the order the recorder has proven them
+* (`recorder/addon/ffmpeg-args.ts` passes the same `movflags` string through
+* `-segment_format_options`, across every vendor in the fleet):
+*
+* - `frag_keyframe` — cut a fragment at each key frame, so every fragment
+*   opens on a sync sample. HKSV's whole requirement.
+* - `empty_moov` — write `ftyp`+`moov` up front with no samples in it, which
+*   is what makes the head a standalone INITIALISATION segment.
+* - `default_base_moof` — fragment offsets are self-relative, so a fragment is
+*   demuxable without the bytes that preceded it. D31's byte-range read path
+*   depends on exactly this property of the recorder's segments.
+*/
+var FMP4_MOVFLAGS = "+frag_keyframe+empty_moov+default_base_moof";
+/**
+* The terminal sink args for every non-`rtp-outputs` sink. Exhaustive over the
+* union so a new member cannot fall through to `['-f', container, 'pipe:1']`,
+* which is what a plain `container` read would have done for `mp4` — a valid
+* argv that writes a NON-fragmented, unseekable-to-a-pipe MP4 and produces one
+* unusable byte stream.
+*/
+function buildStdoutOrRtspSinkArgs(sink) {
+	if (sink.kind === "rtsp-listen") return [
+		"-f",
+		"rtsp",
+		"-rtsp_transport",
+		"tcp",
+		"-rtsp_flags",
+		"listen",
+		sink.url
+	];
+	if (sink.kind === "rtp-outputs") return [];
+	return sink.container === "mp4" ? buildFmp4SinkArgs(sink) : [
+		"-f",
+		sink.container,
+		"pipe:1"
+	];
+}
+/**
+* How far BELOW the negotiated fragment length `-min_frag_duration` is set.
+*
+* `-min_frag_duration` refuses to cut before that much media has accumulated,
+* and then waits for the next key frame. Set to exactly `fragmentMs`, the
+* commonest camera configuration in existence — a key-frame grid EQUAL to the
+* requested fragment length — lands the deadline on the same instant as the key
+* frame, loses the race, and skips to the following one: **every fragment comes
+* out at twice the requested length.**
+*
+* Measured on the live fleet 2026-08-07, camera 615, `-c:v copy` (D84):
+*
+* | slot | GOP | `-min_frag_duration` | median gap |
+* | --- | --- | --- | --- |
+* | 1280×720 | 40 f @ 10 fps = 4.0 s | 4000 ms | **7944 ms** |
+* | 1280×720 | 40 f @ 10 fps = 4.0 s | 3600 ms | 3973 ms |
+* | 3840×2160 | 100 f @ 25 fps = 4.0 s | 4000 ms | 8042 ms |
+* | 3840×2160 | 100 f @ 25 fps = 4.0 s | 3600 ms | 3998 ms |
+*
+* A doubled fragment is not a cosmetic overshoot: HKSV requires every fragment
+* to be no longer than the length the controller SELECTED, so the shipped-but-
+* inert phase-1 sink would have violated the contract on its first real clip.
+*
+* 10 % is chosen against the two failures either side of it. Too small and
+* ordinary jitter (measured spread 3953-4096 ms) re-loses the race; too large
+* and a source with a key frame slightly EARLY than the grid gets cut there,
+* yielding a short fragment for no reason.
+*/
+var FMP4_MIN_FRAG_MARGIN = .9;
+/** `-movflags … -min_frag_duration <us> -f mp4 pipe:1`. */
+function buildFmp4SinkArgs(sink) {
+	return [
+		"-movflags",
+		FMP4_MOVFLAGS,
+		"-min_frag_duration",
+		String(Math.max(0, Math.round(sink.fragmentMs * FMP4_MIN_FRAG_MARGIN * 1e3))),
+		"-f",
+		"mp4",
+		"pipe:1"
+	];
+}
+/**
+* A second output mapping source audio to RTP-over-UDP. `0:a:0?` makes the
+* audio optional so a source with no audio skips it instead of failing the
+* whole invocation.
+*/
+function buildAudioSidecarArgs(sidecar) {
+	return [
+		"-map",
+		"0:a:0?",
+		...buildAudioArgs(sidecar.codec === "pcma" ? {
+			kind: "encode",
+			codec: "pcma",
+			sampleRateHz: 8e3,
+			channels: 1
+		} : AUDIO_PRESETS[sidecar.codec]),
+		...buildRtpOutputArgs({
+			url: sidecar.rtpUrl,
+			sdpFile: sidecar.sdpFile
+		})
+	];
+}
+/**
+* Assemble the full ffmpeg argument list. Layout:
+*
+*   -hide_banner -loglevel <level>
+*   [-hwaccel <backend|auto>]        ─┐ INPUT options — strictly before -i.
+*   [<input.extraArgs>]               │
+*   [-fflags <flag>…]                 │
+*   [-rtsp_transport tcp]             │
+*   -i <url>                         ─┘ …repeated per extraInput
+*   [-filter_complex <graph>]         ─ global, after the LAST -i
+*   [-map <video>]  <video block>  <threads>  ─┐ OUTPUT options.
+*   [-map <audio>]  <audio block>              │
+*   <consumer outputArgs verbatim>             │
+*   <sink>                                    ─┘ terminal
+*
+* The `-map`s are DERIVED (see {@link resolveStreamMaps}), never constants:
+* one input with no graph emits none at all, which is why the argv of every
+* call site that predates the N-input extension is unchanged to the byte.
+*
+* {@link FfmpegInvocation.audioSidecar} is the one map that stays literal
+* (`0:a:0?`): the sidecar is defined as the SOURCE's microphone on its own RTP
+* output, not as whatever the main output happens to carry.
+*/
+/** The hardware-encode context for this invocation, or `undefined`. */
+function hwEncodeFor(inv) {
+	return inv.hwEncodeDevice === void 0 ? void 0 : {
+		device: inv.hwEncodeDevice,
+		decodeHwAccel: inv.decodeHwAccel
+	};
+}
+function buildFfmpegArgs(inv) {
+	const graph = inv.filterGraph ?? null;
+	const head = [
+		...logBannerArgs(inv.logLevel),
+		...inv.hwEncodeDevice !== void 0 ? ["-vaapi_device", inv.hwEncodeDevice.renderNode] : [],
+		...buildInputArgs(inv.input, inv.decodeHwAccel),
+		...(inv.extraInputs ?? []).flatMap((extra) => buildInputArgs(extra, inv.decodeHwAccel)),
+		...graph ? ["-filter_complex", graph.graph] : []
+	];
+	const threadArgs = [...inv.threadCount > 0 ? ["-threads", String(inv.threadCount)] : [], ...inv.filterThreadCount !== void 0 && inv.filterThreadCount > 0 ? ["-filter_threads", String(inv.filterThreadCount)] : []];
+	const maps = resolveStreamMaps(inv);
+	const videoMapArgs = maps.video ? ["-map", maps.video] : [];
+	const audioMapArgs = maps.audio ? ["-map", maps.audio] : [];
+	if (inv.sink.kind === "rtp-outputs") {
+		const videoLeg = inv.sink.video ? [
+			"-an",
+			"-map",
+			maps.video ?? "0:v:0",
+			...buildVideoArgs(inv.video, inv.outputArgs, graph, hwEncodeFor(inv)),
+			...threadArgs,
+			...inv.outputArgs,
+			...buildRtpOutputArgs(inv.sink.video)
+		] : [];
+		const audioLeg = inv.sink.audio ? [
+			"-vn",
+			"-map",
+			maps.audio ?? "0:a:0?",
+			...buildAudioArgs(inv.audio),
+			...buildRtpOutputArgs(inv.sink.audio)
+		] : [];
+		return [
+			...head,
+			...videoLeg,
+			...audioLeg
+		];
+	}
+	const mutedAudio = isElementaryVideoSink(inv.sink) || inv.audio.kind === "none";
+	const audioArgs = isElementaryVideoSink(inv.sink) ? ["-an"] : buildAudioArgs(inv.audio);
+	return [
+		...head,
+		...videoMapArgs,
+		...buildVideoArgs(inv.video, inv.outputArgs, graph, hwEncodeFor(inv)),
+		...threadArgs,
+		...mutedAudio ? [] : audioMapArgs,
+		...audioArgs,
+		...inv.outputArgs,
+		...buildStdoutOrRtspSinkArgs(inv.sink),
+		...inv.audioSidecar ? buildAudioSidecarArgs(inv.audioSidecar) : []
+	];
+}
+/**
+* Hardware ENCODER ids per decode-hwaccel backend — a static, deterministic
+* map (the same shape the reference NVR uses: platform → encoder, no probe).
+*/
+var ENCODER_IDS_BY_BACKEND = {
+	videotoolbox: {
+		h264: "h264_videotoolbox",
+		h265: "hevc_videotoolbox"
+	},
+	vaapi: {
+		h264: "h264_vaapi",
+		h265: "hevc_vaapi"
+	},
+	qsv: {
+		h264: "h264_qsv",
+		h265: "hevc_qsv"
+	},
+	cuda: {
+		h264: "h264_nvenc",
+		h265: "hevc_nvenc"
+	},
+	nvdec: {
+		h264: "h264_nvenc",
+		h265: "hevc_nvenc"
+	},
+	amf: {
+		h264: "h264_amf",
+		h265: "hevc_amf"
+	}
+};
+/**
+* The hardware encoder for a target codec on `backend`, or the software one.
+* `'auto'` is NOT a backend identity (it is an instruction to ffmpeg), so it
+* maps to software encoding.
+*/
+function pickVideoEncoder(target, backend, useHardware) {
+	const software = target === "h264" ? "libx264" : "libx265";
+	if (!useHardware || backend === null || isSoftwareDecode(backend) || backend === "auto") return software;
+	const ids = ENCODER_IDS_BY_BACKEND[backend.toLowerCase()];
+	if (!ids) return software;
+	return target === "h264" ? ids.h264 : ids.h265;
+}
+/** Map an `EncodeProfile.audio` to an audio plan. */
+function audioPlanFromEncodeProfile(audio) {
+	if (audio === "passthrough") return { kind: "none" };
+	if (audio.codec === "copy") return { kind: "copy" };
+	return {
+		kind: "encode",
+		codec: audio.codec,
+		...audio.bitrateKbps !== void 0 ? { bitrateKbps: audio.bitrateKbps } : {},
+		...audio.sampleRateHz !== void 0 ? { sampleRateHz: audio.sampleRateHz } : {},
+		...audio.channels !== void 0 ? { channels: audio.channels } : {}
+	};
+}
+/**
+* Adapt an `EncodeProfile` (the operator/consumer-facing shape) into an
+* {@link FfmpegInvocation}. This is the ONLY bridge between the two models —
+* a second one is how the repo grew two argv builders that disagreed about
+* hardware.
+*
+* Smart video copy: when the source already speaks the requested codec the
+* encode block is elided entirely and ffmpeg runs as a re-muxer on the video
+* plane. Width / height / fps / bitrate in the profile are a downstream BUDGET,
+* not a forced rescale.
+*/
+function invocationFromEncodeProfile(input) {
+	const v = input.profile.video;
+	const shouldCopy = v.codec === "copy" || input.forceReencode !== true && v.codec === input.sourceCodec;
+	const scale = v.width !== void 0 && v.height !== void 0 ? {
+		mode: "fit",
+		width: v.width,
+		height: v.height
+	} : null;
+	const target = v.codec === "h265" ? "h265" : "h264";
+	const video = shouldCopy ? {
+		kind: "copy",
+		...input.bitstreamFilter !== void 0 ? { bitstreamFilter: input.bitstreamFilter } : {}
+	} : {
+		kind: "encode",
+		encoder: pickVideoEncoder(target, input.decodeHwAccel, input.hardwareEncoders === true),
+		scale,
+		...v.preset !== void 0 ? { preset: v.preset } : {},
+		...v.tune !== void 0 ? { tune: v.tune } : {},
+		...v.singleSlicePerFrame !== void 0 ? { singleSlicePerFrame: v.singleSlicePerFrame } : {},
+		...v.profile !== void 0 ? { profile: v.profile } : {},
+		...v.level !== void 0 ? { level: v.level } : {},
+		...input.pixelFormat !== void 0 ? { pixelFormat: input.pixelFormat } : {},
+		...v.fps !== void 0 ? { fps: v.fps } : {},
+		...v.gopFrames !== void 0 ? { gopFrames: v.gopFrames } : {},
+		...input.forceKeyFramesSeconds !== void 0 ? { forceKeyFramesSeconds: input.forceKeyFramesSeconds } : {},
+		...v.bf !== void 0 ? { bf: v.bf } : {},
+		...v.bitrateKbps !== void 0 ? { bitrateKbps: v.bitrateKbps } : {},
+		...input.rateControl !== void 0 ? { rateControl: input.rateControl } : {},
+		...input.bitstreamFilter !== void 0 ? { bitstreamFilter: input.bitstreamFilter } : {}
+	};
+	return {
+		logLevel: input.logLevel ?? "error",
+		decodeHwAccel: input.decodeHwAccel,
+		input: {
+			url: input.sourceUrl,
+			rtspTransport: "tcp",
+			fflags: ["+discardcorrupt"],
+			...input.profile.inputArgs?.length ? { extraArgs: input.profile.inputArgs } : {}
+		},
+		video,
+		audio: audioPlanFromEncodeProfile(input.profile.audio),
+		threadCount: input.threadCount ?? 0,
+		outputArgs: input.profile.outputArgs ?? [],
+		sink: input.sink,
+		...input.audioSidecar !== void 0 ? { audioSidecar: input.audioSidecar } : {}
+	};
+}
+//#endregion
+//#region src/ffmpeg/fmp4-box-splitter.ts
+var DEFAULT_MAX_UNIT_BYTES = 16 * 1024 * 1024;
+/** Header size for a normal box, and for one carrying a 64-bit `largesize`. */
+var BOX_HEADER_BYTES = 8;
+var LARGE_BOX_HEADER_BYTES = 16;
+var Fmp4BoxSplitter = class {
+	maxUnitBytes;
+	/** Bytes of the CURRENT unit plus any partial box after it. */
+	buffer = new Uint8Array(0);
+	/** Where the current unit starts inside {@link buffer}. */
+	unitStart = 0;
+	/** Where the box scanner has reached inside {@link buffer}. */
+	cursor = 0;
+	state = "init";
+	nextSequence = 0;
+	faultReason = null;
+	interstitial = /* @__PURE__ */ new Set();
+	constructor(options = {}) {
+		this.maxUnitBytes = options.maxUnitBytes ?? DEFAULT_MAX_UNIT_BYTES;
+	}
+	/**
+	* Non-null once the stream cannot be split. The splitter emits nothing
+	* further, so a caller polls this to kill the child rather than watching a
+	* silent stall — a fragmenter that quietly stops producing looks exactly like
+	* a camera with no motion.
+	*/
+	get fault() {
+		return this.faultReason;
+	}
+	/** Bytes currently held. The memory bound, observable rather than asserted. */
+	get pendingBytes() {
+		return this.buffer.length - this.unitStart;
+	}
+	/**
+	* Top-level box types seen BETWEEN fragments and discarded — `mfra`, `free`,
+	* a stray `sidx`. Reported rather than dropped in silence: they are legal and
+	* useless to a fragment consumer, but a type nobody expected showing up here
+	* is the first symptom of a muxer that is not writing what we think it is.
+	*/
+	get discardedInterstitialTypes() {
+		return [...this.interstitial];
+	}
+	/**
+	* Feed bytes; get back whatever units completed. Returns `[]` once faulted.
+	*/
+	push(chunk) {
+		if (this.faultReason !== null || chunk.length === 0) return [];
+		this.append(chunk);
+		if (this.pendingBytes > this.maxUnitBytes) return this.fail(`a single fMP4 unit exceeded ${this.maxUnitBytes} bytes — this stream is not fragmented`);
+		return this.drainBoxes();
+	}
+	append(chunk) {
+		if (this.buffer.length === 0) {
+			this.buffer = chunk.slice();
+			return;
+		}
+		const next = new Uint8Array(this.buffer.length + chunk.length);
+		next.set(this.buffer, 0);
+		next.set(chunk, this.buffer.length);
+		this.buffer = next;
+	}
+	/** Consume every COMPLETE top-level box now in the buffer. */
+	drainBoxes() {
+		const units = [];
+		for (;;) {
+			const header = this.readHeader();
+			if (this.faultReason !== null) return units;
+			if (header === null) break;
+			if (this.cursor + header.totalBytes > this.buffer.length) break;
+			const boxStart = this.cursor;
+			const boxEnd = boxStart + header.totalBytes;
+			this.cursor = boxEnd;
+			const unit = this.consumeBox(header.type, boxStart, boxEnd);
+			if (this.faultReason !== null) return units;
+			if (unit !== null) units.push(unit);
+		}
+		this.compact();
+		return units;
+	}
+	/**
+	* Apply one box to the state machine. Returns a unit when this box CLOSED
+	* one, `null` otherwise.
+	*/
+	consumeBox(type, boxStart, boxEnd) {
+		if (this.state === "init") {
+			if (type !== "moof") return null;
+			if (boxStart === this.unitStart) {
+				this.fail("a moof arrived before any initialisation box — there is no ftyp/moov to send");
+				return null;
+			}
+			const init = this.emit("init", this.unitStart, boxStart);
+			this.unitStart = boxStart;
+			this.state = "fragment";
+			return init;
+		}
+		if (this.state === "idle") {
+			if (type !== "moof") {
+				this.interstitial.add(type);
+				this.unitStart = boxEnd;
+				return null;
+			}
+			this.unitStart = boxStart;
+			this.state = "fragment";
+			return null;
+		}
+		if (type !== "mdat") return null;
+		const fragment = this.emit("fragment", this.unitStart, boxEnd);
+		this.unitStart = boxEnd;
+		this.state = "idle";
+		return fragment;
+	}
+	/**
+	* Parse the header at {@link cursor}, or `null` when too few bytes have
+	* arrived to know. Faults on a size the splitter cannot honour.
+	*/
+	readHeader() {
+		const available = this.buffer.length - this.cursor;
+		if (available < BOX_HEADER_BYTES) return null;
+		const view = new DataView(this.buffer.buffer, this.buffer.byteOffset, this.buffer.byteLength);
+		const size = view.getUint32(this.cursor);
+		const type = String.fromCharCode(this.buffer[this.cursor + 4] ?? 0, this.buffer[this.cursor + 5] ?? 0, this.buffer[this.cursor + 6] ?? 0, this.buffer[this.cursor + 7] ?? 0);
+		if (size === 0) {
+			this.fail(`box "${type}" declares size 0 (to EOF) — an unbounded box cannot be fragmented`);
+			return null;
+		}
+		if (size === 1) {
+			if (available < LARGE_BOX_HEADER_BYTES) return null;
+			const large = view.getBigUint64(this.cursor + BOX_HEADER_BYTES);
+			if (large > BigInt(this.maxUnitBytes)) {
+				this.fail(`box "${type}" declares ${large} bytes, over the ${this.maxUnitBytes} byte bound`);
+				return null;
+			}
+			return {
+				type,
+				totalBytes: Number(large)
+			};
+		}
+		if (size < BOX_HEADER_BYTES) {
+			this.fail(`box "${type}" declares an impossible size of ${size} bytes`);
+			return null;
+		}
+		return {
+			type,
+			totalBytes: size
+		};
+	}
+	emit(kind, start, end) {
+		const sequence = this.nextSequence;
+		this.nextSequence += 1;
+		return {
+			kind,
+			data: this.buffer.slice(start, end),
+			sequence
+		};
+	}
+	/**
+	* Drop everything already emitted or discarded. Without this the buffer is
+	* the whole stream and the process dies in hours, not minutes.
+	*/
+	compact() {
+		if (this.unitStart === 0) return;
+		this.buffer = this.buffer.slice(this.unitStart);
+		this.cursor -= this.unitStart;
+		this.unitStart = 0;
+	}
+	fail(reason) {
+		this.faultReason = reason;
+		this.buffer = new Uint8Array(0);
+		this.unitStart = 0;
+		this.cursor = 0;
+		return [];
+	}
+};
+//#endregion
+//#region src/utils/canonical-hash.ts
+/**
+* Deterministic SHA-256 hash of an arbitrary serialisable value. The
+* canonical form sorts object keys alphabetically at every depth so two
+* structurally-equal inputs with different key insertion orders produce
+* the same hash. Returns a 64-char lowercase hex digest.
+*
+* Used by export adapters (Alexa, HAP) to short-circuit re-discovery /
+* accessory-rebuild work when the upstream shape is byte-identical to
+* the last applied state — preventing user-visible "re-discovery"
+* notifications on every addon-runner respawn. Each respawn re-fires
+* `DeviceBindingsChanged` for every cap registration, which without
+* this guard would propagate redundant pushes.
+*
+* Note: this is a SYMPTOMATIC fix layered on top of the binding-change
+* subscription. The proper fix is a single "device ready" lifecycle
+* barrier so exports react only when the full cap set has landed —
+* tracked separately for post-HA-integration work.
+*/
+function canonicalHash(value) {
+	const canonical = JSON.stringify(value, replaceWithSortedKeys);
+	return createHash("sha256").update(canonical ?? "").digest("hex");
+}
+function replaceWithSortedKeys(_key, value) {
+	if (value && typeof value === "object" && !Array.isArray(value)) {
+		const obj = value;
+		const out = {};
+		for (const k of Object.keys(obj).toSorted()) out[k] = obj[k];
+		return out;
+	}
+	return value;
+}
+//#endregion
+//#region src/catalogs/sensor-active-state.ts
+/**
+* LA tabella "quale booleano di questo tipo di device conta come ALTO", e il
+* valutatore puro del suo FRONTE.
+*
+* Viveva dentro il builtin virtual-doorbell
+* (`@camstack/system` — `builtins/doorbell/trigger-engine.ts`) e i suoi
+* predicati erano privati al modulo. Il recorder ne ha bisogno per il trigger
+* `RecordingTriggers.sensorDeviceIds`: copiarla avrebbe creato la SECONDA
+* tabella, che diverge alla prima cap aggiunta e il cui sintomo — "il sensore
+* fa suonare il campanello ma non registra" — è esattamente D62. Quindi si
+* SPOSTA qui e il doorbell la ri-esporta.
+*
+* ⚠ NON è `DEVICE_STATE_READERS` (`catalogs/device-state-vocabulary.ts`), e le
+* due non vanno unificate: quella risponde a "qual è la PAROLA di stato per una
+* regola" (e include `presence`, `cover`, `alarm-panel`), questa a "qual è il
+* booleano il cui FRONTE conta". Vocabolari deliberatamente diversi.
+*/
+/**
+* Known binary / switch source caps → the boolean slice field whose
+* false→true rise counts as ACTIVE. Every entry is "fire on active".
+* Sensors whose "active" reading is not a plain boolean (presence's string
+* state, connectivity's connected flag) are deliberately excluded — a
+* reconnect is not a doorbell press, and it is not a recording either.
+*/
+var SOURCE_CAP_ACTIVE_FIELD = {
+	contact: "entryOpen",
+	binary: "on",
+	switch: "on",
+	motion: "detected",
+	flood: "flooded",
+	gas: "detected",
+	smoke: "detected",
+	"carbon-monoxide": "detected",
+	vibration: "detected",
+	tamper: "tampered"
+};
+/**
+* The same caps → the slice field carrying the ms-epoch timestamp of the
+* last transition. Every source cap MUST appear here (guarded by a spec):
+* without a transition timestamp the evaluator cannot tell a genuine rise
+* from a boot-time hydration when the FIRST slice it ever sees is already
+* active, and errs towards silence — swallowing the rise.
+*
+* These timestamps are UPSTREAM ones, not ingest ones: the Home Assistant
+* provider derives them from `state.last_changed`, so they survive our own
+* restarts and correctly read as "hours ago" for a state that has been
+* active for hours. `motion` names its rise timestamp `lastDetectedAt`.
+*/
+var SOURCE_CAP_CHANGED_AT_FIELD = {
+	contact: "lastChangedAt",
+	binary: "lastChangedAt",
+	switch: "lastChangedAt",
+	motion: "lastDetectedAt",
+	flood: "lastChangedAt",
+	gas: "lastChangedAt",
+	smoke: "lastChangedAt",
+	"carbon-monoxide": "lastChangedAt",
+	vibration: "lastChangedAt",
+	tamper: "lastChangedAt"
+};
+/** Cap names whose presence in a device's bindings qualify it as a source. */
+var SOURCE_CAPS = Object.keys(SOURCE_CAP_ACTIVE_FIELD);
+/**
+* Device `type` values (from `DeviceType`) that can host a binary/switch
+* source cap. Used by the camera's `device-multiselect` picker as the
+* CLIENT-SIDE filter, alongside `SOURCE_CAPS`.
+*
+* Why types and not caps alone: the shared picker filters
+* `deviceManager.listAll` rows client-side, and those rows carry only the
+* device's advertised `features` — NOT its registered cap list. On the live
+* cluster binary sensors and switches advertise EMPTY features (features
+* mirror only a handful of caps like `motion-trigger`), so a caps-only
+* filter matched against `features` would list nothing (the very bug this
+* replaced, which relied on the now-empty `getAllBindings`). Matching by
+* `type` is the reliable client-side signal; the union with `SOURCE_CAPS`
+* still captures any device that DOES advertise a source-cap feature.
+* `sensor` covers contact/motion/flood/gas/smoke/CO/vibration/tamper,
+* `switch` covers switches, `control` covers generic binary actuators.
+*/
+var SOURCE_DEVICE_TYPES = [
+	"sensor",
+	"switch",
+	"control"
+];
+/** True when a cap is a recognised binary/switch source. */
+function isSourceCap(capName) {
+	return Object.prototype.hasOwnProperty.call(SOURCE_CAP_ACTIVE_FIELD, capName);
+}
+/** Extract the "active" boolean a source cap's slice carries, or null when
+*  the cap is unknown or the field is missing / non-boolean. */
+function sliceActiveValue(capName, slice) {
+	const field = SOURCE_CAP_ACTIVE_FIELD[capName];
+	if (field === void 0) return null;
+	const raw = slice[field];
+	return typeof raw === "boolean" ? raw : null;
+}
+/** Ms-epoch transition timestamp a source cap's slice carries, or null when
+*  it is absent, non-numeric or the zero "never observed" sentinel. */
+function sliceChangedAt(capName, slice) {
+	const field = SOURCE_CAP_CHANGED_AT_FIELD[capName];
+	if (field === void 0) return null;
+	const raw = slice[field];
+	if (typeof raw !== "number" || !Number.isFinite(raw) || raw <= 0) return null;
+	return raw;
+}
+/**
+* How recent a source's own transition timestamp must be for a FIRST
+* sighting that is already active to count as a genuine rise rather than a
+* hydration of long-standing state.
+*/
+var DEFAULT_FIRST_SIGHTING_FRESHNESS_MS = 3e4;
+/**
+* The source-independent edge rule. The caller supplies an already extracted
+* boolean level and source timestamp; this function owns first-sighting
+* freshness and false-to-true detection.
+*/
+function evaluateSensorLevelEdge(input) {
+	const timestamp = input.changedAt;
+	const freshFloor = Math.max(input.startedAtMs, input.nowMs - input.firstSightingFreshnessMs);
+	const firstRise = input.priorLevel === void 0 && input.level && timestamp !== null && Number.isFinite(timestamp) && timestamp >= freshFloor;
+	const transitionRise = input.priorLevel === false && input.level && timestamp !== null && Number.isFinite(timestamp);
+	if ((firstRise || transitionRise) && timestamp !== null) return {
+		kind: "rise",
+		timestamp
+	};
+	return {
+		kind: "none",
+		nextPriorLevel: input.level
+	};
+}
+/**
+* IL fronte. Puro: nessun orologio proprio, nessuna memoria — il chiamante
+* porta `prior`, `nowMs` e il proprio `startedAtMs`.
+*
+* Il caso della PRIMA slice già attiva è trattato esplicitamente e vale come
+* fronte solo se il timestamp UPSTREAM della transizione è posteriore a
+* `startedAtMs` **e** entro `firstSightingFreshnessMs`. Entrambe le metà
+* servono: la sola freschezza scatterebbe su un'idratazione al boot di uno
+* stato flippato pochi secondi prima del riavvio, e il solo "dopo che abbiamo
+* iniziato" scatterebbe, su un processo di lunga vita, per una sorgente
+* adottata oggi il cui stato è cambiato ieri. Il caso ambiguo ERRA VERSO IL
+* SILENZIO e lo dichiara (`baseline-seeded-stale-active`).
+*/
+function evaluateSensorEdge(input) {
+	const value = sliceActiveValue(input.capName, input.slice);
+	if (value === null) return {
+		edge: "none",
+		value: null,
+		reason: isSourceCap(input.capName) ? "non-boolean-value" : "unknown-cap"
+	};
+	if (evaluateSensorLevelEdge({
+		level: value,
+		changedAt: sliceChangedAt(input.capName, input.slice),
+		priorLevel: input.prior,
+		startedAtMs: input.startedAtMs,
+		nowMs: input.nowMs,
+		firstSightingFreshnessMs: input.firstSightingFreshnessMs
+	}).kind === "rise") return {
+		edge: "rising",
+		value: true
+	};
+	if (input.prior === void 0) {
+		if (!value) return {
+			edge: "none",
+			value,
+			reason: "baseline-seeded-inactive"
+		};
+		return {
+			edge: "none",
+			value,
+			reason: "baseline-seeded-stale-active"
+		};
+	}
+	if (input.prior === value) return {
+		edge: "none",
+		value,
+		reason: "no-change"
+	};
+	if (!value) return {
+		edge: "none",
+		value,
+		reason: "falling-edge"
+	};
+	return {
+		edge: "none",
+		value,
+		reason: "missing-timestamp"
+	};
+}
+//#endregion
+//#region src/expression/errors.ts
+/**
+* Error types for the safe expression engine. Two distinct classes so callers
+* can tell a compile-time (grammar) failure from a runtime (evaluation)
+* failure — both are non-fatal to the host: read paths degrade to "skip link".
+*/
+/** Thrown by the tokenizer / parser. Carries a 0-based source `position` when
+*  the failure is anchored to a character (author-facing inline feedback). */
+var ExpressionParseError = class extends Error {
+	position;
+	constructor(message, position) {
+		super(message);
+		this.name = "ExpressionParseError";
+		this.position = position;
+	}
+};
+/** Thrown by the evaluator (unknown identifier, type mismatch, non-finite
+*  result, unknown builtin, step-budget exceeded). */
+var ExpressionEvalError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ExpressionEvalError";
+	}
+};
+//#endregion
+//#region src/expression/builtins.ts
+function isStatefulBuiltin(name) {
+	return name === "rose" || name === "count";
+}
+function asFiniteNumber(value, name, index) {
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new ExpressionEvalError(`${name}: argument ${index + 1} must be a finite number`);
+	return value;
+}
+function asString(value, name, index) {
+	if (typeof value !== "string") throw new ExpressionEvalError(`${name}: argument ${index + 1} must be a string`);
+	return value;
+}
+function finiteResult(value, name) {
+	if (!Number.isFinite(value)) throw new ExpressionEvalError(`${name}: produced a non-finite result`);
+	return value;
+}
+function allFiniteNumbers(args, name) {
+	return args.map((a, idx) => asFiniteNumber(a, name, idx));
+}
+function asBoolean(value, name, index) {
+	if (typeof value !== "boolean") throw new ExpressionEvalError(`${name}: argument ${index + 1} must be a boolean`);
+	return value;
+}
+/** A plain decimal (optional sign, fraction, exponent) — never hex, never `Infinity`, never a unit suffix. */
+var DECIMAL = /^[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$/;
+/**
+* `number(x)`: a finite number, or a string that IS one, as a number; every
+* other value — `''`, `'unavailable'`, a boolean, null — is `null`
+* (unavailable, never 0: D393). The one bridge from a string-valued source (an
+* HA sensor with a unit and no device_class is an `enum-sensor`) to a number.
+*/
+function toNumberOrNull(value) {
+	if (typeof value === "number") return Number.isFinite(value) ? value : null;
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	if (!DECIMAL.test(trimmed)) return null;
+	const parsed = Number(trimmed);
+	return Number.isFinite(parsed) ? parsed : null;
+}
+var DEFAULT_ROSE_DEBOUNCE_MS = 2e3;
+function evaluateRose(level, changedAt, debounceMs, call, field, env) {
+	const active = asBoolean(level, "rose", 0);
+	const timestamp = typeof changedAt === "number" && Number.isFinite(changedAt) ? changedAt : null;
+	const debounce = debounceMs === void 0 ? DEFAULT_ROSE_DEBOUNCE_MS : asFiniteNumber(debounceMs, "rose", 2);
+	if (debounce < 0) throw new ExpressionEvalError("rose: debounce must be a non-negative finite number");
+	const verdict = evaluateSensorLevelEdge({
+		level: active,
+		changedAt: timestamp,
+		priorLevel: call.priorLevel,
+		startedAtMs: env.startedAtMs,
+		nowMs: env.nowMs,
+		firstSightingFreshnessMs: DEFAULT_FIRST_SIGHTING_FRESHNESS_MS
+	});
+	call.priorLevel = verdict.kind === "rise" ? true : verdict.nextPriorLevel;
+	if (verdict.kind === "none") return env.currentOutput;
+	if (field.acceptedEdgeAt !== null && verdict.timestamp - field.acceptedEdgeAt < debounce) return env.currentOutput;
+	field.acceptedEdgeAt = verdict.timestamp;
+	return verdict.timestamp;
+}
+function evaluateCount(input, call, currentOutput) {
+	const currentCount = typeof currentOutput === "number" && Number.isFinite(currentOutput) && currentOutput >= 0 ? currentOutput : 0;
+	if (typeof input !== "number" || !Number.isFinite(input)) return currentCount;
+	if (call.highWater === null) {
+		call.highWater = input;
+		return currentCount;
+	}
+	if (input <= call.highWater) return currentCount;
+	call.highWater = input;
+	return currentCount + 1;
+}
+var INF = Number.POSITIVE_INFINITY;
+var table = {
+	min: {
+		minArgs: 1,
+		maxArgs: INF,
+		apply: (args) => finiteResult(Math.min(...allFiniteNumbers(args, "min")), "min")
+	},
+	max: {
+		minArgs: 1,
+		maxArgs: INF,
+		apply: (args) => finiteResult(Math.max(...allFiniteNumbers(args, "max")), "max")
+	},
+	abs: {
+		minArgs: 1,
+		maxArgs: 1,
+		apply: (args) => finiteResult(Math.abs(asFiniteNumber(args[0], "abs", 0)), "abs")
+	},
+	floor: {
+		minArgs: 1,
+		maxArgs: 1,
+		apply: (args) => finiteResult(Math.floor(asFiniteNumber(args[0], "floor", 0)), "floor")
+	},
+	ceil: {
+		minArgs: 1,
+		maxArgs: 1,
+		apply: (args) => finiteResult(Math.ceil(asFiniteNumber(args[0], "ceil", 0)), "ceil")
+	},
+	sqrt: {
+		minArgs: 1,
+		maxArgs: 1,
+		apply: (args) => finiteResult(Math.sqrt(asFiniteNumber(args[0], "sqrt", 0)), "sqrt")
+	},
+	round: {
+		minArgs: 1,
+		maxArgs: 2,
+		apply: (args) => {
+			const x = asFiniteNumber(args[0], "round", 0);
+			const digits = args.length > 1 ? Math.trunc(asFiniteNumber(args[1], "round", 1)) : 0;
+			if (digits < 0 || digits > 100) throw new ExpressionEvalError("round: digits must be between 0 and 100");
+			const factor = 10 ** digits;
+			return finiteResult(Math.round(x * factor) / factor, "round");
+		}
+	},
+	pow: {
+		minArgs: 2,
+		maxArgs: 2,
+		apply: (args) => finiteResult(asFiniteNumber(args[0], "pow", 0) ** asFiniteNumber(args[1], "pow", 1), "pow")
+	},
+	clamp: {
+		minArgs: 3,
+		maxArgs: 3,
+		apply: (args) => {
+			const x = asFiniteNumber(args[0], "clamp", 0);
+			const lo = asFiniteNumber(args[1], "clamp", 1);
+			const hi = asFiniteNumber(args[2], "clamp", 2);
+			if (lo > hi) throw new ExpressionEvalError("clamp: lower bound is greater than upper bound");
+			return finiteResult(Math.min(hi, Math.max(lo, x)), "clamp");
+		}
+	},
+	avg: {
+		minArgs: 1,
+		maxArgs: INF,
+		apply: (args) => {
+			const nums = allFiniteNumbers(args, "avg");
+			return finiteResult(nums.reduce((acc, v) => acc + v, 0) / nums.length, "avg");
+		}
+	},
+	sum: {
+		minArgs: 1,
+		maxArgs: INF,
+		apply: (args) => finiteResult(allFiniteNumbers(args, "sum").reduce((acc, v) => acc + v, 0), "sum")
+	},
+	coalesce: {
+		minArgs: 1,
+		maxArgs: INF,
+		apply: (args) => {
+			for (const a of args) if (a !== null) return a;
+			return null;
+		}
+	},
+	age: {
+		minArgs: 2,
+		maxArgs: 2,
+		apply: (args) => finiteResult(asFiniteNumber(args[0], "age", 0) - asFiniteNumber(args[1], "age", 1), "age")
+	},
+	convert: {
+		minArgs: 3,
+		maxArgs: 3,
+		apply: (args, hooks) => {
+			const x = asFiniteNumber(args[0], "convert", 0);
+			const from = asString(args[1], "convert", 1).trim();
+			const to = asString(args[2], "convert", 2).trim();
+			if (hooks.convert) {
+				const out = hooks.convert(x, from, to);
+				if (out === null) throw new ExpressionEvalError(`convert: cannot convert '${from}' to '${to}'`);
+				return finiteResult(out, "convert");
+			}
+			if (from === to) return x;
+			throw new ExpressionEvalError("convert: unit conversion table not installed");
+		}
+	},
+	any: {
+		minArgs: 1,
+		maxArgs: INF,
+		apply: (args) => args.map((a, i) => asBoolean(a, "any", i)).some((b) => b)
+	},
+	all: {
+		minArgs: 1,
+		maxArgs: INF,
+		apply: (args) => args.map((a, i) => asBoolean(a, "all", i)).every((b) => b)
+	},
+	within: {
+		minArgs: 2,
+		maxArgs: 2,
+		apply: (args, hooks) => {
+			const windowMs = asFiniteNumber(args[1], "within", 1);
+			if (windowMs < 0) throw new ExpressionEvalError("within: the window must not be negative");
+			const at = args[0];
+			if (at === null) return false;
+			const ts = asFiniteNumber(at, "within", 0);
+			const now = hooks.now;
+			if (now === void 0 || !Number.isFinite(now)) throw new ExpressionEvalError("within: no clock was supplied to this evaluation");
+			const inside = now - ts <= windowMs;
+			if (inside) hooks.noteDeadline?.(ts + windowMs + 1);
+			return inside;
+		}
+	},
+	number: {
+		minArgs: 1,
+		maxArgs: 1,
+		apply: (args) => toNumberOrNull(args[0])
+	},
+	latest: {
+		minArgs: 1,
+		maxArgs: INF,
+		apply: (args) => {
+			const present = args.flatMap((a, i) => a === null ? [] : [asFiniteNumber(a, "latest", i)]);
+			return present.length === 0 ? null : finiteResult(Math.max(...present), "latest");
+		}
+	},
+	rose: {
+		minArgs: 2,
+		maxArgs: 3,
+		apply: () => {
+			throw new ExpressionEvalError("rose: stateful evaluation context is required");
+		}
+	},
+	count: {
+		minArgs: 1,
+		maxArgs: 1,
+		apply: () => {
+			throw new ExpressionEvalError("count: stateful evaluation context is required");
+		}
+	}
+};
+/** Frozen, null-prototype builtin table. */
+var EXPRESSION_BUILTINS = Object.freeze(Object.assign(Object.create(null), table));
+/** The set of valid builtin names — used by the parser to reject unknown
+*  callees at parse time (immediate author feedback). */
+var EXPRESSION_BUILTIN_NAMES = new Set(Object.keys(table));
+//#endregion
+//#region src/expression/limits.ts
+/**
+* Resource-bound constants for the safe expression engine.
+*
+* Every bound is defense-in-depth: the grammar is non-Turing-complete (no
+* loops, recursion, lambdas or member access — see `ast.ts`), so evaluation is
+* O(nodeCount) by construction. These caps merely put a hard ceiling on the
+* work a single author-supplied expression can request, so a hostile or
+* accidental pathological string can never spend unbounded CPU/memory.
+*/
+/** Max source length (chars) — checked BEFORE tokenizing so a huge string is
+*  rejected without allocation. */
+var MAX_EXPRESSION_SOURCE_LENGTH = 2048;
+/** Max AST nodes — checked during parse; a deeply nested grouping that exceeds
+*  this is rejected as "expression too complex". */
+var MAX_EXPRESSION_AST_NODES = 256;
+/** Defense-in-depth walker step budget — one increment per node visit during
+*  evaluation. The grammar guarantees O(nodeCount) walks, so this can only trip
+*  on a crafted maximum-size AST. */
+var MAX_EXPRESSION_EVAL_STEPS = 4096;
+/** Max named bindings on one {@link ExpressionSource}. */
+var MAX_EXPRESSION_BINDINGS = 32;
+/** Max positional arguments to any builtin call. */
+var MAX_EXPRESSION_CALL_ARGS = 16;
+/** LRU compile-cache capacity (parsed ASTs keyed by raw source string). */
+var EXPRESSION_COMPILE_CACHE_CAPACITY = 256;
+/** A legal binding / identifier name. */
+var EXPRESSION_IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Binding names an author may NOT use: `now` is auto-injected; the literal
+*  keywords lex as values, not identifiers, so binding to them is meaningless. */
+var RESERVED_BINDING_NAMES = new Set([
+	"now",
+	"true",
+	"false",
+	"null"
+]);
+//#endregion
+//#region src/expression/tokenizer.ts
+/**
+* Tokenizer for the safe expression mini-language. Hand-rolled, single-pass,
+* zero-dependency. The grammar is deliberately boring: decimal numbers,
+* single/double-quoted strings with a tiny escape set, identifiers, the three
+* value keywords (`true`/`false`/`null`) and a fixed punctuator set. Anything
+* outside that — a bare `.`, `=`, `[`, `]`, `{`, `}`, `;`, backtick, `&`, `|` —
+* is a parse error with a source position, so member access / assignment /
+* template literals are lexically impossible.
+*/
+var KEYWORDS = new Set([
+	"true",
+	"false",
+	"null"
+]);
+function isDigit(ch) {
+	return ch >= "0" && ch <= "9";
+}
+function isIdentStart(ch) {
+	return ch >= "A" && ch <= "Z" || ch >= "a" && ch <= "z" || ch === "_";
+}
+function isIdentPart(ch) {
+	return isIdentStart(ch) || isDigit(ch);
+}
+function isWhitespace(ch) {
+	return ch === " " || ch === "	" || ch === "\n" || ch === "\r" || ch === "\f" || ch === "\v";
+}
+/** Tokenize `source` into a flat token list ending with a single `eof` token.
+*  Throws `ExpressionParseError` on any illegal character or unterminated
+*  string. */
+function tokenize(source) {
+	if (source.length > 2048) throw new ExpressionParseError(`expression too long (${source.length} > ${MAX_EXPRESSION_SOURCE_LENGTH} chars)`, 0);
+	const tokens = [];
+	let i = 0;
+	const n = source.length;
+	while (i < n) {
+		const ch = source[i];
+		if (isWhitespace(ch)) {
+			i += 1;
+			continue;
+		}
+		if (isDigit(ch)) {
+			const start = i;
+			while (i < n && isDigit(source[i])) i += 1;
+			if (i < n && source[i] === ".") {
+				if (i + 1 >= n || !isDigit(source[i + 1])) throw new ExpressionParseError("malformed number: decimal point needs a digit", i);
+				i += 1;
+				while (i < n && isDigit(source[i])) i += 1;
+			}
+			const text = source.slice(start, i);
+			const value = Number(text);
+			if (!Number.isFinite(value)) throw new ExpressionParseError(`malformed number: '${text}'`, start);
+			tokens.push({
+				type: "number",
+				value,
+				pos: start
+			});
+			continue;
+		}
+		if (ch === "'" || ch === "\"") {
+			const quote = ch;
+			const start = i;
+			i += 1;
+			let out = "";
+			let closed = false;
+			while (i < n) {
+				const c = source[i];
+				if (c === "\\") {
+					const next = i + 1 < n ? source[i + 1] : "";
+					if (next === "\\" || next === "'" || next === "\"") {
+						out += next;
+						i += 2;
+						continue;
+					}
+					throw new ExpressionParseError(`invalid string escape: '\\${next}'`, i);
+				}
+				if (c === quote) {
+					closed = true;
+					i += 1;
+					break;
+				}
+				out += c;
+				i += 1;
+			}
+			if (!closed) throw new ExpressionParseError("unterminated string literal", start);
+			tokens.push({
+				type: "string",
+				value: out,
+				pos: start
+			});
+			continue;
+		}
+		if (isIdentStart(ch)) {
+			const start = i;
+			while (i < n && isIdentPart(source[i])) i += 1;
+			const text = source.slice(start, i);
+			if (KEYWORDS.has(text)) tokens.push({
+				type: "keyword",
+				keyword: keywordOf(text),
+				pos: start
+			});
+			else tokens.push({
+				type: "identifier",
+				name: text,
+				pos: start
+			});
+			continue;
+		}
+		const two = i + 1 < n ? source.slice(i, i + 2) : "";
+		if (two === "<=" || two === ">=" || two === "==" || two === "!=" || two === "&&" || two === "||") {
+			tokens.push({
+				type: "punct",
+				punct: two,
+				pos: i
+			});
+			i += 2;
+			continue;
+		}
+		if (isSinglePunct(ch)) {
+			tokens.push({
+				type: "punct",
+				punct: ch,
+				pos: i
+			});
+			i += 1;
+			continue;
+		}
+		throw new ExpressionParseError(`unexpected character '${ch}'`, i);
+	}
+	tokens.push({
+		type: "eof",
+		pos: n
+	});
+	return tokens;
+}
+function keywordOf(text) {
+	if (text === "true") return "true";
+	if (text === "false") return "false";
+	return "null";
+}
+function isSinglePunct(ch) {
+	return ch === "(" || ch === ")" || ch === "," || ch === "?" || ch === ":" || ch === "+" || ch === "-" || ch === "*" || ch === "/" || ch === "%" || ch === "!" || ch === "<" || ch === ">";
+}
+//#endregion
+//#region src/expression/parser.ts
+/**
+* Pratt (precedence-climbing) parser for the safe expression mini-language.
+*
+* Precedence (low → high): ternary `?:` (right-assoc) → `||` → `&&` → equality
+* → relational → additive → multiplicative → unary `! -` → call / primary.
+* Calls are ONLY `IDENT '(' args? ')'` at primary position — the callee is a
+* string validated against the builtin table at parse time, so an unknown
+* function is rejected immediately (author feedback) and a persisted expression
+* that references a since-removed builtin degrades at read.
+*
+* A node counter caps total AST size (`MAX_EXPRESSION_AST_NODES`) and call
+* arity is capped (`MAX_EXPRESSION_CALL_ARGS`) — both raise `ExpressionParseError`.
+*/
+/** Binary/logical operator precedence (higher binds tighter). */
+var BINARY_PRECEDENCE = {
+	"||": 1,
+	"&&": 2,
+	"==": 3,
+	"!=": 3,
+	"<": 4,
+	"<=": 4,
+	">": 4,
+	">=": 4,
+	"+": 5,
+	"-": 5,
+	"*": 6,
+	"/": 6,
+	"%": 6
+};
+function isLogicalOp(op) {
+	return op === "&&" || op === "||";
+}
+function isBinaryOp(op) {
+	return op === "+" || op === "-" || op === "*" || op === "/" || op === "%" || op === "==" || op === "!=" || op === "<" || op === "<=" || op === ">" || op === ">=";
+}
+var Parser = class {
+	tokens;
+	pos = 0;
+	nodeCount = 0;
+	identifiers = /* @__PURE__ */ new Set();
+	callees = /* @__PURE__ */ new Set();
+	constructor(tokens) {
+		this.tokens = tokens;
+	}
+	parse() {
+		const ast = this.parseTernary();
+		const tok = this.peek();
+		if (tok.type !== "eof") throw new ExpressionParseError("unexpected trailing input", tok.pos);
+		return {
+			ast,
+			identifiers: this.identifiers,
+			callees: this.callees,
+			nodeCount: this.nodeCount
+		};
+	}
+	peek() {
+		return this.tokens[this.pos];
+	}
+	next() {
+		return this.tokens[this.pos++];
+	}
+	/** Consume a punctuator token, erroring if the next token isn't it. */
+	expectPunct(punct) {
+		const tok = this.peek();
+		if (tok.type !== "punct" || tok.punct !== punct) throw new ExpressionParseError(`expected '${punct}'`, tok.pos);
+		this.pos += 1;
+	}
+	matchPunct(punct) {
+		const tok = this.peek();
+		if (tok.type === "punct" && tok.punct === punct) {
+			this.pos += 1;
+			return true;
+		}
+		return false;
+	}
+	countNode() {
+		this.nodeCount += 1;
+		if (this.nodeCount > 256) throw new ExpressionParseError("expression too complex", this.peek().pos);
+	}
+	parseTernary() {
+		const test = this.parseBinary(1);
+		if (this.matchPunct("?")) {
+			const consequent = this.parseTernary();
+			this.expectPunct(":");
+			const alternate = this.parseTernary();
+			this.countNode();
+			return {
+				kind: "conditional",
+				test,
+				consequent,
+				alternate
+			};
+		}
+		return test;
+	}
+	parseBinary(minPrec) {
+		let left = this.parseUnary();
+		for (;;) {
+			const tok = this.peek();
+			if (tok.type !== "punct") break;
+			const prec = BINARY_PRECEDENCE[tok.punct];
+			if (prec === void 0 || prec < minPrec) break;
+			const op = tok.punct;
+			this.pos += 1;
+			const right = this.parseBinary(prec + 1);
+			this.countNode();
+			if (isLogicalOp(op)) left = {
+				kind: "logical",
+				op,
+				left,
+				right
+			};
+			else if (isBinaryOp(op)) left = {
+				kind: "binary",
+				op,
+				left,
+				right
+			};
+			else throw new ExpressionParseError(`unexpected operator '${op}'`, tok.pos);
+		}
+		return left;
+	}
+	parseUnary() {
+		const tok = this.peek();
+		if (tok.type === "punct" && (tok.punct === "!" || tok.punct === "-")) {
+			const op = tok.punct;
+			this.pos += 1;
+			const operand = this.parseUnary();
+			this.countNode();
+			return {
+				kind: "unary",
+				op,
+				operand
+			};
+		}
+		return this.parsePrimary();
+	}
+	parsePrimary() {
+		const tok = this.next();
+		switch (tok.type) {
+			case "number":
+				this.countNode();
+				return {
+					kind: "literal",
+					value: tok.value
+				};
+			case "string":
+				this.countNode();
+				return {
+					kind: "literal",
+					value: tok.value
+				};
+			case "keyword":
+				this.countNode();
+				return {
+					kind: "literal",
+					value: tok.keyword === "null" ? null : tok.keyword === "true"
+				};
+			case "identifier": {
+				const nextTok = this.peek();
+				if (nextTok.type === "punct" && nextTok.punct === "(") return this.parseCall(tok.name, tok.pos);
+				this.identifiers.add(tok.name);
+				this.countNode();
+				return {
+					kind: "identifier",
+					name: tok.name
+				};
+			}
+			case "punct":
+				if (tok.punct === "(") {
+					const inner = this.parseTernary();
+					this.expectPunct(")");
+					return inner;
+				}
+				throw new ExpressionParseError(`unexpected token '${tok.punct}'`, tok.pos);
+			case "eof": throw new ExpressionParseError("unexpected end of expression", tok.pos);
+		}
+	}
+	parseCall(callee, pos) {
+		if (!EXPRESSION_BUILTIN_NAMES.has(callee)) throw new ExpressionParseError(`unknown function '${callee}'`, pos);
+		this.expectPunct("(");
+		const args = [];
+		if (!this.matchPunct(")")) for (;;) {
+			args.push(this.parseTernary());
+			if (args.length > 16) throw new ExpressionParseError(`too many arguments to '${callee}'`, pos);
+			if (this.matchPunct(",")) continue;
+			this.expectPunct(")");
+			break;
+		}
+		this.callees.add(callee);
+		this.countNode();
+		return {
+			kind: "call",
+			callee,
+			args
+		};
+	}
+};
+/** Tokenize + parse `source` into a validated `ParsedExpression`. Throws
+*  `ExpressionParseError` on any lexical or grammatical failure. */
+function parseExpression(source) {
+	return new Parser(tokenize(source)).parse();
+}
+//#endregion
+//#region src/expression/compile.ts
+/**
+* LRU compile cache for parsed expressions (spec §2.4 "parse once … LRU keyed
+* by expr"). The cache stores BOTH successes and failures (negative caching),
+* so a corrupt persisted string costs exactly one tokenize+parse total — not
+* one per read on a hot resolve path.
+*
+* The cache is a module-level singleton: entries are pure, content-addressed
+* ASTs keyed by the raw source string, so sharing one instance across all
+* callers is safe and maximises hit rate.
+*/
+var cache = /* @__PURE__ */ new Map();
+function getCached(source) {
+	const hit = cache.get(source);
+	if (hit !== void 0) {
+		cache.delete(source);
+		cache.set(source, hit);
+		return hit;
+	}
+	let result;
+	try {
+		result = {
+			ok: true,
+			parsed: parseExpression(source)
+		};
+	} catch (err) {
+		result = {
+			ok: false,
+			error: err instanceof ExpressionParseError ? err.message : String(err)
+		};
+	}
+	cache.set(source, result);
+	if (cache.size > 256) {
+		const oldest = cache.keys().next().value;
+		if (oldest !== void 0) cache.delete(oldest);
+	}
+	return result;
+}
+/** Compile `source` to a `ParsedExpression`, throwing `ExpressionParseError`
+*  on failure. LRU/negative-cached. */
+function compileExpression(source) {
+	const result = getCached(source);
+	if (result.ok) return result.parsed;
+	throw new ExpressionParseError(result.error);
+}
+/** Compile `source`, returning a discriminated result instead of throwing.
+*  Used by read paths that must degrade rather than raise. LRU/negative-cached. */
+function compileExpressionSafe(source) {
+	return getCached(source);
+}
+//#endregion
+//#region src/expression/evaluator.ts
+/**
+* Tree-walking evaluator for the safe expression mini-language.
+*
+* SECURITY (spec §4 rule 2/5):
+*  - The scope is an `Object.create(null)` copy of ONLY the caller's own
+*    enumerable binding entries, so `name in scope` is a pure own-key check and
+*    `constructor` / `__proto__` / `toString` are plain unknown identifiers.
+*  - Performs ZERO I/O and never touches `globalThis` / `Date` / `Math`
+*    directly — the only external calls are into the frozen builtin table.
+*  - The grammar has no loops/recursion/lambdas, so a walk is O(nodeCount) by
+*    construction; the step counter is defense-in-depth for a crafted max-size
+*    AST. Nothing blocks: there are no timers, awaits or unbounded loops.
+*/
+var EMPTY_HOOKS = Object.freeze({});
+/** Build a null-prototype scope from own-enumerable binding entries. Inherited
+*  keys of the input (e.g. from a `{__proto__: {...}}` payload) are NOT copied,
+*  so nothing smuggles in via the prototype chain. */
+function createExpressionScope(bindings) {
+	const scope = Object.create(null);
+	for (const key of Object.keys(bindings)) if (Object.prototype.hasOwnProperty.call(bindings, key)) scope[key] = bindings[key];
+	return scope;
+}
+function isFiniteNumber(value) {
+	return typeof value === "number" && Number.isFinite(value);
+}
+/** JS truthiness of a primitive value. */
+function truthy(value) {
+	return Boolean(value);
+}
+function requireFinite(value, context) {
+	if (!Number.isFinite(value)) throw new ExpressionEvalError(`${context} produced a non-finite result`);
+	return value;
+}
+function step(ctx) {
+	ctx.steps += 1;
+	if (ctx.steps > ctx.maxSteps) throw new ExpressionEvalError("expression evaluation step budget exceeded");
+}
+function childPath(path, child) {
+	return `${path}/${child}`;
+}
+function evalNode(node, ctx, path) {
+	step(ctx);
+	switch (node.kind) {
+		case "literal": return node.value;
+		case "identifier":
+			if (!(node.name in ctx.scope)) throw new ExpressionEvalError(`unknown identifier: ${node.name}`);
+			return ctx.scope[node.name];
+		case "unary": return evalUnary(node.op, evalNode(node.operand, ctx, childPath(path, "operand")));
+		case "binary": return evalBinary(node.op, evalNode(node.left, ctx, childPath(path, "left")), evalNode(node.right, ctx, childPath(path, "right")));
+		case "logical": {
+			const left = evalNode(node.left, ctx, childPath(path, "left"));
+			if (node.op === "&&") return truthy(left) ? evalNode(node.right, ctx, childPath(path, "right")) : left;
+			return truthy(left) ? left : evalNode(node.right, ctx, childPath(path, "right"));
+		}
+		case "conditional": return truthy(evalNode(node.test, ctx, childPath(path, "test"))) ? evalNode(node.consequent, ctx, childPath(path, "consequent")) : evalNode(node.alternate, ctx, childPath(path, "alternate"));
+		case "call": {
+			const args = node.args.map((arg, index) => evalNode(arg, ctx, childPath(path, `arg:${index}`)));
+			return invokeCall(node.callee, args, path, ctx);
+		}
+	}
+}
+function evalUnary(op, operand) {
+	if (op === "!") return !truthy(operand);
+	if (!isFiniteNumber(operand)) throw new ExpressionEvalError("unary \"-\" requires a finite number");
+	return requireFinite(-operand, "unary \"-\"");
+}
+function evalBinary(op, left, right) {
+	switch (op) {
+		case "==": return left === right;
+		case "!=": return left !== right;
+		case "+":
+			if (typeof left === "string" && typeof right === "string") return left + right;
+			if (isFiniteNumber(left) && isFiniteNumber(right)) return requireFinite(left + right, "\"+\"");
+			throw new ExpressionEvalError("\"+\" requires two numbers or two strings");
+		case "-":
+		case "*":
+		case "/":
+		case "%":
+			if (!isFiniteNumber(left) || !isFiniteNumber(right)) throw new ExpressionEvalError(`"${op}" requires two finite numbers`);
+			return requireFinite(op === "-" ? left - right : op === "*" ? left * right : op === "/" ? left / right : left % right, `"${op}"`);
+		case "<":
+		case "<=":
+		case ">":
+		case ">=":
+			if (isFiniteNumber(left) && isFiniteNumber(right)) return op === "<" ? left < right : op === "<=" ? left <= right : op === ">" ? left > right : left >= right;
+			if (typeof left === "string" && typeof right === "string") return op === "<" ? left < right : op === "<=" ? left <= right : op === ">" ? left > right : left >= right;
+			throw new ExpressionEvalError(`"${op}" requires two numbers or two strings`);
+	}
+}
+function invokeCall(callee, args, path, ctx) {
+	if (!Object.prototype.hasOwnProperty.call(EXPRESSION_BUILTINS, callee)) throw new ExpressionEvalError(`unknown function: ${callee}`);
+	const builtin = EXPRESSION_BUILTINS[callee];
+	if (args.length < builtin.minArgs || args.length > builtin.maxArgs) throw new ExpressionEvalError(`${callee}: wrong number of arguments (${args.length})`);
+	if (isStatefulBuiltin(callee)) {
+		if (ctx.invokeStateful === void 0) throw new ExpressionEvalError(`${callee}: stateful evaluation context is required`);
+		return ctx.invokeStateful({
+			name: callee,
+			path,
+			args
+		});
+	}
+	return builtin.apply(args, ctx.hooks);
+}
+/** Evaluate an AST node against a scope. Throws `ExpressionEvalError` on any
+*  runtime failure (unknown identifier, type mismatch, non-finite result,
+*  step-budget exhaustion). */
+function evaluateAst(node, scope, opts) {
+	return evalNode(node, {
+		scope,
+		hooks: opts?.hooks ?? EMPTY_HOOKS,
+		maxSteps: opts?.maxSteps ?? 4096,
+		...opts?.invokeStateful === void 0 ? {} : { invokeStateful: opts.invokeStateful },
+		steps: 0
+	}, "root");
+}
+//#endregion
+//#region src/expression/expression-source.ts
+function createStatefulExpressionMemory() {
+	return {
+		calls: /* @__PURE__ */ new Map(),
+		acceptedEdgeAt: null
+	};
+}
+function cloneStatefulExpressionMemory(memory) {
+	return {
+		calls: new Map([...memory.calls].map(([path, call]) => [path, { ...call }])),
+		acceptedEdgeAt: memory.acceptedEdgeAt
+	};
+}
+function evaluateStatefulExpressionCall(invocation, memory, env) {
+	const existing = memory.calls.get(invocation.path);
+	switch (invocation.name) {
+		case "rose": {
+			const call = existing?.kind === "rose" ? existing : { kind: "rose" };
+			memory.calls.set(invocation.path, call);
+			const currentOutput = env.currentOutput === null || typeof env.currentOutput === "number" && Number.isFinite(env.currentOutput) ? env.currentOutput : null;
+			return evaluateRose(invocation.args[0], invocation.args[1], invocation.args[2], call, memory, {
+				currentOutput,
+				startedAtMs: env.startedAtMs,
+				nowMs: env.nowMs
+			});
+		}
+		case "count": {
+			const call = existing?.kind === "count" ? existing : {
+				kind: "count",
+				highWater: null
+			};
+			memory.calls.set(invocation.path, call);
+			return evaluateCount(invocation.args[0], call, env.currentOutput);
+		}
+	}
+}
+/** The `now` epoch-ms binding is auto-injected into every evaluation and is a
+*  reserved binding name (authors may not rebind it). */
+var EXPRESSION_INJECTED_NOW = "now";
+/**
+* Coerce an untrusted `getByPath` / mirror read to an `ExpressionValue`.
+* Non-primitive values (objects, arrays, `undefined`, functions, bigint,
+* symbol) and non-finite numbers become `undefined` so the caller can apply
+* its binding-miss policy (→ `null`). `null` itself is a valid value.
+*/
+function toExpressionValue(raw) {
+	if (raw === null) return null;
+	if (typeof raw === "string") return raw;
+	if (typeof raw === "boolean") return raw;
+	if (typeof raw === "number") return Number.isFinite(raw) ? raw : void 0;
+}
+/**
+* Author-time validation. Returns `null` when the source is valid, else a
+* human-readable error message. Checks: the expression compiles; binding count
+* is within `MAX_EXPRESSION_BINDINGS`; every binding name is a legal identifier,
+* is not reserved (`now`/keywords) and does not shadow a builtin; and every
+* FREE identifier of the AST is covered by a binding or the injected `now`.
+*/
+function validateExpressionSource(src) {
+	const names = Object.keys(src.bindings);
+	if (names.length > 32) return `too many bindings (${names.length} > 32)`;
+	for (const name of names) {
+		if (!EXPRESSION_IDENTIFIER_RE.test(name)) return `invalid binding name '${name}'`;
+		if (RESERVED_BINDING_NAMES.has(name)) return `binding name '${name}' is reserved`;
+		if (EXPRESSION_BUILTIN_NAMES.has(name)) return `binding name '${name}' shadows a builtin function`;
+	}
+	const compiled = compileExpressionSafe(src.expr);
+	if (!compiled.ok) return compiled.error;
+	const bound = new Set(names);
+	for (const id of compiled.parsed.identifiers) {
+		if (id === "now") continue;
+		if (!bound.has(id)) return `expression references unbound identifier '${id}'`;
+	}
+	return null;
+}
+/**
+* Shared read-path evaluation. Builds a null-proto scope from `bindingValues`
+* plus the injected `now` (supplied by the caller for determinism and
+* testability), compiles via the LRU, and evaluates. Stateful calls are
+* delegated through `opts.invokeStateful` with their stable AST path. Any
+* failure (parse or eval) returns `{ ok: false }` — the caller treats that as
+* "skip this derivation", never as a throw that takes the pass down.
+*/
+function evaluateExpressionSource(expr, bindingValues, now, opts) {
+	const compiled = compileExpressionSafe(expr);
+	if (!compiled.ok) return {
+		ok: false,
+		error: compiled.error
+	};
+	const scope = createExpressionScope({
+		...bindingValues,
+		["now"]: now
+	});
+	const hooks = {
+		...opts?.hooks,
+		now
+	};
+	try {
+		return {
+			ok: true,
+			value: evaluateAst(compiled.parsed.ast, scope, {
+				...opts,
+				hooks
+			})
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			error: err instanceof ExpressionEvalError ? err.message : String(err)
+		};
+	}
+}
+//#endregion
+//#region src/composition/composition.ts
+/**
+* A COMPOSITION: a device assembled from other devices' state (D659).
+*
+* The data half of the composed-devices spec §1. A composition is stored inside
+* a core block (`CoreBlock.source.kind === 'composition'`) and run by the shared
+* `composer` runner. It names a TARGET and, for each capability of the target, a
+* FIELD MAP: every state field has exactly one source.
+*
+* Sources are keyed by `(addonId, stableId)`, NEVER by numeric device id. A
+* resync reissues numeric ids, and a composition that stored them would be
+* orphaned by the first re-adoption (the linked-devices lesson). A `stableId` is
+* unique only within its owning addon, so the owner travels with it.
+*
+* Later slices EXTEND these unions and do not reshape them. The variants a later
+* slice implements are already in the wire shape, and `validateComposition`
+* refuses them BY NAME until then:
+*   feature `passthrough` → slice 3 · `commands` (`forward`) → slice 3 ·
+*   source `code` → slice 4. Target `existing` (customize a device) is slice 2 (D663).
+*/
+/** The owner of every composed device: the `composer` builtin. */
+var COMPOSER_ADDON_ID = "composer";
+/**
+* The stored name of a block that customizes an EXISTING device starts with this
+* (`customizationBlockName`, `@camstack/types/node`). Never parsed to tell a
+* customization apart: `composition.target.kind === 'existing'` says that (D663).
+*/
+var CUSTOMIZATION_BLOCK_NAME_PREFIX = "customize:";
+/** A composed device's stableId is this prefix plus the block id. */
+var COMPOSED_DEVICE_STABLE_ID_PREFIX = "composed-";
+/** A device with more capabilities than this is two devices. */
+var MAX_COMPOSITION_FEATURES = 16;
+var MAX_COMPOSITION_FIELDS_PER_FEATURE = 32;
+/** Longest snippet a `code` source may carry (slice 4). */
+var MAX_COMPOSITION_CODE_LENGTH = 2e4;
+var CompositionSourceRefSchema = z.object({
+	/** The owning addon; `stableId` is unique only within it. */
+	addonId: z.string().min(1),
+	stableId: z.string().min(1)
+});
+/** One field of one capability of one source device. */
+var CompositionFieldReadSchema = z.object({
+	source: CompositionSourceRefSchema,
+	cap: z.string().min(1),
+	/** Dotted path into the source cap's runtime-state slice. */
+	fieldPath: z.string().min(1)
+});
+/** `from`: copy one source field verbatim. It is also an expression's `from` binding. */
+var CompositionFromSourceSchema = CompositionFieldReadSchema.extend({ kind: z.literal("from") });
+/** A constant binding. No device is read. */
+var CompositionLiteralBindingSchema = z.object({
+	kind: z.literal("literal"),
+	value: z.union([
+		z.string(),
+		z.number(),
+		z.boolean(),
+		z.null()
+	])
+});
+var CompositionBindingSchema = z.discriminatedUnion("kind", [CompositionFromSourceSchema, CompositionLiteralBindingSchema]);
+/**
+* `expression`: a formula over named bindings, in the salvaged expression
+* engine. Validated at parse by the SAME function every other consumer runs,
+* so the editor and the store cannot disagree.
+*/
+var CompositionExpressionSourceSchema = z.object({
+	kind: z.literal("expression"),
+	expr: z.string().min(1).max(MAX_EXPRESSION_SOURCE_LENGTH),
+	bindings: z.record(z.string().regex(EXPRESSION_IDENTIFIER_RE), CompositionBindingSchema)
+}).superRefine((src, ctx) => {
+	const err = validateExpressionSource(src);
+	if (err !== null) ctx.addIssue({
+		code: "custom",
+		message: err,
+		path: ["expr"]
+	});
+});
+/** `code`: RESERVED for slice 4 (own runner, one-way eject). */
+var CompositionCodeSourceSchema = z.object({
+	kind: z.literal("code"),
+	code: z.string().min(1).max(MAX_COMPOSITION_CODE_LENGTH)
+});
+var CompositionFieldSourceSchema = z.discriminatedUnion("kind", [
+	CompositionFromSourceSchema,
+	CompositionExpressionSourceSchema,
+	CompositionCodeSourceSchema
+]);
+/** `forward`: RESERVED for slice 3. Argument mapping arrives there as an additive optional `args`. */
+var CompositionForwardCommandSchema = z.object({
+	kind: z.literal("forward"),
+	source: CompositionSourceRefSchema,
+	cap: z.string().min(1),
+	method: z.string().min(1)
+});
+var CompositionCommandTargetSchema = z.discriminatedUnion("kind", [CompositionForwardCommandSchema, CompositionCodeSourceSchema]);
+/** An item key inside an item-array cap (`consumables.items[<key>]`). */
+var COMPOSITION_ITEM_KEY_RE = /^[a-z0-9][a-z0-9-]{0,47}$/;
+var MAX_COMPOSITION_ITEMS = 16;
+/** The item-array path of every item-array cap that exists (`consumables.items`). */
+var COMPOSITION_ITEM_ARRAY_PATH = "items";
+/**
+* One item of an item-array cap (D663), addressed through the cap's
+* `status.itemArray` descriptor. `fields` are paths INSIDE the item, nested
+* allowed (`remaining.value`); the key and label come from the entry itself.
+*/
+var CompositionItemEntrySchema = z.object({
+	label: z.string().min(1).max(80),
+	fields: z.record(z.string().min(1), CompositionFieldSourceSchema)
+});
+var CompositionFieldsFeatureSchema = z.object({
+	kind: z.literal("fields"),
+	cap: z.string().min(1),
+	enabled: z.boolean().optional(),
+	fields: z.record(z.string().min(1), CompositionFieldSourceSchema).refine((fields) => Object.keys(fields).length <= 32, { message: `at most 32 fields per capability` }),
+	/**
+	* Items of the cap's item array, keyed by item key (D663). Naming `items`
+	* owns the WHOLE array field: the composed value holds exactly these items.
+	*/
+	items: z.record(z.string().regex(COMPOSITION_ITEM_KEY_RE), CompositionItemEntrySchema).refine((items) => Object.keys(items).length <= 16, { message: `at most 16 items` }).optional(),
+	/** RESERVED for slice 3; refused by the validator when non-empty. */
+	commands: z.record(z.string().min(1), CompositionCommandTargetSchema).optional()
+});
+/** RESERVED for slice 3: a media / data-plane cap, whole, from one source. */
+var CompositionPassthroughFeatureSchema = z.object({
+	kind: z.literal("passthrough"),
+	cap: z.string().min(1),
+	enabled: z.boolean().optional(),
+	source: CompositionSourceRefSchema
+});
+var CompositionFeatureSchema = z.discriminatedUnion("kind", [CompositionFieldsFeatureSchema, CompositionPassthroughFeatureSchema]);
+/** Only an explicit `false` disables a feature; omitted preserves the existing wire default. */
+function compositionFeatureEnabled(feature) {
+	return feature.enabled !== false;
+}
+/**
+* A NEW device. It has no `name` of its own: the block's name IS the device's
+* name (2026-08-08). A second copy here would be a second writer of one string (D62).
+*/
+var CompositionNewTargetSchema = z.object({
+	kind: z.literal("new"),
+	type: z.enum(DeviceType),
+	role: z.enum(DeviceRole).optional()
+});
+/** Customize an EXISTING device: each feature adds a capability or replaces fields of a native one (D663). */
+var CompositionExistingTargetSchema = z.object({
+	kind: z.literal("existing"),
+	device: CompositionSourceRefSchema
+});
+var CompositionTargetSchema = z.discriminatedUnion("kind", [CompositionNewTargetSchema, CompositionExistingTargetSchema]);
+var CompositionSchema = z.object({
+	target: CompositionTargetSchema,
+	features: z.array(CompositionFeatureSchema).min(1).max(16)
+}).superRefine((composition, ctx) => {
+	const seen = /* @__PURE__ */ new Set();
+	composition.features.forEach((feature, index) => {
+		if (seen.has(feature.cap)) ctx.addIssue({
+			code: "custom",
+			message: `capability \`${feature.cap}\` is composed twice — one feature per capability`,
+			path: [
+				"features",
+				index,
+				"cap"
+			]
+		});
+		seen.add(feature.cap);
+	});
+});
+function compositionSourceKey(ref) {
+	return `${ref.addonId}/${ref.stableId}`;
+}
+function compositionSliceKey(ref, cap) {
+	return `${compositionSourceKey(ref)}#${cap}`;
+}
+function compositionReadKey(read) {
+	return `${compositionSliceKey(read.source, read.cap)}.${read.fieldPath}`;
+}
+function composedDeviceStableId(blockId) {
+	return `${COMPOSED_DEVICE_STABLE_ID_PREFIX}${blockId}`;
+}
+function composedDeviceRef(blockId) {
+	return {
+		addonId: COMPOSER_ADDON_ID,
+		stableId: composedDeviceStableId(blockId)
+	};
+}
+/** Every device field a source reads: `from` is one read, an expression is its `from` bindings. */
+function fieldReads(source) {
+	switch (source.kind) {
+		case "from": return [{
+			source: source.source,
+			cap: source.cap,
+			fieldPath: source.fieldPath
+		}];
+		case "expression": return Object.values(source.bindings).flatMap((binding) => binding.kind === "from" ? [{
+			source: binding.source,
+			cap: binding.cap,
+			fieldPath: binding.fieldPath
+		}] : []);
+		case "code": return [];
+	}
+}
+/** The ONE spelling of an item leaf as a field path: `items[desiccant].remaining.value`. */
+function compositionItemFieldPath(arrayPath, key, path) {
+	return `${arrayPath}[${key}].${path}`;
+}
+/**
+* Every written field of a feature, item leaves under their bracketed path.
+* `arrayPath` is `'items'` for every item-array cap that exists
+* (`consumables.cap.ts`); the graph has no cap lookup, so the default stands
+* and `planItems` asserts it agrees with the cap's descriptor.
+*/
+function featureFieldEntries(feature, arrayPath = COMPOSITION_ITEM_ARRAY_PATH) {
+	return [...Object.entries(feature.fields).map(([fieldPath, source]) => ({
+		fieldPath,
+		source
+	})), ...Object.entries(feature.items ?? {}).flatMap(([key, item]) => Object.entries(item.fields).map(([path, source]) => ({
+		fieldPath: compositionItemFieldPath(arrayPath, key, path),
+		source
+	})))];
+}
+function featureSources(feature) {
+	return featureFieldEntries(feature).map((e) => e.source);
+}
+//#endregion
+export { MAX_EXPRESSION_AST_NODES as $, compositionFeatureEnabled as A, invocationFromEncodeProfile as At, createStatefulExpressionMemory as B, CompositionTargetSchema as C, Fmp4BoxSplitter as Ct, MAX_COMPOSITION_ITEMS as D, buildFfmpegArgs as Dt, MAX_COMPOSITION_FIELDS_PER_FEATURE as E, buildAudioArgs as Et, featureFieldEntries as F, createExpressionScope as G, evaluateStatefulExpressionCall as H, featureSources as I, compileExpressionSafe as J, evaluateAst as K, fieldReads as L, compositionReadKey as M, logBannerArgs as Mt, compositionSliceKey as N, pickVideoEncoder as Nt, composedDeviceRef as O, buildInputArgs as Ot, compositionSourceKey as P, resolveStreamMaps as Pt, EXPRESSION_IDENTIFIER_RE as Q, EXPRESSION_INJECTED_NOW as R, CompositionSourceRefSchema as S, canonicalHash as St, MAX_COMPOSITION_FEATURES as T, audioPlanFromEncodeProfile as Tt, toExpressionValue as U, evaluateExpressionSource as V, validateExpressionSource as W, tokenize as X, parseExpression as Y, EXPRESSION_COMPILE_CACHE_CAPACITY as Z, CompositionItemEntrySchema as _, evaluateSensorEdge as _t, CUSTOMIZATION_BLOCK_NAME_PREFIX as a, EXPRESSION_BUILTINS as at, CompositionPassthroughFeatureSchema as b, sliceActiveValue as bt, CompositionCommandTargetSchema as c, evaluateRose as ct, CompositionFeatureSchema as d, ExpressionParseError as dt, MAX_EXPRESSION_BINDINGS as et, CompositionFieldReadSchema as f, DEFAULT_FIRST_SIGHTING_FRESHNESS_MS as ft, CompositionFromSourceSchema as g, SOURCE_DEVICE_TYPES as gt, CompositionForwardCommandSchema as h, SOURCE_CAP_CHANGED_AT_FIELD as ht, COMPOSITION_ITEM_KEY_RE as i, RESERVED_BINDING_NAMES as it, compositionItemFieldPath as j, isSoftwareDecode as jt, composedDeviceStableId as k, buildVideoArgs as kt, CompositionExistingTargetSchema as l, isStatefulBuiltin as lt, CompositionFieldsFeatureSchema as m, SOURCE_CAP_ACTIVE_FIELD as mt, COMPOSER_ADDON_ID as n, MAX_EXPRESSION_EVAL_STEPS as nt, CompositionBindingSchema as o, EXPRESSION_BUILTIN_NAMES as ot, CompositionFieldSourceSchema as p, SOURCE_CAPS as pt, compileExpression as q, COMPOSITION_ITEM_ARRAY_PATH as r, MAX_EXPRESSION_SOURCE_LENGTH as rt, CompositionCodeSourceSchema as s, evaluateCount as st, COMPOSED_DEVICE_STABLE_ID_PREFIX as t, MAX_EXPRESSION_CALL_ARGS as tt, CompositionExpressionSourceSchema as u, ExpressionEvalError as ut, CompositionLiteralBindingSchema as v, evaluateSensorLevelEdge as vt, MAX_COMPOSITION_CODE_LENGTH as w, AUDIO_PRESETS as wt, CompositionSchema as x, sliceChangedAt as xt, CompositionNewTargetSchema as y, isSourceCap as yt, cloneStatefulExpressionMemory as z };