@bridge_gpt/mcp-server 0.2.2 → 0.2.4

package/build/conductor/supervisor-state.js

@@ -0,0 +1,572 @@
+/**
+ * Deterministic supervisor state reduction + housekeeping (BAPI-396, conductor
+ * C4).
+ *
+ * This module converts raw conductor ledger events into per-worker watchdog
+ * state and run-level projection state. It is PURE and deterministic: it has no
+ * I/O, no timers, and no LLM calls. Every time-dependent function takes an
+ * explicit `now` (epoch ms) so tests are wall-clock independent.
+ *
+ * Truth precedence (enforced here): raw events are the source of truth. A
+ * `supervisor.assessment` event is audit-only and NEVER overrides a worker's
+ * raw-derived state. Terminal states (`complete` / `failed`) are sticky and are
+ * only replaced by a stronger explicit raw terminal event.
+ */
+/** Marker stored on the projection summary so hydration can validate it. */
+export const SUPERVISOR_SUMMARY_KIND = "supervisor_projection_summary";
+const TERMINAL_STATES = new Set(["complete", "failed"]);
+/** Is this worker in a sticky terminal state? */
+function isTerminalState(state) {
+    return TERMINAL_STATES.has(state);
+}
+/** Safe ISO -> epoch ms (returns null on unparseable input). */
+function isoToMs(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return null;
+    const ms = Date.parse(value);
+    return Number.isFinite(ms) ? ms : null;
+}
+/** Epoch ms -> ISO string. */
+function msToIso(now) {
+    return new Date(now).toISOString();
+}
+// ---------------------------------------------------------------------------
+// Construction & hydration
+// ---------------------------------------------------------------------------
+/**
+ * Initialize an empty {@link SupervisorRunState} scoped to exactly one run. The
+ * global deadline is `now + config.global_timeout_ms`.
+ */
+export function createEmptySupervisorRunState(runId, config, now) {
+    const startedIso = msToIso(now);
+    return {
+        run_id: runId,
+        status: "unknown",
+        last_seq: 0,
+        last_event_time: null,
+        workers: {},
+        gates: {},
+        latest_assessment: null,
+        escalations: [],
+        llm_budget: {
+            enabled: config.llm_enabled,
+            max_calls: config.llm_max_calls,
+            used_calls: 0,
+        },
+        started_at: startedIso,
+        updated_at: startedIso,
+        global_deadline_at: msToIso(now + config.global_timeout_ms),
+        roster_discovered: false,
+    };
+}
+/** Is a parsed summary object a plausible supervisor summary? */
+function isValidSupervisorSummary(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        value.kind === SUPERVISOR_SUMMARY_KIND);
+}
+/**
+ * Hydrate run state from a supervisor snapshot's projection summary. ALWAYS
+ * enforces the requested `runId` — a summary persisted under a different run is
+ * never allowed to take ownership. Falls back to {@link
+ * createEmptySupervisorRunState} when the snapshot is missing or malformed.
+ */
+export function hydrateSupervisorRunStateFromSnapshot(snapshot, runId, config, now) {
+    const empty = createEmptySupervisorRunState(runId, config, now);
+    const summary = snapshot?.projection?.summary;
+    if (!isValidSupervisorSummary(summary)) {
+        return empty;
+    }
+    // Merge persisted fields on top of the empty scaffold, then HARD-OVERRIDE the
+    // run id so a cross-run summary can never be hydrated under this run.
+    const hydrated = {
+        ...empty,
+        status: typeof summary.status === "string" ? summary.status : empty.status,
+        last_seq: typeof summary.last_seq === "number" && summary.last_seq >= 0 ? summary.last_seq : empty.last_seq,
+        last_event_time: typeof summary.last_event_time === "string" ? summary.last_event_time : null,
+        workers: isPlainRecord(summary.workers) ? summary.workers : {},
+        gates: isPlainRecord(summary.gates) ? summary.gates : {},
+        latest_assessment: summary.latest_assessment && typeof summary.latest_assessment === "object"
+            ? summary.latest_assessment
+            : null,
+        escalations: Array.isArray(summary.escalations)
+            ? summary.escalations
+            : [],
+        llm_budget: summary.llm_budget && typeof summary.llm_budget === "object"
+            ? {
+                enabled: config.llm_enabled,
+                max_calls: config.llm_max_calls,
+                used_calls: typeof summary.llm_budget.used_calls === "number"
+                    ? summary.llm_budget.used_calls
+                    : 0,
+            }
+            : empty.llm_budget,
+        started_at: typeof summary.started_at === "string" ? summary.started_at : empty.started_at,
+        global_deadline_at: typeof summary.global_deadline_at === "string" ? summary.global_deadline_at : empty.global_deadline_at,
+        roster_discovered: summary.roster_discovered === true,
+        run_id: runId,
+    };
+    return hydrated;
+}
+function isPlainRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Return the existing worker state for `workerId`, creating it if absent. A
+ * roster-discovered worker starts `not_started`; a worker first seen via an
+ * arbitrary event starts `unknown`. Existing workers are returned as-is —
+ * terminal states are preserved (never downgraded by mere rediscovery).
+ */
+export function ensureWorkerState(state, workerId, options = {}) {
+    const existing = state.workers[workerId];
+    if (existing) {
+        if (options.ticketKey && !existing.ticket_key) {
+            existing.ticket_key = options.ticketKey;
+        }
+        return existing;
+    }
+    const created = {
+        worker_id: workerId,
+        ticket_key: options.ticketKey ?? null,
+        state: options.fromRoster ? "not_started" : "unknown",
+        liveness: "unknown",
+        first_seen_seq: options.seq ?? null,
+        last_event_seq: options.seq ?? null,
+        last_event_time: null,
+        last_progress_time: null,
+        last_heartbeat_time: null,
+        blocked_reason: null,
+        terminal_reason: null,
+        observed_event_types: [],
+    };
+    state.workers[workerId] = created;
+    return created;
+}
+/** Record that a worker observed `eventType` (deduped, bounded list). */
+function noteObservedType(worker, eventType) {
+    if (!worker.observed_event_types.includes(eventType)) {
+        worker.observed_event_types.push(eventType);
+    }
+}
+/** Extract a normalized `data.details` object from an event, if present. */
+function eventDetails(event) {
+    const details = event.data?.details;
+    return isPlainRecord(details) ? details : {};
+}
+/**
+ * Extract a worker roster from a `run.started` event. Supports rosters at
+ * `data.details.workers`, `data.workers`, or `data.raw.workers`. Each entry is
+ * read for `worker_id` and `ticket_key` only (compact, secret-free).
+ */
+function extractRoster(event) {
+    const candidates = [
+        eventDetails(event).workers,
+        event.data?.workers,
+        isPlainRecord(event.data?.raw) ? event.data.raw.workers : undefined,
+    ];
+    for (const candidate of candidates) {
+        if (Array.isArray(candidate)) {
+            const roster = [];
+            for (const entry of candidate) {
+                if (!isPlainRecord(entry))
+                    continue;
+                const workerId = entry.worker_id;
+                if (typeof workerId !== "string" || workerId.length === 0)
+                    continue;
+                const ticketKey = entry.ticket_key;
+                roster.push({
+                    worker_id: workerId,
+                    ticket_key: typeof ticketKey === "string" ? ticketKey : null,
+                });
+            }
+            if (roster.length > 0)
+                return roster;
+        }
+    }
+    return [];
+}
+/** Lowercased `data.status` from an event, or "". */
+function eventStatus(event) {
+    const status = event.data?.status;
+    return typeof status === "string" ? status.trim().toLowerCase() : "";
+}
+/** Lowercased `data.reason` (or details.reason) from an event, or "". */
+function eventReason(event) {
+    const reason = event.data?.reason ?? eventDetails(event).reason;
+    return typeof reason === "string" ? reason.trim().toLowerCase() : "";
+}
+const PROGRESS_EVENT_TYPES = new Set([
+    "tool.intent",
+    "worktree.changed",
+    "git.commit_created",
+]);
+const BLOCKED_STATUS_TOKENS = new Set(["blocked", "waiting_for_input", "needs_input"]);
+/** Statuses on `run.stopped` that mean the worker failed (vs. completed). */
+const FAILED_STATUS_TOKENS = new Set(["failed", "error", "errored", "aborted", "cancelled", "canceled"]);
+/**
+ * Apply ONE raw conductor event to the supervisor state, mutating and returning
+ * it. Events whose `run_id` does not match are ignored WITHOUT advancing
+ * `last_seq`. Matching events advance `last_seq` (monotonic) and update
+ * `last_event_time`. Raw events are authoritative; `supervisor.assessment` is
+ * treated as audit input only.
+ */
+export function applyConductorEventToSupervisorState(state, event, now) {
+    // Run scoping: ignore foreign-run events entirely.
+    if (event.run_id !== state.run_id) {
+        return state;
+    }
+    const eventType = event.type;
+    const eventTimeMs = isoToMs(event.time) ?? now;
+    const eventTimeIso = event.time ?? msToIso(now);
+    // Advance the cursor and run-level last event time.
+    if (typeof event.seq === "number" && event.seq > state.last_seq) {
+        state.last_seq = event.seq;
+    }
+    state.last_event_time = eventTimeIso;
+    if (state.status === "unknown")
+        state.status = "active";
+    // run.started: discover the roster. Workers are created `not_started`.
+    if (eventType === "run.started") {
+        const roster = extractRoster(event);
+        if (roster.length > 0)
+            state.roster_discovered = true;
+        for (const member of roster) {
+            const worker = ensureWorkerState(state, member.worker_id, {
+                fromRoster: true,
+                ticketKey: member.ticket_key,
+                seq: event.seq,
+            });
+            noteObservedType(worker, eventType);
+            worker.last_event_seq = event.seq ?? worker.last_event_seq;
+            worker.last_event_time = eventTimeIso;
+        }
+        state.updated_at = msToIso(now);
+        return state;
+    }
+    // supervisor.assessment and message.sent are SUPERVISOR-side audit events and
+    // must NOT advance the target worker's liveness/stall anchor. message.sent is
+    // emitted scoped to the *target* worker (so the relay can attribute it), so
+    // without this guard the very act of sending an escalation to a stalled worker
+    // would stamp that worker with a fresh last_event_time — making it look `alive`
+    // on the next housekeeping pass and resetting its stall anchor, defeating the
+    // watchdog. (message.delivered / message.acked ARE the worker's own activity and
+    // are handled as liveness signals in the worker switch below — BAPI-397.)
+    if (eventType === "supervisor.assessment" || eventType === "message.sent") {
+        state.updated_at = msToIso(now);
+        return state;
+    }
+    // Events with a worker_id mutate that worker; otherwise run-level only.
+    const workerId = event.worker_id;
+    if (typeof workerId !== "string" || workerId.length === 0) {
+        applyRunLevelEvent(state, event, eventType);
+        state.updated_at = msToIso(now);
+        return state;
+    }
+    const worker = ensureWorkerState(state, workerId, { seq: event.seq });
+    noteObservedType(worker, eventType);
+    worker.last_event_seq = event.seq ?? worker.last_event_seq;
+    worker.last_event_time = eventTimeIso;
+    switch (eventType) {
+        case "run.heartbeat": {
+            worker.last_heartbeat_time = eventTimeIso;
+            if (!isTerminalState(worker.state) && worker.state !== "blocked") {
+                // A heartbeat alone is not "progress" but it does promote a not_started
+                // or unknown worker to active.
+                if (worker.state === "not_started" || worker.state === "unknown") {
+                    worker.state = "active";
+                }
+            }
+            break;
+        }
+        case "agent.notification": {
+            const status = eventStatus(event);
+            const reason = eventReason(event);
+            if (BLOCKED_STATUS_TOKENS.has(status) || BLOCKED_STATUS_TOKENS.has(reason)) {
+                if (!isTerminalState(worker.state)) {
+                    worker.state = "blocked";
+                    worker.blocked_reason = status || reason || "blocked";
+                }
+            }
+            else if (!isTerminalState(worker.state) && worker.state === "not_started") {
+                // An ambiguous notification still indicates the worker is alive.
+                worker.state = "active";
+            }
+            break;
+        }
+        case "tool.intent":
+        case "worktree.changed":
+        case "git.commit_created": {
+            if (PROGRESS_EVENT_TYPES.has(eventType)) {
+                worker.last_progress_time = eventTimeIso;
+                if (!isTerminalState(worker.state)) {
+                    // Deterministic progress clears a blocked/stalled marker and keeps the
+                    // worker active.
+                    if (worker.state === "not_started" || worker.state === "unknown" || worker.state === "stalled" || worker.state === "blocked") {
+                        worker.state = "active";
+                    }
+                    worker.blocked_reason = null;
+                }
+            }
+            break;
+        }
+        case "gate.met": {
+            if (!isTerminalState(worker.state)) {
+                worker.state = "candidate_done";
+            }
+            break;
+        }
+        case "ci.passed": {
+            if (!isTerminalState(worker.state)) {
+                worker.state = "verifying";
+            }
+            worker.last_progress_time = eventTimeIso;
+            break;
+        }
+        case "ci.failed": {
+            // Only an explicit, semantically-terminal worker-scoped CI failure marks a
+            // worker failed; otherwise keep it nonterminal (CI may retry).
+            const reason = eventReason(event);
+            const status = eventStatus(event);
+            if (status === "terminal" || reason === "terminal" || reason === "give_up") {
+                worker.state = "failed";
+                worker.terminal_reason = reason || "ci_failed";
+            }
+            else if (!isTerminalState(worker.state)) {
+                worker.last_progress_time = eventTimeIso;
+            }
+            break;
+        }
+        case "run.stopped": {
+            const status = eventStatus(event);
+            const reason = eventReason(event);
+            if (FAILED_STATUS_TOKENS.has(status) || FAILED_STATUS_TOKENS.has(reason)) {
+                worker.state = "failed";
+                worker.terminal_reason = reason || status || "failed";
+            }
+            else {
+                worker.state = "complete";
+                worker.terminal_reason = reason || status || "complete";
+            }
+            break;
+        }
+        case "message.delivered":
+        case "message.acked": {
+            // BAPI-397: a worker that polled + acked a supervisor relay message is
+            // demonstrably alive. Treat it as a LIVENESS signal (promote a
+            // not_started/unknown worker to active, like a heartbeat) but NOT as
+            // deterministic implementation progress: message relay types are
+            // deliberately absent from PROGRESS_EVENT_TYPES, so last_progress_time is
+            // never advanced here. Terminal states stay sticky (the guard below) and a
+            // blocked/stalled worker is not silently revived by an ack.
+            if (!isTerminalState(worker.state) &&
+                (worker.state === "not_started" || worker.state === "unknown")) {
+                worker.state = "active";
+            }
+            break;
+        }
+        case "merge.succeeded": {
+            // BAPI-398: a successful autonomous merge is the worker's payoff — mark it
+            // complete with an auto-merge terminal reason.
+            worker.state = "complete";
+            worker.terminal_reason = worker.terminal_reason || "merge_succeeded";
+            break;
+        }
+        case "merge.failed": {
+            // BAPI-398: merge.failed is RETRYABLE (head-SHA drift / CI-not-green /
+            // provider conflict can self-resolve on a new head SHA + action key). Record
+            // it as observed (noteObservedType above) but never mark the worker terminal.
+            break;
+        }
+        case "merge.dry_run": {
+            // BAPI-398: dry-run is audit-only (repo flag off / fail-closed). Keep the
+            // worker nonterminal.
+            break;
+        }
+        case "merge.pending_approval": {
+            // BAPI-413: pending_approval is nonterminal — the worker must stay active
+            // until the human redeems the token and the backend returns merge.succeeded.
+            break;
+        }
+        default:
+            break;
+    }
+    state.updated_at = msToIso(now);
+    return state;
+}
+/** Apply a run-level (no worker_id) event to gate/verification metadata. */
+function applyRunLevelEvent(state, event, eventType) {
+    switch (eventType) {
+        case "gate.met":
+            state.gates.gate_met = true;
+            break;
+        case "ci.passed":
+            state.gates.ci = "passed";
+            break;
+        case "ci.failed":
+            state.gates.ci = "failed";
+            break;
+        case "git.pr_opened":
+            state.gates.pr_opened = true;
+            break;
+        case "merge.succeeded":
+        case "merge.failed":
+        case "merge.dry_run":
+        case "merge.pending_approval":
+            // BAPI-398/413: run-level merge events (no worker_id) are recorded compactly
+            // under gate metadata WITHOUT creating a worker. Worker-scoped merge events
+            // are handled in the main reducer; merges are normally worker-scoped.
+            state.gates.merge = eventType.slice("merge.".length);
+            break;
+        default:
+            break;
+    }
+}
+// ---------------------------------------------------------------------------
+// Liveness & housekeeping (Step 6)
+// ---------------------------------------------------------------------------
+/**
+ * Classify a worker's LIVENESS from timestamps only — independent of its
+ * progress (watchdog) state. Terminal workers return a stable `alive` liveness
+ * (they are done, not dead). A worker with no observed timestamps is `unknown`.
+ */
+export function classifyWorkerLiveness(worker, config, now) {
+    if (isTerminalState(worker.state))
+        return "alive";
+    const lastSignalMs = mostRecentSignalMs(worker);
+    if (lastSignalMs === null)
+        return "unknown";
+    const elapsed = now - lastSignalMs;
+    if (elapsed >= config.liveness.dead_after_ms)
+        return "dead";
+    if (elapsed >= config.liveness.stalled_after_ms)
+        return "stalled";
+    if (elapsed >= config.liveness.quiet_after_ms)
+        return "quiet";
+    return "alive";
+}
+/** Most recent of heartbeat / event / progress timestamps (ms), or null. */
+function mostRecentSignalMs(worker) {
+    const candidates = [
+        isoToMs(worker.last_heartbeat_time),
+        isoToMs(worker.last_event_time),
+        isoToMs(worker.last_progress_time),
+    ].filter((v) => v !== null);
+    if (candidates.length === 0)
+        return null;
+    return Math.max(...candidates);
+}
+/** Reference time for a worker's CURRENT-state stall budget. */
+function stateAnchorMs(worker) {
+    // For long active/verifying work, prefer recent progress so a long but
+    // PROGRESSING worker is never falsely stalled. Fall back to last event time,
+    // then heartbeat.
+    if (worker.state === "active" || worker.state === "verifying") {
+        return mostRecentSignalMs(worker);
+    }
+    // not_started/unknown/candidate_done/blocked/stalled: anchor on last event.
+    return (isoToMs(worker.last_event_time) ??
+        isoToMs(worker.last_heartbeat_time) ??
+        isoToMs(worker.last_progress_time));
+}
+/**
+ * Recompute liveness for every worker and apply STATE-SPECIFIC stall
+ * thresholds. A worker is moved to `stalled` only when its CURRENT state's
+ * threshold has elapsed — there is no flat timeout. Terminal workers are never
+ * touched. Active/verifying workers with recent progress are protected from
+ * false-positive stalls because their anchor is the most recent signal.
+ */
+export function applySupervisorHousekeeping(state, config, now) {
+    for (const worker of Object.values(state.workers)) {
+        worker.liveness = classifyWorkerLiveness(worker, config, now);
+        if (isTerminalState(worker.state) || worker.state === "stalled") {
+            continue;
+        }
+        const threshold = config.stall_thresholds_ms[worker.state];
+        const anchor = stateAnchorMs(worker);
+        if (anchor === null)
+            continue;
+        if (now - anchor >= threshold) {
+            worker.state = "stalled";
+        }
+    }
+    state.updated_at = msToIso(now);
+    return state;
+}
+/**
+ * A run is terminal ONLY when a worker roster has been discovered AND every
+ * known worker is `complete` or `failed`. With no roster discovered, the run is
+ * not terminal (the global timeout is the separate backstop).
+ */
+export function isSupervisorRunTerminal(state) {
+    const workers = Object.values(state.workers);
+    if (workers.length === 0)
+        return false;
+    if (!state.roster_discovered)
+        return false;
+    return workers.every((w) => isTerminalState(w.state));
+}
+/** Has the configured global deadline passed at `now`? Independent of stalls. */
+export function hasSupervisorGlobalTimeoutElapsed(state, now) {
+    const deadlineMs = isoToMs(state.global_deadline_at);
+    if (deadlineMs === null)
+        return false;
+    return now >= deadlineMs;
+}
+// ---------------------------------------------------------------------------
+// Projection serialization (Step 7)
+// ---------------------------------------------------------------------------
+/** Compact, secret-free per-worker summary stored in `active_workers`. */
+function compactWorker(worker) {
+    return {
+        worker_id: worker.worker_id,
+        ticket_key: worker.ticket_key,
+        state: worker.state,
+        liveness: worker.liveness,
+        last_event_seq: worker.last_event_seq,
+        last_event_time: worker.last_event_time,
+        last_progress_time: worker.last_progress_time,
+        last_heartbeat_time: worker.last_heartbeat_time,
+        blocked_reason: worker.blocked_reason,
+        terminal_reason: worker.terminal_reason,
+    };
+}
+/**
+ * Convert run state into a {@link SupervisorProjectionInput}. `active_workers`
+ * holds compact worker summaries (never raw event data); `gates` holds gate
+ * metadata; `assessment` holds the latest assessment or null; and `summary`
+ * holds the FULL resumable supervisor state (worker watchdog states, liveness,
+ * last seq, escalation history, LLM budget usage, run start/deadline metadata).
+ *
+ * The serialized summary is secret-free by construction: it is built only from
+ * the compact state fields above — never from raw payloads, secrets, or LLM
+ * prompts.
+ */
+export function toSupervisorProjectionInput(state) {
+    const summary = {
+        kind: SUPERVISOR_SUMMARY_KIND,
+        run_id: state.run_id,
+        status: state.status,
+        last_seq: state.last_seq,
+        last_event_time: state.last_event_time,
+        workers: state.workers,
+        gates: state.gates,
+        latest_assessment: state.latest_assessment,
+        escalations: state.escalations,
+        llm_budget: state.llm_budget,
+        started_at: state.started_at,
+        updated_at: state.updated_at,
+        global_deadline_at: state.global_deadline_at,
+        roster_discovered: state.roster_discovered,
+    };
+    return {
+        run_id: state.run_id,
+        status: state.status,
+        last_seq: state.last_seq,
+        last_event_time: state.last_event_time,
+        active_workers: Object.values(state.workers).map(compactWorker),
+        gates: state.gates,
+        assessment: state.latest_assessment,
+        summary,
+    };
+}

