@bridge_gpt/mcp-server 0.2.9 → 0.2.12

package/build/conductor/pr-ci-producer.js

@@ -11,7 +11,16 @@
  */
 import { GIT_CI_PRODUCER, } from "./git-ci-types.js";
 import { evaluateDoneGate, normalizeCiSnapshot, parseDoneGateConfig } from "./done-gate.js";
-import { fetchDoneGateConfigField, pollCiChecksForCommit, resolveConductorBridgeApiAccess, } from "./bridge-api-client.js";
+import { observeReviewWithResolved } from "./pr-review-producer.js";
+import { fetchEffectiveSupervisorSetup, fetchActiveEpicRuns, fetchEpicRunState, pollCiChecksForCommit, resolveConductorBridgeApiAccess, } from "./bridge-api-client.js";
+/** Default gate-config fetcher: reads done_gate_config from the supervisor setup. */
+async function _fetchGateConfigDefault(access) {
+    const setup = await fetchEffectiveSupervisorSetup(access);
+    // Fail closed when no row exists (source="none")
+    if (setup.source === "none")
+        return undefined;
+    return setup.done_gate_config ?? undefined;
+}
 import { resolvePrHeadBinding } from "./pr-discovery.js";
 import { emitConductorEventIfNew } from "./producer-ledger.js";
 const PRODUCER_OBSERVED_VIA = "pr-ci-producer";
@@ -24,7 +33,7 @@ export const WAIT_FOR_GATE_POLL_INTERVAL_MIN_MS = 500;
 // Event builders
 // ---------------------------------------------------------------------------
 /** Build a `git.pr_opened` event bound to repo + PR number + head SHA. */
