@aperant/framework 0.17.0 → 0.20.0

package/src/cli/produce/saga.mjs

@@ -0,0 +1,303 @@
+/**
+ * @internal
+ * produce/saga.mjs — the plan→execute→verify→review→ship saga + FORWARD
+ * compensators (M4, ID-M4-01 / ID-M4-02, the ID-10 semantic).
+ *
+ * The loop is modeled as a saga: each phase declares a FORWARD compensator via
+ * `resolveCompensator(phase)`. The load-bearing invariant is that EVERY
+ * compensator carries `rolls_back_merged_pr: false` — a compensator is always a
+ * forward compensating transaction. A failed verify/review/ship SHIPS A REVERT
+ * (a new forward commit/branch) + reopens the task + re-plans; it NEVER un-merges
+ * history other agents/humans already built on. plan/execute are pre-merge and
+ * simply reopen + re-plan (no revert), still `rolls_back_merged_pr: false`.
+ *
+ * The CLI RECORDS the phase transitions + the forward-compensator DESCRIPTOR; it
+ * NEVER executes the revert / reopen / re-plan (that dispatch is OOS — the CLI
+ * records + computes, the skill/dispatch acts, exactly as M2 records
+ * oracle/probe results while the skill drives the LLM steps).
+ *
+ * `projectSaga` folds `produce.saga.*` ONLY into per-milestone phase state — a
+ * SEPARATE fold PARALLEL to the roadmap projection (projection.mjs still folds
+ * `produce.roadmap.*` ONLY, so the M1/M2/M3 blindness invariant holds: a saga
+ * compensation never mutates a milestone's `done` roadmap status).
+ */
+
+import {
+	appendProduceEvent,
+	readImplementerFamily,
+	readProduceRunEventsMatching,
+} from './events.mjs'
+import { normalizeFamily, resolveProbeFamily } from './probe-family.mjs'
+
+/** The ordered saga phases (ID-M4-01). Mirrors ALLOWED_SAGA_PHASES in event-schema.mjs. */
+export const SAGA_PHASES = ['plan', 'execute', 'verify', 'review', 'ship']
+
+/**
+ * The declared FORWARD-compensator table (ID-M4-02). EVERY descriptor carries
+ * `rolls_back_merged_pr: false` — a compensator is always forward. plan/execute
+ * are pre-merge (reopen + re-plan, no revert); verify/review/ship SHIP A REVERT
+ * + reopen + re-plan. The CLI records the descriptor kind; it never emits a
+ * rollback / history-rewrite instruction.
+ */
+const COMPENSATORS = {
+	plan: {
+		kind: 'rewrite_plan',
+		reopens_task: true,
+		ships_revert: false,
+		rolls_back_merged_pr: false,
+	},
+	execute: {
+		kind: 'discard_branch_replan',
+		reopens_task: true,
+		ships_revert: false,
+		rolls_back_merged_pr: false,
+	},
+	verify: {
+		kind: 'revert_reopen_replan',
+		reopens_task: true,
+		ships_revert: true,
+		rolls_back_merged_pr: false,
+	},
+	review: {
+		kind: 'revert_reopen_replan',
+		reopens_task: true,
+		ships_revert: true,
+		rolls_back_merged_pr: false,
+	},
+	ship: {
+		kind: 'revert_reopen_replan',
+		reopens_task: true,
+		ships_revert: true,
+		rolls_back_merged_pr: false,
+	},
+}
+
+/**
+ * Resolve the declared FORWARD compensator for a saga phase. Returns a fresh
+ * copy (the table is never handed out mutable) or null for an out-of-vocabulary
+ * phase (fail-closed). The returned descriptor ALWAYS has
+ * `rolls_back_merged_pr: false` (ID-M4-02).
+ *
+ * @param {string} phase
+ * @returns {{ kind: string, reopens_task: boolean, ships_revert: boolean, rolls_back_merged_pr: boolean } | null}
+ */
+export function resolveCompensator(phase) {
+	const descriptor = COMPENSATORS[phase]
+	if (!descriptor) return null
+	return { ...descriptor }
+}
+
+/**
+ * Append `produce.saga.phase_entered` for a milestone's saga phase. Validates
+ * the phase against SAGA_PHASES fail-closed (an out-of-vocabulary phase appends
+ * nothing).
+ *
+ * @param {string} projectDir
+ * @param {{ runId: string, milestoneId: string, phase: string }} args
+ * @returns {{ ok: true, phase: string } | { ok: false, reason: string }}
+ */
+export function enterPhase(projectDir, { runId, milestoneId, phase }) {
+	if (!SAGA_PHASES.includes(phase)) return { ok: false, reason: 'invalid_phase' }
+	appendProduceEvent(projectDir, 'produce.saga.phase_entered', {
+		run_id: runId,
+		milestone_id: milestoneId,
+		phase,
+	})
+	return { ok: true, phase }
+}
+
+/**
+ * Append `produce.saga.phase_completed` for a milestone's saga phase. Validates
+ * the phase against SAGA_PHASES fail-closed.
+ *
+ * @param {string} projectDir
+ * @param {{ runId: string, milestoneId: string, phase: string }} args
+ * @returns {{ ok: true, phase: string } | { ok: false, reason: string }}
+ */
+export function completePhase(projectDir, { runId, milestoneId, phase }) {
+	if (!SAGA_PHASES.includes(phase)) return { ok: false, reason: 'invalid_phase' }
+	appendProduceEvent(projectDir, 'produce.saga.phase_completed', {
+		run_id: runId,
+		milestone_id: milestoneId,
+		phase,
+	})
+	return { ok: true, phase }
+}
+
+/**
+ * Fire the FORWARD compensator for a failed saga phase (ID-M4-02). Resolves the
+ * declared compensator, then appends `produce.saga.compensated {run_id,
+ * milestone_id, phase, compensator: <descriptor.kind>, reason}` — carrying the
+ * descriptor KIND, never a rollback instruction. Validates the phase fail-closed.
+ * The CLI records the forward compensator; it does NOT execute the revert/reopen/
+ * re-plan (OOS dispatch) and NEVER mutates the roadmap milestone status.
+ *
+ * @param {string} projectDir
+ * @param {{ runId: string, milestoneId: string, phase: string, reason?: string }} args
+ * @returns {{ ok: true, phase: string, compensator: object } | { ok: false, reason: string }}
+ */
+export function compensatePhase(projectDir, { runId, milestoneId, phase, reason }) {
+	if (!SAGA_PHASES.includes(phase)) return { ok: false, reason: 'invalid_phase' }
+	const compensator = resolveCompensator(phase)
+	appendProduceEvent(projectDir, 'produce.saga.compensated', {
+		run_id: runId,
+		milestone_id: milestoneId,
+		phase,
+		compensator: compensator.kind,
+		reason: reason || `compensate_${phase}`,
+	})
+	return { ok: true, phase, compensator }
+}
+
+/**
+ * Record a provider-diverse review verdict (ID-M4-04 / ID-08). The review-path
+ * analog of evidence-oracle.mjs::recordOracleVerdict. REFUSES fail-closed when
+ * the reviewer family equals the recorded implementer family (a same-family
+ * reviewer rubber-stamps its own family's work) or when no implementer family is
+ * recorded (ID-M2-02). On acceptance appends `produce.saga.reviewed {run_id,
+ * milestone_id, reviewer_family, verdict}`.
+ *
+ * @param {string} projectDir
+ * @param {{ runId: string, milestoneId: string, verdict: string, reviewerFamily: string }} args
+ * @returns {{ ok: true, verdict: string, reviewer_family: string, implementer_family: string }
+ *   | { ok: false, reason: string, implementer_family?: string | null }}
+ */
+export function recordReview(projectDir, { runId, milestoneId, verdict, reviewerFamily }) {
+	if (verdict !== 'pass' && verdict !== 'fail') return { ok: false, reason: 'invalid_verdict' }
+	if (!reviewerFamily) return { ok: false, reason: 'no_reviewer_family' }
+
+	const implementerFamily = readImplementerFamily(projectDir, runId, milestoneId)
+	if (!implementerFamily)
+		return { ok: false, reason: 'no_recorded_implementer', implementer_family: null }
+
+	// Cross-family enforcement (normalized so claude-code === claude).
+	if (normalizeFamily(reviewerFamily) === normalizeFamily(implementerFamily))
+		return { ok: false, reason: 'same_family_reviewer', implementer_family: implementerFamily }
+
+	appendProduceEvent(projectDir, 'produce.saga.reviewed', {
+		run_id: runId,
+		milestone_id: milestoneId,
+		reviewer_family: reviewerFamily,
+		verdict,
+	})
+
+	return {
+		ok: true,
+		verdict,
+		reviewer_family: reviewerFamily,
+		implementer_family: implementerFamily,
+	}
+}
+
+/**
+ * Resolve a REVIEW-phase reviewer family DISJOINT from the recorded implementer
+ * (ID-M4-04 / ID-08), a THIN wrapper over the M2 `resolveProbeFamily` — NO
+ * duplicated cross-family / partner-map / model-resolution logic. Reads the
+ * implementer family from the recorded `produce.milestone.implemented` trail
+ * (fail-closed when absent). Returns the resolution with `probe_family` surfaced
+ * as `reviewer_family`. Provider is an OUTPUT; the model is resolved LIVE (null
+ * for self-resolving families) — never a hardcoded id.
+ *
+ * @param {string} projectDir
+ * @param {{ runId: string, milestoneId: string, hostFamily?: string | null, availableFamilies?: string[] }} args
+ * @returns {{ available: boolean, reviewer_family: string | null, implementer_family: string | null,
+ *   transport_hint: object | null, model: string | null, source: string | null, reason: string | null }}
+ */
+export function resolveReviewer(projectDir, { runId, milestoneId, hostFamily, availableFamilies }) {
+	const implementerFamily = readImplementerFamily(projectDir, runId, milestoneId)
+	if (!implementerFamily) {
+		return {
+			available: false,
+			reviewer_family: null,
+			implementer_family: null,
+			transport_hint: null,
+			model: null,
+			source: null,
+			reason: 'no_recorded_implementer',
+		}
+	}
+
+	const resolution = resolveProbeFamily({ implementerFamily, hostFamily, availableFamilies })
+	// Surface the disjoint probe family as the reviewer family (same selection).
+	const { probe_family, ...rest } = resolution
+	return { ...rest, reviewer_family: probe_family, implementer_family: implementerFamily }
+}
+
+/**
+ * Fold the run's `produce.saga.*` events into per-milestone saga state — a
+ * SEPARATE fold parallel to the roadmap projection (the roadmap projection folds
+ * `produce.roadmap.*` ONLY, so saga events never enter the roadmap the Showrunner
+ * re-reads each tick — blindness preserved, ID-M4-01). Deterministic: two folds
+ * of the same log yield the identical saga state; `updated_at` is the last folded
+ * event's timestamp.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {{
+ *   run_id: string,
+ *   milestones: Array<{
+ *     milestone_id: string,
+ *     current_phase: string | null,
+ *     phase_status: 'entered' | 'completed' | null,
+ *     phases: Record<string, 'entered' | 'completed'>,
+ *     last_compensated: { phase: string | null, compensator: string | null, reason: string | null } | null,
+ *     reviewed: { reviewer_family: string | null, verdict: string | null } | null,
+ *   }>,
+ *   updated_at: string | null,
+ * }}
+ */
+export function projectSaga(projectDir, runId) {
+	const events = readProduceRunEventsMatching(projectDir, runId, (op) =>
+		op.startsWith('produce.saga.'),
+	)
+	const byId = new Map()
+	const order = []
+	let updatedAt = null
+
+	const ensure = (id) => {
+		if (!byId.has(id)) {
+			byId.set(id, {
+				milestone_id: id,
+				current_phase: null,
+				phase_status: null,
+				phases: {},
+				last_compensated: null,
+				reviewed: null,
+			})
+			order.push(id)
+		}
+		return byId.get(id)
+	}
+
+	for (const e of events) {
+		const d = e.data || {}
+		const id = typeof d.milestone_id === 'string' ? d.milestone_id : null
+		if (!id) continue
+		const m = ensure(id)
+		const phase = typeof d.phase === 'string' ? d.phase : null
+
+		if (e.op === 'produce.saga.phase_entered' && phase) {
+			m.current_phase = phase
+			m.phase_status = 'entered'
+			m.phases[phase] = 'entered'
+		} else if (e.op === 'produce.saga.phase_completed' && phase) {
+			m.current_phase = phase
+			m.phase_status = 'completed'
+			m.phases[phase] = 'completed'
+		} else if (e.op === 'produce.saga.compensated') {
+			m.last_compensated = {
+				phase,
+				compensator: typeof d.compensator === 'string' ? d.compensator : null,
+				reason: typeof d.reason === 'string' ? d.reason : null,
+			}
+		} else if (e.op === 'produce.saga.reviewed') {
+			m.reviewed = {
+				reviewer_family: typeof d.reviewer_family === 'string' ? d.reviewer_family : null,
+				verdict: typeof d.verdict === 'string' ? d.verdict : null,
+			}
+		}
+		if (typeof e.t === 'string') updatedAt = e.t
+	}
+
+	return { run_id: runId, milestones: order.map((id) => byId.get(id)), updated_at: updatedAt }
+}