package/build/conductor/supervisor-types.js

@@ -0,0 +1,16 @@
+/**
+ * Shared DTO / state-vocabulary contracts for the conductor supervisor runtime
+ * (BAPI-396, conductor C4).
+ *
+ * These are pure TypeScript type declarations with NO runtime behavior so every
+ * supervisor module (config, reducer, escalation, judgment, runtime) can depend
+ * on them freely without import cycles or side effects.
+ *
+ * Vocabulary split — the supervisor tracks two ORTHOGONAL axes per worker:
+ *   - {@link WatchdogState}: the worker's progress through the run lifecycle
+ *     (derived from raw ledger events; raw events are the source of truth).
+ *   - {@link WorkerLiveness}: how recently the worker produced ANY signal
+ *     (derived purely from timestamps). Liveness is NOT progress: a worker can
+ *     be `active` (progress) yet `quiet` (liveness) during a long build.
+ */
+export {};

package/build/conductor/taxonomy.js

@@ -0,0 +1,58 @@
+/**
+ * Conductor semantic event taxonomy.
+ *
+ * This module is the SINGLE SOURCE OF TRUTH for the set of accepted conductor
+ * event types. The SQLite `events` table CHECK constraint, the Zod tool input
+ * enums, and the CLI parser all derive their accepted vocabulary from
+ * {@link SEMANTIC_EVENT_TYPES} here. It is deliberately framework-agnostic and
+ * has no I/O or store dependencies so it can be imported from the store, the
+ * tools, the CLI, and unit tests alike.
+ */
+import { ConductorValidationError } from "./errors.js";
+/**
+ * The exact, ordered set of accepted semantic event types. The order is part of
+ * the contract (a unit test pins it) so downstream artifacts — the schema CHECK
+ * constraint and the Zod enum — render deterministically.
+ */
+export const SEMANTIC_EVENT_TYPES = [
+    "run.started",
+    "run.heartbeat",
+    "run.stopped",
+    "agent.notification",
+    "tool.intent",
+    "worktree.changed",
+    "git.commit_created",
+    "git.pr_opened",
+    "ci.passed",
+    "ci.failed",
+    "gate.met",
+    "supervisor.assessment",
+    "message.sent",
+    "message.delivered",
+    "message.acked",
+    "merge.dry_run",
+    "merge.attempted",
+    "merge.succeeded",
+    "merge.failed",
+    "merge.pending_approval",
+];
+/**
+ * Type guard: returns `true` only when `value` is one of the exact taxonomy
+ * strings. Rejects non-strings, casing variants, and surrounding whitespace.
+ */
+export function isSemanticEventType(value) {
+    return (typeof value === "string" &&
+        SEMANTIC_EVENT_TYPES.includes(value));
+}
+/**
+ * Narrow `value` to a {@link SemanticEventType}, throwing a
+ * {@link ConductorValidationError} for any non-taxonomy value. The error names
+ * the invalid event-type problem but never echoes unrelated payload data.
+ */
+export function assertSemanticEventType(value) {
+    if (isSemanticEventType(value)) {
+        return value;
+    }
+    const rendered = typeof value === "string" ? value : typeof value;
+    throw new ConductorValidationError(`Unknown conductor event type "${rendered}". Allowed types: ${SEMANTIC_EVENT_TYPES.join(", ")}.`);
+}