-export function buildPrOpenedEventInput(binding) {
+export function buildPrOpenedEventInput(binding, runId = null, workerId = null) {
     const details = {
         repo: binding.repo,
         pr_number: binding.pr_number,
@@ -43,6 +52,8 @@ export function buildPrOpenedEventInput(binding) {
         source: "git",
         type: "git.pr_opened",
         subject: binding.subject,
+        run_id: runId,
+        worker_id: workerId,
         producer: GIT_CI_PRODUCER,
         observed_via: PRODUCER_OBSERVED_VIA,
         data,
@@ -54,7 +65,7 @@ export function buildPrOpenedEventInput(binding) {
  * `ci.passed` requires every polled check complete and green; `ci.failed` requires
  * every polled check complete with at least one not green.
  */
-export function buildCiObservationEventInput(binding, snapshot) {
+export function buildCiObservationEventInput(binding, snapshot, runId = null, workerId = null) {
     if (snapshot.checks.length === 0)
         return null;
     const allComplete = snapshot.checks.every((c) => c.complete);
@@ -74,6 +85,8 @@ export function buildCiObservationEventInput(binding, snapshot) {
         source: "ci",
         type,
         subject: binding.subject,
+        run_id: runId,
+        worker_id: workerId,
         producer: GIT_CI_PRODUCER,
         observed_via: PRODUCER_OBSERVED_VIA,
         data: {
@@ -87,13 +100,15 @@ export function buildCiObservationEventInput(binding, snapshot) {
  * Build a canonical `gate.met` event from a successful {@link GateEvaluationResult}.
  * Returns `null` when the gate was not met (no event data to emit).
  */
-export function buildGateMetEventInput(binding, evaluation) {
+export function buildGateMetEventInput(binding, evaluation, runId = null, workerId = null) {
     if (!evaluation.met || !evaluation.gateEventData)
         return null;
     return {
         source: "conductor",
         type: "gate.met",
         subject: binding.subject,
+        run_id: runId,
+        worker_id: workerId,
         producer: GIT_CI_PRODUCER,
         observed_via: PRODUCER_OBSERVED_VIA,
         data: { ...evaluation.gateEventData },
@@ -112,6 +127,18 @@ async function observeWithResolved(binding, access, gateConfig, deps) {
     const emitIfNew = deps.emitIfNew ?? emitConductorEventIfNew;
     const pollCi = deps.pollCi ?? pollCiChecksForCommit;
     const now = deps.now ?? (() => new Date().toISOString());
+    // Resolve run_id/worker_id for attribution. Env takes precedence; fall back
+    // to the injected resolution seam when the env identity is absent.
+    let run_id = deps.env?.BAPI_CONDUCTOR_RUN_ID?.trim() || null;
+    const worker_id = deps.env?.BAPI_CONDUCTOR_WORKER_ID?.trim() || null;
+    if (run_id === null && deps.resolveRunId) {
+        try {
+            run_id = await deps.resolveRunId(access, binding) ?? null;
+        }
+        catch {
+            run_id = null;
+        }
+    }
     const result = {
         binding,
         pr_opened_emitted: false,
@@ -122,7 +149,7 @@ async function observeWithResolved(binding, access, gateConfig, deps) {
         reason: "observed",
     };
     // 1. PR opened telemetry (independent of CI / gate).
-    const prDecision = emitIfNew(buildPrOpenedEventInput(binding), {
+    const prDecision = await emitIfNew(buildPrOpenedEventInput(binding, run_id, worker_id), {
         event_type: "git.pr_opened",
         repo: binding.repo,
         pr_number: binding.pr_number,
@@ -141,13 +168,13 @@ async function observeWithResolved(binding, access, gateConfig, deps) {
     }
     const snapshot = normalizeCiSnapshot(rawPoll);
     // 3. CI observation telemetry (only for terminal states).
-    const ciEvent = buildCiObservationEventInput(binding, snapshot);
+    const ciEvent = buildCiObservationEventInput(binding, snapshot, run_id, worker_id);
     if (ciEvent === null) {
         result.ci_status = "pending";
     }
     else {
         result.ci_status = ciEvent.type === "ci.passed" ? "passed" : "failed";
-        const ciDecision = emitIfNew(ciEvent, {
+        const ciDecision = await emitIfNew(ciEvent, {
             event_type: ciEvent.type,
             repo: binding.repo,
             pr_number: binding.pr_number,
@@ -161,15 +188,29 @@ async function observeWithResolved(binding, access, gateConfig, deps) {
         result.reason = `gate inactive: ${gateConfig.reason}`;
         return result;
     }
-    const evaluation = evaluateDoneGate(gateConfig, binding, snapshot, now());
+    // 4a. Observe review state (alongside CI) for composite gate evaluation.
+    // A review poll failure must not block the CI observation — fail open here.
+    let reviewSnapshot = null;
+    try {
+        const reviewObservation = await observeReviewWithResolved(binding, access, gateConfig, {
+            emitIfNew: deps.emitIfNew ?? emitConductorEventIfNew,
+            env: deps.env,
+        });
+        reviewSnapshot = reviewObservation.snapshot;
+    }
+    catch {
+        // fail open: a review observation error does not block CI/gate evaluation
+        reviewSnapshot = null;
+    }
+    const evaluation = evaluateDoneGate(gateConfig, binding, snapshot, now(), reviewSnapshot);
     if (!evaluation.met) {
         result.reason = evaluation.reason;
         return result;
     }
     result.gate_met = true;
-    const gateEvent = buildGateMetEventInput(binding, evaluation);
+    const gateEvent = buildGateMetEventInput(binding, evaluation, run_id, worker_id);
     if (gateEvent !== null) {
-        const gateDecision = emitIfNew(gateEvent, {
+        const gateDecision = await emitIfNew(gateEvent, {
             event_type: "gate.met",
             repo: binding.repo,
             pr_number: binding.pr_number,
@@ -190,7 +231,7 @@ async function observeWithResolved(binding, access, gateConfig, deps) {
 export async function observePrCiOnce(params = {}, deps = {}) {
     const resolveBinding = deps.resolveBinding ?? resolvePrHeadBinding;
     const resolveAccess = deps.resolveAccess ?? (() => resolveConductorBridgeApiAccess({ env: deps.env, cwd: deps.cwd }));
-    const fetchGateConfig = deps.fetchGateConfig ?? fetchDoneGateConfigField;
+    const fetchGateConfig = deps.fetchGateConfig ?? _fetchGateConfigDefault;
     const bindingResult = resolveBinding({ repoName: params.repoName, prNumber: params.prNumber, headSha: params.headSha, cwd: params.cwd ?? deps.cwd, env: deps.env }, deps.bindingDeps ?? {});
     if (!bindingResult.ok) {
         return {
@@ -239,7 +280,7 @@ function clampInt(value, fallback, min, max) {
 export async function waitForDoneGate(params = {}, deps = {}) {
     const resolveBinding = deps.resolveBinding ?? resolvePrHeadBinding;
     const resolveAccess = deps.resolveAccess ?? (() => resolveConductorBridgeApiAccess({ env: deps.env, cwd: params.worktreePath ?? deps.cwd }));
-    const fetchGateConfig = deps.fetchGateConfig ?? fetchDoneGateConfigField;
+    const fetchGateConfig = deps.fetchGateConfig ?? _fetchGateConfigDefault;
     const sleep = deps.sleep ?? defaultSleep;
     const now = deps.now ?? (() => new Date().toISOString());
     const timeoutMs = clampInt(params.timeoutMs, WAIT_FOR_GATE_TIMEOUT_DEFAULT_MS, 0, WAIT_FOR_GATE_TIMEOUT_MAX_MS);
@@ -355,6 +396,10 @@ export async function observePrCiFromPollResponse(commitRef, pollResponse, deps
             reason: "commit ref does not match PR head",
         };
     }
+    // Env-stamp identity; fall back to the resolution seam when env is absent.
+    // Access resolution for the seam is attempted inline within the gate block.
+    let run_id = deps.env?.BAPI_CONDUCTOR_RUN_ID?.trim() || null;
+    const worker_id = deps.env?.BAPI_CONDUCTOR_WORKER_ID?.trim() || null;
     const result = {
         binding,
         pr_opened_emitted: false,
@@ -364,7 +409,7 @@ export async function observePrCiFromPollResponse(commitRef, pollResponse, deps
         gate_emitted: false,
         reason: "observed",
     };
-    const prDecision = emitIfNew(buildPrOpenedEventInput(binding), {
+    const prDecision = await emitIfNew(buildPrOpenedEventInput(binding, run_id, worker_id), {
         event_type: "git.pr_opened",
         repo: binding.repo,
         pr_number: binding.pr_number,
@@ -372,13 +417,13 @@ export async function observePrCiFromPollResponse(commitRef, pollResponse, deps
     });
     result.pr_opened_emitted = prDecision.emitted;
     const snapshot = normalizeCiSnapshot(pollResponse);
-    const ciEvent = buildCiObservationEventInput(binding, snapshot);
+    const ciEvent = buildCiObservationEventInput(binding, snapshot, run_id, worker_id);
     if (ciEvent === null) {
         result.ci_status = "pending";
         return result;
     }
     result.ci_status = ciEvent.type === "ci.passed" ? "passed" : "failed";
-    const ciDecision = emitIfNew(ciEvent, {
+    const ciDecision = await emitIfNew(ciEvent, {
         event_type: ciEvent.type,
         repo: binding.repo,
         pr_number: binding.pr_number,
@@ -388,13 +433,23 @@ export async function observePrCiFromPollResponse(commitRef, pollResponse, deps
     result.ci_emitted = ciDecision.emitted;
     // Best-effort gate evaluation when access + config are available.
     const resolveAccess = deps.resolveAccess ?? (() => resolveConductorBridgeApiAccess({ env: deps.env, cwd: deps.cwd }));
-    const fetchGateConfig = deps.fetchGateConfig ?? fetchDoneGateConfigField;
+    const fetchGateConfig = deps.fetchGateConfig ?? _fetchGateConfigDefault;
     try {
         const accessResult = await resolveAccess();
         if (accessResult.ok) {
+            const access = accessResult.access;
+            // If run_id is still null, try the resolution seam now that we have access.
+            if (run_id === null && deps.resolveRunId) {
+                try {
+                    run_id = await deps.resolveRunId(access, binding) ?? null;
+                }
+                catch {
+                    run_id = null;
+                }
+            }
             let rawConfig;
             try {
-                rawConfig = await fetchGateConfig(accessResult.access);
+                rawConfig = await fetchGateConfig(access);
             }
             catch {
                 rawConfig = undefined;
@@ -404,9 +459,9 @@ export async function observePrCiFromPollResponse(commitRef, pollResponse, deps
                 const evaluation = evaluateDoneGate(gateConfig, binding, snapshot, now());
                 if (evaluation.met) {
                     result.gate_met = true;
-                    const gateEvent = buildGateMetEventInput(binding, evaluation);
+                    const gateEvent = buildGateMetEventInput(binding, evaluation, run_id, worker_id);
                     if (gateEvent !== null) {
-                        const gateDecision = emitIfNew(gateEvent, {
+                        const gateDecision = await emitIfNew(gateEvent, {
                             event_type: "gate.met",
                             repo: binding.repo,
                             pr_number: binding.pr_number,
@@ -425,3 +480,47 @@ export async function observePrCiFromPollResponse(commitRef, pollResponse, deps
     }
     return result;
 }
+// ---------------------------------------------------------------------------
+// Dispatch run_id resolution seam (Approach B: binding → ticket → dispatch)
+// ---------------------------------------------------------------------------
+/** Extract a Jira ticket key from a git branch name, e.g. `feature/BAPI-437-slug` → `BAPI-437`. */
+function extractTicketKeyFromRef(headRef) {
+    if (!headRef)
+        return null;
+    const match = /([A-Z][A-Z0-9]+-\d+)/i.exec(headRef);
+    return match ? match[1].toUpperCase() : null;
+}
+/**
+ * Resolve the dispatch `run_id` for a PR binding by extracting the ticket key
+ * from `binding.head_ref`, listing active epic runs, and searching each epic's
+ * dispatch rows for a match. Returns `null` when the lookup yields no result or
+ * any step fails — the producer never crashes on a resolution failure.
+ *
+ * Intended to be injected as `PrCiProducerDeps.resolveRunId` at call sites
+ * that lack `BAPI_CONDUCTOR_RUN_ID` in the environment (git-hook / CI-poll
+ * contexts). A production `fetchImpl` is optional; defaults to the global fetch.
+ */
+export async function resolveDispatchRunIdForBinding(access, binding, fetchImpl = fetch) {
+    const ticketKey = extractTicketKeyFromRef(binding.head_ref);
+    if (!ticketKey)
+        return null;
+    let activeRuns;
+    try {
+        activeRuns = await fetchActiveEpicRuns(access, fetchImpl);
+    }
+    catch {
+        return null;
+    }
+    for (const run of activeRuns) {
+        try {
+            const state = await fetchEpicRunState(access, run.epic_key, fetchImpl);
+            const dispatch = state.dispatches.find((d) => d.ticket_key === ticketKey && d.run_id !== null);
+            if (dispatch?.run_id)
+                return dispatch.run_id;
+        }
+        catch {
+            // Skip this epic on any error; try the next one.
+        }
+    }
+    return null;
+}

package/build/conductor/pr-review-producer.js

@@ -0,0 +1,116 @@
+/**
+ * PR review event production (BAPI-440).
+ *
+ * Polls the backend-owned review-status endpoint and emits `review.passed` /
+ * `review.changes_requested` exactly once per stable review state (deduped by
+ * review_state_hash). A poll failure never emits `review.changes_requested`
+ * (mirroring the CI rule that a failed poll is never a failed check).
+ *
+ * This module is pure of VCS credentials — the backend endpoint owns them.
+ */
+import { GIT_CI_PRODUCER, REVIEW_CHANGES_REQUESTED, REVIEW_PASSED, } from "./git-ci-types.js";
+import { evaluateReviewCondition, normalizeReviewSnapshot } from "./done-gate.js";
+import { fetchPrReviewStatus } from "./bridge-api-client.js";
+import { emitConductorEventIfNew } from "./producer-ledger.js";
+export const REVIEW_PRODUCER_OBSERVED_VIA = "pr-review-producer";
+// ---------------------------------------------------------------------------
+// Event builders
+// ---------------------------------------------------------------------------
+/**
+ * Build a `review.passed` or `review.changes_requested` event input from a
+ * normalized snapshot, or `null` when neither outcome is determinable.
+ */
+export function buildReviewObservationEventInput(binding, snapshot, eventType, reason, runId = null, workerId = null) {
+    return {
+        source: "review",
+        type: eventType,
+        subject: binding.subject,
+        run_id: runId,
+        worker_id: workerId,
+        producer: GIT_CI_PRODUCER,
+        observed_via: REVIEW_PRODUCER_OBSERVED_VIA,
+        data: {
+            summary: eventType === REVIEW_PASSED
+                ? `Review passed for ${binding.subject}`
+                : `Review changes requested for ${binding.subject}`,
+            status: eventType === REVIEW_PASSED ? "passed" : "changes_requested",
+            details: {
+                repo: binding.repo,
+                pr_number: binding.pr_number,
+                head_sha: binding.head_sha,
+                review_decision: snapshot.review_decision,
+                approvals: snapshot.approvals,
+                sticky_verdict: snapshot.sticky_verdict,
+                review_state_hash: snapshot.review_state_hash,
+                reason,
+            },
+        },
+    };
+}
+/**
+ * Observe the PR review state for an already-resolved binding/access/config.
+ * Polls the backend endpoint, normalizes the snapshot, evaluates the review
+ * condition, and emits the appropriate event through the dedupe layer.
+ *
+ * A poll failure or unavailable envelope returns `null` snapshot and emits
+ * nothing — it is never a `review.changes_requested`.
+ */
+export async function observeReviewWithResolved(binding, access, gateConfig, deps = {}) {
+    const fetchStatus = deps.fetchReviewStatus ?? fetchPrReviewStatus;
+    const emitIfNew = deps.emitIfNew ?? emitConductorEventIfNew;
+    const run_id = deps.env?.BAPI_CONDUCTOR_RUN_ID?.trim() || null;
+    const worker_id = deps.env?.BAPI_CONDUCTOR_WORKER_ID?.trim() || null;
+    const result = {
+        snapshot: null,
+        review_passed_emitted: false,
+        review_changes_requested_emitted: false,
+        reason: "observed",
+    };
+    // Find the review_state condition from the gate config (if present).
+    const reviewCondition = gateConfig.conditions.find((c) => c.type === "review_state") ?? null;
+    // CI-only gate: no review condition, skip the backend round-trip entirely.
+    if (reviewCondition === null) {
+        result.reason = "no-review-condition";
+        return result;
+    }
+    // Poll the backend endpoint. A thrown error means unavailable — fail open,
+    // emit nothing (mirroring CI producer rule: "a failed poll is never a failure").
+    let rawStatus;
+    try {
+        rawStatus = await fetchStatus(access, binding.pr_number);
+    }
+    catch {
+        result.reason = "review-poll-failed";
+        return result;
+    }
+    const snapshot = normalizeReviewSnapshot(rawStatus);
+    result.snapshot = snapshot;
+    if (snapshot === null) {
+        result.reason = "review-snapshot-unavailable";
+        return result;
+    }
+    // Evaluate the review condition (reviewCondition is non-null — null is handled above).
+    const evalResult = evaluateReviewCondition(reviewCondition, snapshot);
+    const baseDimensions = {
+        repo: binding.repo,
+        pr_number: binding.pr_number,
+        head_sha: binding.head_sha,
+        review_state_hash: snapshot.review_state_hash,
+    };
+    if (evalResult.changesRequested) {
+        const event = buildReviewObservationEventInput(binding, snapshot, REVIEW_CHANGES_REQUESTED, evalResult.reason, run_id, worker_id);
+        const decision = await emitIfNew(event, { event_type: REVIEW_CHANGES_REQUESTED, ...baseDimensions });
+        result.review_changes_requested_emitted = decision.emitted;
+        result.reason = "review changes requested";
+    }
+    else if (evalResult.passed) {
+        const event = buildReviewObservationEventInput(binding, snapshot, REVIEW_PASSED, evalResult.reason, run_id, worker_id);
+        const decision = await emitIfNew(event, { event_type: REVIEW_PASSED, ...baseDimensions });
+        result.review_passed_emitted = decision.emitted;
+        result.reason = "review passed";
+    }
+    else {
+        result.reason = `review not yet passed: ${evalResult.reason}`;
+    }
+    return result;
+}

package/build/conductor/producer-ledger.js

@@ -59,13 +59,13 @@ const LEDGER_SCAN_MAX_PAGES = 200;
  * full details object is visible. Malformed/non-matching events are skipped; the
  * scan never throws.
  */
-export function eventAlreadyExists(dedupeKey, deps = {}) {
+export async function eventAlreadyExists(dedupeKey, deps = {}) {
     const pollEvents = deps.pollEvents ?? ((options) => pollConductorEvents(options));
     let sinceSeq = 1;
     for (let page = 0; page < LEDGER_SCAN_MAX_PAGES; page += 1) {
         let result;
         try {
-            result = pollEvents({ since_seq: sinceSeq, data_mode: "full", limit: LEDGER_SCAN_PAGE_LIMIT });
+            result = await pollEvents({ since_seq: sinceSeq, data_mode: "full", limit: LEDGER_SCAN_PAGE_LIMIT });
         }
         catch {
             return false;
@@ -95,10 +95,10 @@ export function eventAlreadyExists(dedupeKey, deps = {}) {
  * under `data.details`, then emits. A duplicate-id constraint thrown by a racing
  * producer is classified as a duplicate rather than surfaced as a failure.
  */
-export function emitConductorEventIfNew(input, dimensions, deps = {}) {
+export async function emitConductorEventIfNew(input, dimensions, deps = {}) {
     const emitEvent = deps.emitEvent ?? emitConductorEvent;
     const dedupeKey = makeProducerDedupeKey(dimensions);
-    if (eventAlreadyExists(dedupeKey, deps)) {
+    if (await eventAlreadyExists(dedupeKey, deps)) {
         return { emitted: false, reason: "duplicate" };
     }
     const eventId = makeStableProducerEventId(dedupeKey);
@@ -113,7 +113,7 @@ export function emitConductorEventIfNew(input, dimensions, deps = {}) {
         details: { ...existingDetails, dedupe_key: dedupeKey },
     };
     try {
-        emitEvent({ ...input, id: eventId, data });
+        await emitEvent({ ...input, id: eventId, data });
         return { emitted: true, event_id: eventId };
     }
     catch (error) {

package/build/conductor/spec-review-producer.js

@@ -0,0 +1,88 @@
+/**
+ * Pre-implementation SPEC re-review verdict production (BAPI-445 Phase 2).
+ *
+ * Emits the spec re-review verdict (`spec_review.passed` /
+ * `spec_review.changes_requested`) into the LOCAL conductor ledger, correlated
+ * to the spec-review run via `BAPI_CONDUCTOR_RUN_ID`. The Epic Supervisor's
+ * reconcile pass folds these signals: `passed` → `reviewing → ready` (proceed to
+ * implementation), `changes_requested` → `blocked` (escalate; do NOT implement).
+ *
+ * Why this is a LOCAL producer, not a backend webhook change: the conductor
+ * ledger is a per-worker SQLite file (`~/.config/bridge/events.db`). The
+ * Heroku-hosted Bridge API backend has no access to it. So — exactly like the
+ * PR-review producer ({@link ./pr-review-producer}) — the verdict is emitted by
+ * the LOCAL spec-review run, whose environment carries `BAPI_CONDUCTOR_RUN_ID`
+ * (injected at dispatch time by {@link ../review-tickets}.orchestrateReviewTickets
+ * when an epic identity is present). This corrects the original BAPI-445 plan,
+ * which proposed emitting from the backend review webhook
+ * (`code_writer_jira.py`) — that path cannot reach the worker-local ledger.
+ *
+ * The verdict family is kept DISTINCT from the PR-review `review.passed` /
+ * `review.changes_requested` verdicts (BAPI-440) so a spec-review outcome is
+ * never mis-folded as the implementation PR's review state (Obstacle 2).
+ */
+// TODO(BAPI-445 Phase 2 integration): `emitSpecReviewVerdict` is the verdict
+// EMISSION primitive but currently has no caller. Until the review-ticket
+// completion flow derives a pass/changes-requested decision from the critique
+// and calls this function, no `spec_review.*` event is ever written.
+//
+// This is FAIL-SAFE, not fail-open: epic-state.ts `rebuildObservedState` filters
+// a review run's incidental terminals (run.stopped, …) out of folding, so a
+// completed review with NO verdict leaves the ticket in `reviewing` rather than
+// advancing it to `ready` and dispatching implementation. The reconcile
+// liveness-recovery / escalation path then surfaces the stranded ticket for
+// operator attention. Only an explicit `spec_review.passed` proceeds and only
+// `spec_review.changes_requested` blocks — so wiring this producer in is what
+// makes the gate ACTIVE; without it, opted-in tickets hold safely instead of
+// silently implementing against the review's wishes.
+import { SPEC_REVIEW_CHANGES_REQUESTED, SPEC_REVIEW_PASSED } from "./git-ci-types.js";
+import { emitConductorEventIfNew } from "./producer-ledger.js";
+/** Producer + observed-via identifiers stamped onto emitted spec-review events. */
+export const SPEC_REVIEW_PRODUCER = "spec-review-producer";
+/**
+ * Build a `spec_review.passed` / `spec_review.changes_requested` event input for
+ * a ticket's spec re-review verdict, correlated to the review run via `runId`.
+ */
+export function buildSpecReviewVerdictEventInput(ticketKey, verdict, reason, runId = null, workerId = null) {
+    const eventType = verdict === "passed" ? SPEC_REVIEW_PASSED : SPEC_REVIEW_CHANGES_REQUESTED;
+    return {
+        source: "review",
+        type: eventType,
+        subject: ticketKey,
+        run_id: runId,
+        worker_id: workerId,
+        producer: SPEC_REVIEW_PRODUCER,
+        observed_via: SPEC_REVIEW_PRODUCER,
+        data: {
+            summary: verdict === "passed"
+                ? `Spec re-review passed for ${ticketKey}`
+                : `Spec re-review requested changes for ${ticketKey}`,
+            status: verdict,
+            details: { ticket_key: ticketKey, reason },
+        },
+    };
+}
+/**
+ * Emit a spec re-review verdict for `ticketKey` into the local conductor ledger,
+ * correlated to the spec-review run via `BAPI_CONDUCTOR_RUN_ID` (read from the
+ * injected env). Idempotent: deduped by `event_type` + `run_id`, so re-emitting
+ * the same run's verdict is a no-op. A missing run id still emits (uncorrelated)
+ * but is logged in the result so callers can detect the misconfiguration.
+ */
+export async function emitSpecReviewVerdict(ticketKey, verdict, reason, deps = {}) {
+    const emitIfNew = deps.emitIfNew ?? emitConductorEventIfNew;
+    const run_id = deps.env?.BAPI_CONDUCTOR_RUN_ID?.trim() || null;
+    const worker_id = deps.env?.BAPI_CONDUCTOR_WORKER_ID?.trim() || null;
+    const eventType = verdict === "passed" ? SPEC_REVIEW_PASSED : SPEC_REVIEW_CHANGES_REQUESTED;
+    const event = buildSpecReviewVerdictEventInput(ticketKey, verdict, reason, run_id, worker_id);
+    const decision = await emitIfNew(event, {
+        event_type: eventType,
+        run_id: run_id ?? "",
+    });
+    return {
+        emitted: decision.emitted,
+        event_type: eventType,
+        run_id,
+        reason: run_id ? reason : `${reason} (warning: no BAPI_CONDUCTOR_RUN_ID — verdict uncorrelated)`,
+    };
+}