@snoai/memory 0.0.0-stage → 1.0.0

package/dist/rem-trigger-BTxkcjgT.js

@@ -0,0 +1,729 @@
+import { $ as appendAuditEntryStrict, r as enumerateRemCandidateScopes, tt as getAuditPath } from "./rem-batch-executor-Cbm5gfSe.js";
+import { f as getRemDiscoveryPath, l as REM_SIDECAR_TOKEN_HEADER, o as REM_RUN_PATH, r as REM_CORRELATION_ID_HEADER, s as REM_SIDECAR_HOST } from "./config-tSrvLXgV.js";
+import { createLogger } from "@snoai/utils/logger";
+import path from "node:path";
+import { z } from "zod";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import { withLogContext as withLogContext$1 } from "@snoai/utils/log-context";
+//#region src/contract/error.ts
+const DEGRADED_REASONS = [
+	"sidecar-unreachable",
+	"sidecar-unresponsive",
+	"principal-mismatch",
+	"store-mismatch",
+	"no-agent-endpoint",
+	"invalid-input",
+	"timeout",
+	"storage-unavailable",
+	"engine-failed"
+];
+var ContractError = class extends Error {
+	reason;
+	degraded = true;
+	constructor(reason, message = reason) {
+		super(message);
+		this.reason = reason;
+		this.name = "ContractError";
+	}
+};
+//#endregion
+//#region src/sidecar/rem-trigger-state.ts
+/** @file rem-trigger-state.ts
+* @purpose Persists the automatic REM scheduler's strict per-scope state.
+* @boundary One atomically replaced JSON file under the sno-station-mem state directory.
+*/
+const remTriggerScopeStateSchema = z.object({
+	last_pass_at: z.string().datetime(),
+	schedule_zone: z.string().min(1).refine(isValidScheduleZone, "invalid IANA time zone"),
+	last_covered_count: z.number().int().nonnegative(),
+	last_volume_pass_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/u).nullable(),
+	missed_window: z.object({
+		due_at: z.string().datetime(),
+		trigger: z.enum(["daily", "volume"]),
+		recorded_at: z.string().datetime()
+	}).strict().nullable().default(null),
+	attempts: z.object({
+		identity: z.string().min(1).nullable(),
+		count: z.number().int().min(0).max(3)
+	}).strict()
+}).strict();
+const remTriggerStateDocumentSchema = z.object({
+	version: z.literal(1),
+	scopes: z.record(z.string().min(1), remTriggerScopeStateSchema)
+}).strict();
+var RemTriggerStateError = class extends Error {
+	statePath;
+	constructor(statePath, cause) {
+		super(`REM trigger state at ${statePath} is invalid or unreadable: ${errorMessage$1(cause)}`, { cause: cause instanceof Error ? cause : void 0 });
+		this.statePath = statePath;
+		this.name = "RemTriggerStateError";
+	}
+};
+function remTriggerStatePath(stateDir) {
+	return path.join(stateDir, "rem-trigger-state.json");
+}
+async function loadRemTriggerState(stateDir) {
+	const statePath = remTriggerStatePath(stateDir);
+	let raw;
+	try {
+		raw = await readFile(statePath, "utf8");
+	} catch (error) {
+		if (isNodeError$1(error) && error.code === "ENOENT") return {
+			version: 1,
+			scopes: {}
+		};
+		throw new RemTriggerStateError(statePath, error);
+	}
+	try {
+		return remTriggerStateDocumentSchema.parse(JSON.parse(raw));
+	} catch (error) {
+		throw new RemTriggerStateError(statePath, error);
+	}
+}
+function ensureRemTriggerScope(state, input) {
+	const existing = state.scopes[input.scope];
+	if (existing !== void 0) return {
+		state,
+		scopeState: existing,
+		initialized: false
+	};
+	if (input.scope.trim().length === 0) throw new Error("REM trigger scope is required");
+	if (!Number.isInteger(input.candidateCount) || input.candidateCount < 0) throw new Error("REM trigger candidate count must be a nonnegative integer");
+	if (Number.isNaN(input.now.getTime())) throw new Error("REM trigger initialization time is invalid");
+	const scheduleZone = (input.resolveScheduleZone ?? resolveHostScheduleZone)();
+	if (!isValidScheduleZone(scheduleZone)) throw new Error(`invalid REM schedule zone: ${scheduleZone}`);
+	const scopeState = {
+		last_pass_at: input.now.toISOString(),
+		schedule_zone: scheduleZone,
+		last_covered_count: input.candidateCount,
+		last_volume_pass_date: null,
+		missed_window: null,
+		attempts: {
+			identity: null,
+			count: 0
+		}
+	};
+	return {
+		state: {
+			version: 1,
+			scopes: {
+				...state.scopes,
+				[input.scope]: scopeState
+			}
+		},
+		scopeState,
+		initialized: true
+	};
+}
+async function writeRemTriggerStateAtomic$1(stateDir, state) {
+	const validated = remTriggerStateDocumentSchema.parse(state);
+	await mkdir(stateDir, {
+		recursive: true,
+		mode: 448
+	});
+	const statePath = remTriggerStatePath(stateDir);
+	const temporaryPath = `${statePath}.${process.pid}.${randomUUID()}.tmp`;
+	try {
+		const handle = await open(temporaryPath, "wx", 384);
+		try {
+			await handle.writeFile(JSON.stringify(validated), "utf8");
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
+		await rename(temporaryPath, statePath);
+		await syncDirectory(stateDir);
+	} catch (error) {
+		await rm(temporaryPath, { force: true });
+		throw error;
+	}
+}
+function resolveHostScheduleZone() {
+	return Intl.DateTimeFormat().resolvedOptions().timeZone;
+}
+function isValidScheduleZone(value) {
+	if (value.trim().length === 0) return false;
+	try {
+		new Intl.DateTimeFormat("en-US", { timeZone: value }).format(0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function syncDirectory(directory) {
+	if (process.platform === "win32") return;
+	const handle = await open(directory, "r");
+	try {
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+}
+function isNodeError$1(error) {
+	return error instanceof Error && "code" in error;
+}
+function errorMessage$1(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+const REM_COMPLETION_AUDIT_TAIL_BYTES = 16777216;
+const log = createLogger("sno-station-mem:rem-trigger");
+function remNeedsHost(mode, modelCalls) {
+	return Object.keys(modelCalls).some((id) => id.startsWith("REM") && modelCalls[id][mode] === "host");
+}
+const discoverySchema = z.object({
+	pid: z.number().int().positive(),
+	port: z.number().int().min(1).max(65535),
+	token: z.string().min(1)
+}).strict();
+const idleEvaluations = /* @__PURE__ */ new Map();
+async function evaluateRemAutomaticTriggers(input) {
+	const now = input.now ?? /* @__PURE__ */ new Date();
+	if (!Number.isInteger(input.volumeThreshold ?? 100) || (input.volumeThreshold ?? 100) < 1) throw new Error("REM volume threshold must be a positive integer");
+	const auditStateDir = input.auditStateDir ?? input.stateDir;
+	if (Number.isNaN(now.getTime())) throw new Error("REM trigger evaluation time is invalid");
+	if (input.requestedOperations.length === 0) {
+		await recordDecision(auditStateDir, void 0, "skipped", {
+			row: "automatic-trigger-skipped",
+			reason: "product-mode-disabled"
+		});
+		return {
+			evaluations: 0,
+			dispatches: 0
+		};
+	}
+	if (input.mode && remNeedsHost(input.mode, input.modelCalls) && !input.hasConnectedHost?.()) {
+		await recordDecision(auditStateDir, void 0, "skipped", {
+			row: "automatic-trigger-skipped",
+			reason: "skipped: no host model connected"
+		});
+		return {
+			evaluations: 0,
+			dispatches: 0
+		};
+	}
+	let scopes;
+	try {
+		scopes = enumerateRemCandidateScopes(input.database);
+	} catch (error) {
+		await recordDecision(auditStateDir, void 0, "error", {
+			row: "enumeration-failed",
+			cause: errorMessage(error)
+		});
+		return {
+			evaluations: 1,
+			dispatches: 0
+		};
+	}
+	if (scopes.length === 0) {
+		await recordDecision(auditStateDir, void 0, "ok", { row: "no-scopes" });
+		return {
+			evaluations: 1,
+			dispatches: 0
+		};
+	}
+	let state;
+	let lostState = false;
+	try {
+		state = await loadRemTriggerState(input.stateDir);
+	} catch (error) {
+		for (const { scope, candidateCount } of scopes) {
+			const consecutiveIdle = (idleEvaluations.get(scope) ?? 0) + 1;
+			idleEvaluations.set(scope, consecutiveIdle);
+			await recordDecision(auditStateDir, scope, "error", {
+				row: "state-unreadable",
+				candidate_count: candidateCount,
+				cause: errorMessage(error),
+				consecutive_idle: consecutiveIdle
+			});
+		}
+		log.error("REM trigger state unavailable; continuing with due work", { cause: errorMessage(error) }, {
+			event_name: "memory.rem.trigger.state.unavailable",
+			file: "packages/memory/src/sidecar/rem-trigger.ts",
+			function: "evaluateRemAutomaticTriggers",
+			site_id: "memory.rem.trigger.state.unavailable"
+		});
+		state = {
+			version: 1,
+			scopes: {}
+		};
+		lostState = true;
+	}
+	state = await applyCompletedBaselines(auditStateDir, input.stateDir, state);
+	let dispatches = 0;
+	for (const { scope, candidateCount } of scopes) try {
+		const ensured = ensureRemTriggerScope(state, {
+			scope,
+			now: lostState ? previousDay(now) : now,
+			candidateCount,
+			resolveScheduleZone: input.resolveScheduleZone
+		});
+		state = ensured.state;
+		if (ensured.initialized) await writeRemTriggerStateAtomic(input.stateDir, state);
+		const scopeResult = await evaluateScope(input, auditStateDir, state, scope, candidateCount, now);
+		state = scopeResult.state;
+		dispatches += scopeResult.dispatched ? 1 : 0;
+	} catch (error) {
+		log.error("REM automatic scope evaluation failed", {
+			scope,
+			error
+		}, {
+			event_name: "sno_station_mem.rem-trigger.rem.automatic.scope.evaluation.failed",
+			file: "packages/memory/src/sidecar/rem-trigger.ts",
+			function: "evaluateRemAutomaticTriggers",
+			site_id: "rem-trigger.evaluateRemAutomaticTriggers.1d59077a5c"
+		});
+		try {
+			await recordDecision(auditStateDir, scope, "error", {
+				row: "scope-evaluation-failed",
+				cause: errorMessage(error)
+			});
+		} catch (auditError) {
+			log.warn("REM automatic scope failure audit failed", {
+				scope,
+				error: auditError
+			}, {
+				event_name: "sno_station_mem.rem-trigger.rem.automatic.scope.failure.audit.failed",
+				file: "packages/memory/src/sidecar/rem-trigger.ts",
+				function: "evaluateRemAutomaticTriggers",
+				site_id: "rem-trigger.evaluateRemAutomaticTriggers.ebe1cdd204"
+			});
+		}
+		try {
+			state = await loadRemTriggerState(input.stateDir);
+		} catch (stateError) {
+			log.warn("REM automatic trigger state reload failed", {
+				scope,
+				error: stateError
+			}, {
+				event_name: "sno_station_mem.rem-trigger.rem.automatic.trigger.state.reload.failed",
+				file: "packages/memory/src/sidecar/rem-trigger.ts",
+				function: "evaluateRemAutomaticTriggers",
+				site_id: "rem-trigger.evaluateRemAutomaticTriggers.46669e66ff"
+			});
+			break;
+		}
+	}
+	return {
+		evaluations: scopes.length,
+		dispatches
+	};
+}
+function previousDay(now) {
+	const day = new Date(now);
+	day.setUTCDate(day.getUTCDate() - 1);
+	return day;
+}
+async function writeRemTriggerStateAtomic(stateDir, state) {
+	try {
+		await writeRemTriggerStateAtomic$1(stateDir, state);
+	} catch (error) {
+		log.error("REM trigger state write failed; continuing dispatch", { cause: errorMessage(error) }, {
+			event_name: "memory.rem.trigger.state.write.failed",
+			file: "packages/memory/src/sidecar/rem-trigger.ts",
+			function: "evaluateRemAutomaticTriggers",
+			site_id: "memory.rem.trigger.state.write.failed"
+		});
+	}
+}
+async function evaluateScope(input, auditStateDir, state, scope, candidateCount, now) {
+	const scopeState = requiredScopeState(state, scope);
+	const zone = scopeState.schedule_zone;
+	const nextDue = nextDailyDue(scopeState);
+	const localDate = localDateAt(now, zone);
+	const growth = candidateCount - scopeState.last_covered_count;
+	const scheduledDue = computeRemDailyDue(scopeState.last_pass_at, zone);
+	const pendingVolumeToday = scopeState.attempts.identity === remAutomaticCorrelationId("volume", scope, localDate);
+	const pendingDailyToday = localDateAt(scheduledDue, zone) === localDate && scopeState.attempts.identity === remAutomaticCorrelationId("daily", scope, scheduledDue.toISOString());
+	const dailyDue = now.getTime() >= nextDue.getTime() && !pendingVolumeToday;
+	const volumeDue = growth >= (input.volumeThreshold ?? 100) && scopeState.last_volume_pass_date !== localDate && !pendingDailyToday;
+	if (!dailyDue && !volumeDue) {
+		const consecutiveIdle = (idleEvaluations.get(scope) ?? 0) + 1;
+		idleEvaluations.set(scope, consecutiveIdle);
+		await recordDecision(auditStateDir, scope, "ok", {
+			row: "waiting-for-schedule",
+			next_due: nextDue.toISOString(),
+			milliseconds_until_due: Math.max(0, nextDue.getTime() - now.getTime()),
+			growth: growthDetails(candidateCount, scopeState.last_covered_count, input.volumeThreshold ?? 100),
+			consecutive_idle: consecutiveIdle
+		});
+		return {
+			state,
+			dispatched: false
+		};
+	}
+	const trigger = dailyDue ? "daily" : "volume";
+	if (input.tickEnabled === false) {
+		const nextState = replaceScopeState(state, scope, {
+			...scopeState,
+			missed_window: {
+				due_at: dailyDue ? nextDue.toISOString() : now.toISOString(),
+				trigger,
+				recorded_at: now.toISOString()
+			}
+		});
+		await writeRemTriggerStateAtomic(input.stateDir, nextState);
+		return {
+			state: nextState,
+			dispatched: false
+		};
+	}
+	const correlationId = remAutomaticCorrelationId(trigger, scope, trigger === "daily" ? nextDue.toISOString() : localDate);
+	const priorAttempts = scopeState.attempts.identity === correlationId ? scopeState.attempts.count : 0;
+	await recordDecision(auditStateDir, scope, "ok", {
+		row: "dispatch",
+		trigger,
+		next_due: nextDue.toISOString(),
+		pass_at: now.toISOString(),
+		local_date: localDate,
+		growth: growthDetails(candidateCount, scopeState.last_covered_count, input.volumeThreshold ?? 100),
+		correlation_id: correlationId,
+		consecutive_idle: 0
+	});
+	idleEvaluations.set(scope, 0);
+	let nextState = replaceScopeState(state, scope, {
+		...scopeState,
+		attempts: {
+			identity: correlationId,
+			count: Math.min(priorAttempts + 1, 3)
+		}
+	});
+	await writeRemTriggerStateAtomic(input.stateDir, nextState);
+	let cause;
+	try {
+		await dispatchRemWave(input, scope, correlationId);
+	} catch (error) {
+		cause = errorMessage(error);
+	}
+	if (cause === void 0) {
+		nextState = replaceScopeState(nextState, scope, {
+			...requiredScopeState(nextState, scope),
+			missed_window: null
+		});
+		await writeRemTriggerStateAtomic(input.stateDir, nextState);
+		return {
+			state: nextState,
+			dispatched: true
+		};
+	}
+	await appendAuditEntryStrict(auditStateDir, {
+		event: "rem_failed",
+		resultStatus: "error",
+		scope,
+		details: {
+			outcome: "dispatch-failed",
+			cause,
+			correlation_id: correlationId,
+			source: "gateway-trigger"
+		}
+	});
+	return {
+		state: nextState,
+		dispatched: true
+	};
+}
+async function dispatchRemWave(input, scope, correlationId) {
+	const started = performance.now();
+	const discovery = discoverySchema.parse(JSON.parse(await readFile(input.discoveryPath ?? getRemDiscoveryPath(), "utf8")));
+	const response = await fetch(`http://${REM_SIDECAR_HOST}:${discovery.port}${REM_RUN_PATH}`, {
+		method: "POST",
+		headers: {
+			"content-type": "application/json",
+			[REM_SIDECAR_TOKEN_HEADER]: discovery.token,
+			[REM_CORRELATION_ID_HEADER]: correlationId
+		},
+		body: JSON.stringify({
+			types: input.requestedOperations,
+			scope
+		}),
+		signal: AbortSignal.timeout(input.dispatchTimeoutMs ?? 1e4)
+	});
+	if (response.status !== 202) throw new Error(`REM sidecar returned HTTP ${response.status}`);
+	const body = z.object({
+		job_id: z.string().min(1),
+		waveId: z.string().min(1)
+	}).passthrough().parse(await response.json());
+	if (body.job_id !== body.waveId) throw new Error("REM sidecar confirmation identities disagree");
+	withLogContext$1({
+		operation_id: body.job_id,
+		job_id: body.job_id,
+		session_reference: scope,
+		external_reference: correlationId
+	}, () => {
+		log.info("REM dispatch accepted", {
+			outcome: "success",
+			job_id: body.job_id,
+			status: response.status,
+			duration_ms: performance.now() - started
+		}, {
+			event_name: "sidecar.trigger.dispatch.accepted",
+			file: "packages/memory/src/sidecar/rem-trigger.ts",
+			function: "dispatchRemWave",
+			site_id: "sidecar.trigger.dispatch.accepted"
+		});
+	});
+}
+async function applyCompletedBaselines(auditStateDir, triggerStateDir, state) {
+	let content;
+	try {
+		content = await readAuditTail(getAuditPath(auditStateDir));
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return state;
+		log.warn("REM completion audit could not be read", {
+			error,
+			outcome: "skipped",
+			reason_code: "audit_read_failed"
+		}, {
+			event_name: "sidecar.trigger.audit_read.failed",
+			file: "packages/memory/src/sidecar/rem-trigger.ts",
+			function: "applyCompletedBaselines",
+			site_id: "sidecar.trigger.audit_read.failed"
+		});
+		return state;
+	}
+	const dispatched = /* @__PURE__ */ new Map();
+	let nextState = state;
+	let malformedCount = 0;
+	for (const line of content.split("\n")) {
+		if (line.trim() === "") continue;
+		try {
+			const entry = JSON.parse(line);
+			const details = asRecord(entry["details"]);
+			const correlationId = details?.["correlation_id"];
+			const scope = entry["scope"];
+			if (entry["event"] === "rem_trigger_evaluated" && details?.["row"] === "dispatch" && typeof correlationId === "string" && typeof scope === "string") {
+				const trigger = details["trigger"];
+				const passAt = details["pass_at"];
+				const localDate = details["local_date"];
+				dispatched.set(correlationId, {
+					scope,
+					...trigger === "daily" || trigger === "volume" ? { trigger } : {},
+					...typeof passAt === "string" ? { passAt } : {},
+					...typeof localDate === "string" ? { localDate } : {}
+				});
+				continue;
+			}
+			if (entry["event"] === "rem_skipped" && typeof correlationId === "string") {
+				const skipped = dispatched.get(correlationId);
+				if (skipped && nextState.scopes[skipped.scope]?.attempts.identity === correlationId) nextState = replaceScopeState(nextState, skipped.scope, {
+					...requiredScopeState(nextState, skipped.scope),
+					attempts: {
+						identity: null,
+						count: 0
+					}
+				});
+				continue;
+			}
+			if (entry["event"] !== "rem_completed" || typeof correlationId !== "string") continue;
+			const dispatch = dispatched.get(correlationId);
+			if (dispatch === void 0 || state.scopes[dispatch.scope] === void 0 || entry["scope"] !== dispatch.scope) continue;
+			const currentScopeState = requiredScopeState(nextState, dispatch.scope);
+			let completedScopeState = {
+				...currentScopeState,
+				...dispatch.trigger === "daily" && isValidInstant(dispatch.passAt) ? { last_pass_at: dispatch.passAt } : {},
+				...dispatch.trigger === "daily" && isLocalDate(dispatch.localDate) ? { last_volume_pass_date: dispatch.localDate } : {},
+				...dispatch.trigger === "volume" && isLocalDate(dispatch.localDate) ? { last_volume_pass_date: dispatch.localDate } : {},
+				...currentScopeState.attempts.identity === correlationId ? { attempts: {
+					identity: null,
+					count: 0
+				} } : {}
+			};
+			const measured = asRecord(asRecord(details?.["stats"])?.["measured"]);
+			const rowsConsidered = measured?.["rows_considered"];
+			if (measured?.["pair_cap_binding"] === false && Number.isInteger(rowsConsidered) && Number(rowsConsidered) >= 0) completedScopeState = {
+				...completedScopeState,
+				last_covered_count: Number(rowsConsidered)
+			};
+			if (JSON.stringify(completedScopeState) === JSON.stringify(currentScopeState)) continue;
+			nextState = replaceScopeState(nextState, dispatch.scope, completedScopeState);
+		} catch {
+			malformedCount += 1;
+		}
+	}
+	if (malformedCount > 0) log.warn("Malformed REM audit records skipped", {
+		malformed_count: malformedCount,
+		outcome: "partial"
+	}, {
+		event_name: "sidecar.trigger.audit_records.skipped",
+		file: "packages/memory/src/sidecar/rem-trigger.ts",
+		function: "applyCompletedBaselines",
+		site_id: "sidecar.trigger.audit_records.skipped"
+	});
+	if (nextState !== state) await writeRemTriggerStateAtomic(triggerStateDir, nextState);
+	return nextState;
+}
+async function readAuditTail(auditPath) {
+	const handle = await open(auditPath, "r");
+	try {
+		const size = (await handle.stat()).size;
+		const bytesToRead = Math.min(size, REM_COMPLETION_AUDIT_TAIL_BYTES);
+		if (bytesToRead === 0) return "";
+		const buffer = Buffer.alloc(bytesToRead);
+		const { bytesRead } = await handle.read(buffer, 0, bytesToRead, size - bytesToRead);
+		let content = buffer.subarray(0, bytesRead).toString("utf8");
+		if (size > bytesToRead) {
+			const firstLineEnd = content.indexOf("\n");
+			content = firstLineEnd === -1 ? "" : content.slice(firstLineEnd + 1);
+		}
+		return content;
+	} finally {
+		await handle.close();
+	}
+}
+function remAutomaticCorrelationId(trigger, scope, triggerKey) {
+	return `rem-auto-${trigger}-${createHash("sha256").update(JSON.stringify([
+		"rem-automatic-v1",
+		trigger,
+		scope,
+		triggerKey
+	])).digest("hex")}`;
+}
+/** The daily due time, pushed to the schedule after the last used-up local day. */
+function nextDailyDue(scopeState) {
+	const scheduled = computeRemDailyDue(scopeState.last_pass_at, scopeState.schedule_zone);
+	const volumeDate = scopeState.last_volume_pass_date;
+	if (volumeDate === null) return scheduled;
+	const parsed = /^(\d{4})-(\d{2})-(\d{2})$/u.exec(volumeDate);
+	if (parsed === null) return scheduled;
+	const following = addCalendarDays({
+		year: Number(parsed[1]),
+		month: Number(parsed[2]),
+		day: Number(parsed[3])
+	}, 1);
+	const afterVolume = zonedInstant(scopeState.schedule_zone, following.year, following.month, following.day);
+	return afterVolume.getTime() > scheduled.getTime() ? afterVolume : scheduled;
+}
+function computeRemDailyDue(lastPassAt, scheduleZone) {
+	const lastPass = new Date(lastPassAt);
+	if (Number.isNaN(lastPass.getTime())) throw new Error("REM last pass time is invalid");
+	const localDate = localDateParts(lastPass, scheduleZone);
+	let due = zonedInstant(scheduleZone, localDate.year, localDate.month, localDate.day);
+	if (due.getTime() <= lastPass.getTime()) {
+		const nextDate = addCalendarDays(localDate, 1);
+		due = zonedInstant(scheduleZone, nextDate.year, nextDate.month, nextDate.day);
+	}
+	return due;
+}
+function zonedInstant(zone, year, month, day) {
+	const target = Date.UTC(year, month - 1, day, 3, 0, 0, 0);
+	let instant = target;
+	let firstExistingAfter;
+	for (let iteration = 0; iteration < 5; iteration++) {
+		const parts = zonedDateTimeParts(new Date(instant), zone);
+		const represented = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second);
+		const adjustment = target - represented;
+		if (adjustment === 0) return new Date(instant);
+		if (represented > target && represented < (firstExistingAfter?.represented ?? Number.POSITIVE_INFINITY)) firstExistingAfter = {
+			instant,
+			represented
+		};
+		instant += adjustment;
+	}
+	if (firstExistingAfter !== void 0) return new Date(firstExistingAfter.instant);
+	throw new Error(`REM scheduled instant cannot be resolved in zone ${zone}`);
+}
+function localDateAt(instant, zone) {
+	const parts = localDateParts(instant, zone);
+	return `${parts.year.toString().padStart(4, "0")}-${parts.month.toString().padStart(2, "0")}-${parts.day.toString().padStart(2, "0")}`;
+}
+function localDateParts(instant, zone) {
+	const parts = zonedDateTimeParts(instant, zone);
+	return {
+		year: parts.year,
+		month: parts.month,
+		day: parts.day
+	};
+}
+function zonedDateTimeParts(instant, zone) {
+	const values = {};
+	const formatter = new Intl.DateTimeFormat("en-CA", {
+		timeZone: zone,
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit",
+		hourCycle: "h23"
+	});
+	for (const part of formatter.formatToParts(instant)) if (part.type !== "literal") values[part.type] = Number(part.value);
+	const year = values["year"];
+	const month = values["month"];
+	const day = values["day"];
+	const hour = values["hour"];
+	const minute = values["minute"];
+	const second = values["second"];
+	if ([
+		year,
+		month,
+		day,
+		hour,
+		minute,
+		second
+	].some((value) => value === void 0)) throw new Error(`REM schedule zone ${zone} did not produce complete date parts`);
+	return {
+		year: Number(year),
+		month: Number(month),
+		day: Number(day),
+		hour: Number(hour),
+		minute: Number(minute),
+		second: Number(second)
+	};
+}
+function addCalendarDays(date, days) {
+	const instant = new Date(Date.UTC(date.year, date.month - 1, date.day + days));
+	return {
+		year: instant.getUTCFullYear(),
+		month: instant.getUTCMonth() + 1,
+		day: instant.getUTCDate()
+	};
+}
+function growthDetails(candidateCount, coveredCount, threshold) {
+	const growth = candidateCount - coveredCount;
+	return {
+		candidate_count: candidateCount,
+		last_covered_count: coveredCount,
+		delta: growth,
+		threshold,
+		remaining: Math.max(0, threshold - growth)
+	};
+}
+async function recordDecision(stateDir, scope, resultStatus, details) {
+	await appendAuditEntryStrict(stateDir, {
+		event: "rem_trigger_evaluated",
+		resultStatus,
+		...scope === void 0 ? {} : { scope },
+		details
+	});
+}
+function requiredScopeState(state, scope) {
+	const scopeState = state.scopes[scope];
+	if (scopeState === void 0) throw new Error(`REM trigger state missing scope ${scope}`);
+	return scopeState;
+}
+function replaceScopeState(state, scope, scopeState) {
+	return {
+		version: 1,
+		scopes: {
+			...state.scopes,
+			[scope]: scopeState
+		}
+	};
+}
+function asRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+function isValidInstant(value) {
+	return value !== void 0 && !Number.isNaN(new Date(value).getTime());
+}
+function isLocalDate(value) {
+	return value !== void 0 && /^\d{4}-\d{2}-\d{2}$/u.test(value);
+}
+function isNodeError(error) {
+	return error instanceof Error && "code" in error;
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+export { DEGRADED_REASONS as i, remNeedsHost as n, ContractError as r, evaluateRemAutomaticTriggers as t };