@sqdr2/dsh-fusion 0.0.0-stage → 0.3.2

package/src/profile/resolve.ts

@@ -0,0 +1,131 @@
+import { readFileSync } from 'node:fs'
+import type { Digest, PairProfile, PhysicalRoute, RoleContextPolicy } from '../contracts.js'
+import { digestOf, sha256Hex } from '../digest.js'
+import { FusionError, PROFILE_UNAVAILABLE } from '../errors.js'
+import { keepaliveChoice } from './keepalive.js'
+import { compactorChoice, profileRoutes } from './compactor.js'
+
+const PLACEHOLDERS = new Set(['__AUTHORIZED_PROVIDER__', '__EXACT_MODEL_ID__', '__EXACT_WORKER_ID__', '__EXISTING_PROJECT_POLICY__'])
+
+export interface PromptBundle {
+  lead: string
+  worker: string
+  compact: string
+}
+
+export interface ResolvedProfile {
+  readonly profile: PairProfile
+  readonly prompts: PromptBundle
+}
+
+export interface ProfileCatalog {
+  readonly authorizedRoutes: readonly PhysicalRoute[]
+}
+
+function isPlaceholder(route: PhysicalRoute): boolean {
+  return PLACEHOLDERS.has(route.provider) || PLACEHOLDERS.has(route.model)
+}
+
+function asPolicy(raw: RoleContextPolicy | undefined, fallback: RoleContextPolicy): RoleContextPolicy {
+  const policy = {
+    targetInputTokens: raw?.targetInputTokens ?? fallback.targetInputTokens,
+    reserveOutputTokens: raw?.reserveOutputTokens ?? fallback.reserveOutputTokens,
+    minSafetyTokens: raw?.minSafetyTokens ?? fallback.minSafetyTokens,
+    safetyFraction: raw?.safetyFraction ?? fallback.safetyFraction,
+    compactToFraction: raw?.compactToFraction ?? fallback.compactToFraction,
+    evidenceReadTokens: raw?.evidenceReadTokens ?? fallback.evidenceReadTokens,
+    maxToolVisibleTokens: raw?.maxToolVisibleTokens ?? fallback.maxToolVisibleTokens,
+  }
+  for (const key of ['targetInputTokens', 'reserveOutputTokens', 'evidenceReadTokens', 'maxToolVisibleTokens'] as const) {
+    if (!Number.isSafeInteger(policy[key]) || policy[key] <= 0) throw new FusionError(PROFILE_UNAVAILABLE, `Invalid context policy: ${key}`)
+  }
+  if (!Number.isSafeInteger(policy.minSafetyTokens) || policy.minSafetyTokens < 0
+    || !Number.isFinite(policy.safetyFraction) || policy.safetyFraction < 0 || policy.safetyFraction >= 1
+    || !Number.isFinite(policy.compactToFraction) || policy.compactToFraction <= 0 || policy.compactToFraction >= 1) {
+    throw new FusionError(PROFILE_UNAVAILABLE, 'Invalid context safety or compaction policy')
+  }
+  return policy
+}
+
+const LEAD_DEFAULT: RoleContextPolicy = {
+  // The final guard always intersects this soft target with the registered
+  // physical model window, output reservation and safety margin. A fixed 32k
+  // default can reject the real Host's system prompt/tools before its first
+  // request; do not impose an undocumented smaller window by default.
+  targetInputTokens: Number.MAX_SAFE_INTEGER,
+  reserveOutputTokens: 8_000,
+  minSafetyTokens: 2_048,
+  safetyFraction: 0.05,
+  compactToFraction: 0.5,
+  evidenceReadTokens: 4_000,
+  maxToolVisibleTokens: 6_000,
+}
+
+const WORKER_DEFAULT: RoleContextPolicy = {
+  ...LEAD_DEFAULT,
+  compactToFraction: 0.55,
+  evidenceReadTokens: 8_000,
+  maxToolVisibleTokens: 8_000,
+}
+
+export function promptDigests(prompts: PromptBundle): PairProfile['promptDigests'] {
+  return {
+    lead: sha256Hex(prompts.lead),
+    worker: sha256Hex(prompts.worker),
+    compact: sha256Hex(prompts.compact),
+  }
+}
+
+export function completeProfile(raw: Record<string, unknown>, prompts: PromptBundle): PairProfile {
+  const lead = raw.lead as PhysicalRoute
+  const worker = raw.worker as PhysicalRoute
+  const context = (raw.context ?? {}) as Partial<PairProfile['context']>
+  const promptHash = promptDigests(prompts)
+  const cacheKeepalive = keepaliveChoice(raw.cacheKeepalive)
+  const compactor = compactorChoice(raw.compactor)
+  if (raw.interactionMode !== undefined && raw.interactionMode !== 'model-like') throw new Error('Unknown Fusion interaction mode')
+  if (raw.workflowPolicy !== undefined && (!['enforced-v1', 'enforced-v2', 'enforced-v3'].includes(String(raw.workflowPolicy)) || raw.interactionMode !== 'model-like')) throw new Error('Unknown Fusion workflow policy')
+  const profile: PairProfile = {
+    schemaVersion: 1,
+    id: String(raw.id),
+    version: String(raw.version),
+    digest: '' as Digest,
+    enabled: raw.enabled === true,
+    quality: (raw.quality as PairProfile['quality']) ?? 'experimental',
+    ...(raw.interactionMode === 'model-like' ? { interactionMode: 'model-like' as const } : {}),
+    ...(raw.workflowPolicy === 'enforced-v1' || raw.workflowPolicy === 'enforced-v2' || raw.workflowPolicy === 'enforced-v3' ? { workflowPolicy: raw.workflowPolicy } : {}),
+    lead,
+    worker,
+    workerUpgradePath: (raw.workerUpgradePath as PhysicalRoute[]) ?? [],
+    promptDigests: promptHash,
+    context: {
+      lead: asPolicy(context.lead, LEAD_DEFAULT),
+      worker: asPolicy(context.worker, WORKER_DEFAULT),
+    },
+    dataPolicyId: String(raw.dataPolicyId ?? ''),
+    evidenceCampaignIds: (raw.evidenceCampaignIds as string[]) ?? [],
+    ...(cacheKeepalive === undefined ? {} : { cacheKeepalive }),
+    ...(compactor === undefined ? {} : { compactor }),
+  }
+  return { ...profile, digest: digestOf(profile) }
+}
+
+export function resolveProfile(raw: Record<string, unknown>, prompts: PromptBundle, catalog: ProfileCatalog): ResolvedProfile {
+  const profile = completeProfile(raw, prompts)
+  if (!profile.enabled) {
+    throw new FusionError(PROFILE_UNAVAILABLE, `profile ${profile.id} is disabled`)
+  }
+  if (profileRoutes(profile).some(isPlaceholder) || PLACEHOLDERS.has(profile.dataPolicyId)) {
+    throw new FusionError(PROFILE_UNAVAILABLE, `profile ${profile.id} still has placeholder routes`)
+  }
+  const authorized = (route: PhysicalRoute) =>
+    catalog.authorizedRoutes.some(item => item.provider === route.provider && item.model === route.model)
+  if (!profileRoutes(profile).every(authorized)) {
+    throw new FusionError(PROFILE_UNAVAILABLE, `profile ${profile.id} routes are not authorized on this Host`)
+  }
+  return { profile, prompts }
+}
+
+export function loadJsonObject(path: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>
+}

package/src/prompts.ts

@@ -0,0 +1,32 @@
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { PromptBundle } from './profile/resolve.js'
+import { promptDigests } from './profile/resolve.js'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+export function defaultPromptDir(): string {
+  return join(here, '..', 'prompts')
+}
+
+export function loadPromptBundle(dir = defaultPromptDir()): PromptBundle {
+  return {
+    lead: readFileSync(join(dir, 'lead.md'), 'utf8'),
+    worker: readFileSync(join(dir, 'worker.md'), 'utf8'),
+    compact: readFileSync(join(dir, 'compact.md'), 'utf8'),
+  }
+}
+
+export function loadModelPromptBundle(dir = defaultPromptDir()): PromptBundle {
+  return {
+    lead: readFileSync(join(dir, 'model-lead.md'), 'utf8'),
+    worker: readFileSync(join(dir, 'model-worker.md'), 'utf8'),
+    compact: readFileSync(join(dir, 'compact.md'), 'utf8'),
+  }
+}
+
+export function promptManifest(dir = defaultPromptDir()) {
+  const prompts = loadPromptBundle(dir)
+  return { prompts, digests: promptDigests(prompts) }
+}

package/src/recovery/reconcile.ts

@@ -0,0 +1,38 @@
+import type { OutboxRow, SessionId } from '../contracts.js'
+import { NEEDS_REPAIR, OUTCOME_UNKNOWN } from '../errors.js'
+
+export type ChildPersistence = 'present' | 'missing' | 'corrupt'
+
+export interface RecoveryScan {
+  readonly outbox: OutboxRow
+  readonly childPersistence: ChildPersistence
+  readonly effectKnown: boolean | null
+  readonly reportAlreadyRecorded: boolean
+  readonly parentDelivered: boolean
+}
+
+export type RecoveryDecision =
+  | { action: 'retry-prepare'; child: SessionId }
+  | { action: 'resume-child'; child: SessionId }
+  | { action: 'return-stored-result' }
+  | { action: 'needs-repair'; code: typeof NEEDS_REPAIR }
+  | { action: 'outcome-unknown'; code: typeof OUTCOME_UNKNOWN }
+  | { action: 'idle' }
+
+export function reconcile(scan: RecoveryScan): RecoveryDecision {
+  if (scan.reportAlreadyRecorded && !scan.parentDelivered) return { action: 'return-stored-result' }
+  if (scan.reportAlreadyRecorded && scan.parentDelivered) return { action: 'idle' }
+  if (scan.effectKnown === null && (scan.outbox.state === 'dispatched' || scan.outbox.state === 'claimed')) {
+    return { action: 'outcome-unknown', code: OUTCOME_UNKNOWN }
+  }
+  if (scan.outbox.state === 'prepared' && scan.childPersistence === 'missing' && scan.outbox.reservedChild) {
+    return { action: 'retry-prepare', child: scan.outbox.reservedChild }
+  }
+  if (scan.outbox.state === 'accepted' && scan.childPersistence !== 'present') {
+    return { action: 'needs-repair', code: NEEDS_REPAIR }
+  }
+  if ((scan.outbox.state === 'accepted' || scan.outbox.state === 'claimed') && scan.outbox.reservedChild) {
+    return { action: 'resume-child', child: scan.outbox.reservedChild }
+  }
+  return { action: 'idle' }
+}

package/src/review/dispatch.ts

@@ -0,0 +1,48 @@
+import type { FusionEvent, ReviewTicket, TaskId } from '../contracts.js'
+import { EVENT_CONFLICT, FusionError } from '../errors.js'
+import type { ReviewClassification } from './protocol.js'
+import { captureTicket, createReviewTicket, resultFromCapturedTicket, reviewOutboxRow, reviewRequestedEvent } from './ticket.js'
+import type { FusionStore } from '../task/store.js'
+
+/**
+ * Offline producer: persist the captured ticket and outbox row before any adapter send.
+ * The model callback may read the latest TaskState only for seq/CAS.
+ */
+export function persistReviewRequest(
+  store: FusionStore,
+  taskId: TaskId,
+  ids: { ticketId: string; requestId: string },
+  payloadRef: string,
+): Readonly<ReviewTicket> {
+  const current = store.load(taskId)
+  if (!current) throw new FusionError(EVENT_CONFLICT, `unknown task ${taskId}`)
+  const ticket = captureTicket(createReviewTicket(current, ids))
+  const requested = reviewRequestedEvent(current, current.seq + 1, ids)
+  store.transact(taskId, current.seq, persisted => ({
+    events: [requested],
+    outbox: [...persisted.outbox, reviewOutboxRow(ticket, payloadRef)],
+  }))
+  return ticket
+}
+
+export function loadReviewOutboxByRequestId(store: FusionStore, taskId: TaskId, requestId: string) {
+  const row = store.outbox(taskId).find(item => item.requestId === requestId || item.ticket?.requestId === requestId)
+  if (!row?.ticket) throw new FusionError(EVENT_CONFLICT, `review outbox missing for ${requestId}`)
+  return { row, ticket: captureTicket(row.ticket) }
+}
+
+export function appendCapturedReviewResult(
+  store: FusionStore,
+  taskId: TaskId,
+  ticket: Readonly<ReviewTicket>,
+  outcome: { requestId: string; terminalEvidenceRef: string; classification: ReviewClassification },
+): ReturnType<FusionStore['append']> {
+  const current = store.load(taskId)
+  if (!current) throw new FusionError(EVENT_CONFLICT, `unknown task ${taskId}`)
+  const event: FusionEvent = resultFromCapturedTicket(ticket, outcome, {
+    eventId: `review-completed-${ticket.requestId}-${current.seq + 1}`,
+    seq: current.seq + 1,
+    createdAt: new Date().toISOString(),
+  })
+  return store.append(taskId, current.revision, [event])
+}

package/src/review/protocol.ts

@@ -0,0 +1,212 @@
+export type ReviewStatus = 'complete' | 'incomplete' | 'not_required' | 'failed'
+
+export type ReviewDecision = 'approve' | 'rework' | 'needs-decision' | 'REVIEW_INCOMPLETE'
+
+export type ExecutionPath = 'direct' | 'forced_fusion' | 'fusion_auto'
+
+export type ReviewTermination = 'success' | 'truncated' | 'aborted' | 'error' | 'filtered' | 'unknown'
+
+export interface ReviewClassification {
+  reviewStatus: ReviewStatus
+  decision: ReviewDecision | 'not_required'
+  protocolComplete: boolean
+  /** True only after a substitute artifact was actually delivered. */
+  fallbackUsed: boolean
+  /** True when a fallback or retry is still required. */
+  fallbackRequired: boolean
+  termination: ReviewTermination
+  reasons: readonly string[]
+}
+
+export interface ReviewAttemptFields {
+  artifactPass: boolean
+  executionPath: ExecutionPath
+  leadReviewStatus: ReviewStatus
+  finishReason: string | null
+  protocolComplete: boolean
+  fallbackUsed: boolean
+  deliveredArtifactSource: string | null
+}
+
+const VALID_DECISIONS = new Set(['approve', 'accept', 'rework', 'needs-decision'])
+
+const SUCCESS_REASONS = new Set(['stop', 'end_turn', 'end-turn', 'tool_calls', 'tool_call', 'completed', 'success'])
+const TRUNCATED_REASONS = new Set(['length', 'max_tokens', 'max_token'])
+const ABORTED_REASONS = new Set(['aborted', 'abort', 'cancelled', 'canceled', 'cancel'])
+const ERROR_REASONS = new Set(['error', 'internal_error', 'server_error'])
+const FILTERED_REASONS = new Set(['content_filter', 'content-filter', 'filtered', 'contentfilter'])
+
+function normalizeFinishReason(finishReason: string | null | undefined): string | null {
+  if (finishReason === null || finishReason === undefined) return null
+  const trimmed = finishReason.trim().toLowerCase()
+  return trimmed.length ? trimmed : null
+}
+
+function terminationFromFinishReason(finishReason: string | null): ReviewTermination | null {
+  if (finishReason === null) return null
+  if (SUCCESS_REASONS.has(finishReason)) return 'success'
+  if (TRUNCATED_REASONS.has(finishReason)) return 'truncated'
+  if (ABORTED_REASONS.has(finishReason)) return 'aborted'
+  if (ERROR_REASONS.has(finishReason)) return 'error'
+  if (FILTERED_REASONS.has(finishReason)) return 'filtered'
+  return 'unknown'
+}
+
+export function normalizeTermination(input: {
+  finishReason?: string | null
+  termination?: ReviewTermination
+  completeEvidence?: boolean
+}): ReviewTermination {
+  const finishReason = normalizeFinishReason(input.finishReason)
+  const fromFinish = terminationFromFinishReason(finishReason)
+  if (input.termination && fromFinish && input.termination !== fromFinish) {
+    return 'unknown'
+  }
+  if (input.termination) return input.termination
+  if (fromFinish) return fromFinish
+  return input.completeEvidence === true ? 'success' : 'unknown'
+}
+
+function parsedDecision(parsed: unknown): string | undefined {
+  if (!parsed || typeof parsed !== 'object') return undefined
+  const decision = (parsed as { decision?: unknown }).decision
+  return typeof decision === 'string' ? decision.trim().toLowerCase() : undefined
+}
+
+function incomplete(
+  reasons: readonly string[],
+  termination: ReviewTermination,
+  reviewStatus: ReviewStatus = 'incomplete',
+): ReviewClassification {
+  return {
+    reviewStatus,
+    decision: 'REVIEW_INCOMPLETE',
+    protocolComplete: false,
+    fallbackUsed: false,
+    fallbackRequired: true,
+    termination,
+    reasons,
+  }
+}
+
+/**
+ * Lead review is fail-closed. Only an explicit success termination plus a
+ * versioned accept/rework/needs-decision structure can complete the protocol.
+ * DIRECT skips review.
+ */
+export function classifyReview(input: {
+  executionPath: ExecutionPath
+  finishReason?: string | null
+  termination?: ReviewTermination
+  completeEvidence?: boolean
+  rawText?: string | null
+  parsed?: unknown
+}): ReviewClassification {
+  if (input.executionPath === 'direct') {
+    return {
+      reviewStatus: 'not_required',
+      decision: 'not_required',
+      protocolComplete: true,
+      fallbackUsed: false,
+      fallbackRequired: false,
+      termination: 'success',
+      reasons: ['direct path does not require Lead review'],
+    }
+  }
+
+  const reasons: string[] = []
+  const termination = normalizeTermination(input)
+  if (termination === 'truncated') reasons.push(`finish_reason=${normalizeFinishReason(input.finishReason) ?? 'truncated'}`)
+  if (termination === 'aborted') reasons.push('termination=aborted')
+  if (termination === 'error') reasons.push('termination=error')
+  if (termination === 'filtered') reasons.push('termination=filtered')
+  if (termination === 'unknown') reasons.push('termination=unknown; parsed text is not success evidence')
+
+  const raw = input.rawText ?? ''
+  if (!raw.trim()) reasons.push('empty review output')
+
+  const decision = parsedDecision(input.parsed)
+  if (input.parsed !== undefined && input.parsed !== null && !decision) {
+    reasons.push('illegal review structure')
+  } else if (decision && !VALID_DECISIONS.has(decision)) {
+    reasons.push(`illegal review decision ${decision}`)
+  }
+
+  if (termination === 'truncated' || termination === 'unknown') {
+    return incomplete(reasons.length ? reasons : [`termination=${termination}`], termination)
+  }
+  if (termination === 'aborted' || termination === 'error' || termination === 'filtered') {
+    return incomplete(reasons, termination, 'failed')
+  }
+
+  if (reasons.length) {
+    return incomplete(reasons, termination)
+  }
+
+  if (decision === 'rework') {
+    return {
+      reviewStatus: 'complete',
+      decision: 'rework',
+      protocolComplete: true,
+      fallbackUsed: false,
+      fallbackRequired: false,
+      termination,
+      reasons: [],
+    }
+  }
+  if (decision === 'needs-decision') {
+    return {
+      reviewStatus: 'complete',
+      decision: 'needs-decision',
+      protocolComplete: true,
+      fallbackUsed: false,
+      fallbackRequired: false,
+      termination,
+      reasons: [],
+    }
+  }
+  if (decision === 'approve' || decision === 'accept') {
+    return {
+      reviewStatus: 'complete',
+      decision: 'approve',
+      protocolComplete: true,
+      fallbackUsed: false,
+      fallbackRequired: false,
+      termination,
+      reasons: [],
+    }
+  }
+
+  return incomplete(['review decision missing'], termination)
+}
+
+/** Map classifier output onto the reducer event decision. */
+export function toReducerReviewDecision(
+  classification: ReviewClassification,
+): 'accept' | 'rework' | 'needs-decision' | 'REVIEW_INCOMPLETE' {
+  if (classification.decision === 'approve') return 'accept'
+  if (classification.decision === 'rework') return 'rework'
+  if (classification.decision === 'needs-decision') return 'needs-decision'
+  return 'REVIEW_INCOMPLETE'
+}
+
+export function reviewAttemptFields(input: {
+  artifactPass: boolean
+  executionPath: ExecutionPath
+  classification: ReviewClassification
+  finishReason?: string | null
+  deliveredArtifactSource?: string | null
+}): ReviewAttemptFields {
+  const deliveredArtifactSource = input.deliveredArtifactSource ?? null
+  return {
+    artifactPass: input.artifactPass,
+    executionPath: input.executionPath,
+    leadReviewStatus: input.classification.reviewStatus,
+    finishReason: input.finishReason ?? null,
+    protocolComplete: input.classification.protocolComplete,
+    fallbackUsed: Boolean(deliveredArtifactSource) && (
+      input.classification.fallbackRequired || input.classification.fallbackUsed
+    ),
+    deliveredArtifactSource,
+  }
+}

package/src/review/ticket.ts

@@ -0,0 +1,166 @@
+import type {
+  FusionEvent,
+  OutboxRow,
+  ReportSubject,
+  ReviewReadinessReceipt,
+  ReviewResultV2,
+  ReviewTicket,
+  TaskId,
+  WorkerReport,
+} from '../contracts.js'
+import { OperationId } from '../contracts.js'
+import { digestOf } from '../digest.js'
+import { EVENT_CONFLICT, FusionError } from '../errors.js'
+import type { ReviewClassification } from './protocol.js'
+import { toReducerReviewDecision } from './protocol.js'
+import type { TaskState } from '../task/state.js'
+
+function requireThat(value: unknown, code: string): asserts value {
+  if (!value) throw new FusionError(EVENT_CONFLICT, code)
+}
+
+function freeze<T>(value: T): Readonly<T> {
+  if (value && typeof value === 'object') {
+    for (const child of Object.values(value as Record<string, unknown>)) freeze(child)
+    Object.freeze(value)
+  }
+  return value as Readonly<T>
+}
+
+export function reportSubject(taskId: TaskId, report: WorkerReport): ReportSubject {
+  const reportDigest = digestOf(report)
+  return {
+    taskId,
+    workOrderId: report.workOrderId,
+    revision: report.revision,
+    reportId: `report:${reportDigest}`,
+    reportDigest,
+    snapshot: report.snapshot,
+  }
+}
+
+export function sameSubject(left: ReportSubject, right: ReportSubject): boolean {
+  return digestOf(left) === digestOf(right)
+}
+
+export function reviewReadinessReceipt(subject: ReportSubject): ReviewReadinessReceipt {
+  const receipt = {
+    subject,
+    receiptId: `ready:${subject.reportDigest}`,
+    verdict: 'review-ready' as const,
+    receiptDigest: '' as ReviewReadinessReceipt['receiptDigest'],
+  }
+  return { ...receipt, receiptDigest: digestOf({ subject, receiptId: receipt.receiptId, verdict: receipt.verdict }) }
+}
+
+export function captureTicket(ticket: ReviewTicket): Readonly<ReviewTicket> {
+  requireThat(ticket.id && ticket.requestId && Number.isSafeInteger(ticket.generation), 'INVALID_TICKET')
+  requireThat(ticket.workOrderDigest, 'WORK_ORDER_DIGEST_REQUIRED')
+  return freeze(structuredClone(ticket))
+}
+
+export function createReviewTicket(
+  state: TaskState,
+  ids: { ticketId: string; requestId: string },
+): ReviewTicket {
+  const receipt = state.validatedReceipt
+  const workOrder = state.currentWorkOrder
+  if (!receipt) throw new FusionError(EVENT_CONFLICT, 'review ticket requires a validated report')
+  if (!workOrder) throw new FusionError(EVENT_CONFLICT, 'review ticket requires a current work order')
+  return captureTicket({
+    id: ids.ticketId,
+    requestId: ids.requestId,
+    generation: state.reviewGeneration + 1,
+    subject: receipt.subject,
+    validationDigest: digestOf(receipt),
+    workOrderDigest: digestOf(workOrder),
+  })
+}
+
+export function reviewRequestedEvent(
+  state: TaskState,
+  seq: number,
+  ids: { ticketId: string; requestId: string },
+  extras: Partial<Pick<FusionEvent, 'id' | 'revision' | 'createdAt' | 'causeId'>> = {},
+): Extract<FusionEvent, { type: 'review/requested' }> {
+  return {
+    schemaVersion: 1,
+    id: extras.id ?? `review-requested-${ids.requestId}`,
+    taskId: state.taskId,
+    seq,
+    revision: extras.revision ?? state.revision,
+    type: 'review/requested',
+    createdAt: extras.createdAt ?? new Date().toISOString(),
+    causeId: extras.causeId ?? ids.requestId,
+    payload: { ticket: createReviewTicket(state, ids) },
+  }
+}
+
+export function reviewOutboxRow(ticket: Readonly<ReviewTicket>, payloadRef: string): OutboxRow {
+  requireThat(payloadRef.length > 0, 'REVIEW_PAYLOAD_REF_REQUIRED')
+  return {
+    operationId: OperationId(`review:${ticket.requestId}`),
+    taskId: ticket.subject.taskId,
+    kind: 'review-request',
+    state: 'prepared',
+    payloadRef,
+    requestId: ticket.requestId,
+    ticket: structuredClone(ticket),
+  }
+}
+
+/** Callback constructor. No TaskState argument: the producer cannot rebind to the latest task. */
+export function resultFromCapturedTicket(
+  ticket: Readonly<ReviewTicket>,
+  outcome: {
+    requestId: string
+    terminalEvidenceRef: string
+    classification: ReviewClassification
+  },
+  envelope: { eventId: string; seq: number; createdAt: string },
+): Extract<FusionEvent, { type: 'review/completed' }> {
+  requireThat(outcome.requestId === ticket.requestId, 'REVIEW_REQUEST_MISMATCH')
+  requireThat(outcome.terminalEvidenceRef.length > 0, 'TERMINAL_EVIDENCE_REQUIRED')
+  requireThat(envelope.eventId && Number.isSafeInteger(envelope.seq) && envelope.seq > 0, 'INVALID_EVENT_ENVELOPE')
+  const classification = outcome.classification
+  requireThat(classification.decision !== 'not_required', 'DIRECT_IS_NOT_A_REVIEW_RESULT')
+  const protocolValid = classification.reviewStatus === 'complete'
+    && classification.protocolComplete
+    && classification.termination === 'success'
+  const decision = protocolValid ? toReducerReviewDecision(classification) : 'REVIEW_INCOMPLETE'
+  const binding: ReviewResultV2 = {
+    ticketId: ticket.id,
+    requestId: ticket.requestId,
+    generation: ticket.generation,
+    subject: structuredClone(ticket.subject),
+    terminalEvidenceRef: outcome.terminalEvidenceRef,
+    decision,
+    protocolValid,
+  }
+  return {
+    schemaVersion: 1,
+    id: envelope.eventId,
+    taskId: ticket.subject.taskId,
+    seq: envelope.seq,
+    revision: ticket.subject.revision,
+    type: 'review/completed',
+    createdAt: envelope.createdAt,
+    causeId: ticket.requestId,
+    payload: { decision, binding },
+  }
+}
+
+/** Call at review dispatch AND immediately before committing verified completion. */
+export function assertCurrentSubject(state: TaskState, ticket: ReviewTicket, actualSnapshot: ReportSubject['snapshot']): void {
+  const workOrder = state.currentWorkOrder
+  requireThat(workOrder, 'CURRENT_WORK_ORDER_REQUIRED')
+  requireThat(workOrder.taskId === state.taskId && workOrder.id === ticket.subject.workOrderId, 'WORK_ORDER_CHANGED')
+  requireThat(state.revision === workOrder.revision && workOrder.revision === ticket.subject.revision, 'REVISION_CHANGED')
+  requireThat(digestOf(workOrder) === ticket.workOrderDigest, 'WORK_ORDER_CHANGED')
+  requireThat(state.candidateReport && state.validatedReport && state.validatedReceipt, 'VALIDATED_CANDIDATE_REQUIRED')
+  requireThat(digestOf(reportSubject(state.taskId, state.candidateReport)) === digestOf(ticket.subject), 'CANDIDATE_CHANGED')
+  requireThat(digestOf(reportSubject(state.taskId, state.validatedReport)) === digestOf(ticket.subject), 'VALIDATED_REPORT_CHANGED')
+  requireThat(digestOf(state.validatedReceipt.subject) === digestOf(ticket.subject), 'READINESS_SUBJECT_CHANGED')
+  requireThat(digestOf(state.validatedReceipt) === ticket.validationDigest, 'READINESS_CHANGED')
+  requireThat(actualSnapshot === ticket.subject.snapshot, 'WORKSPACE_CHANGED')
+}

package/src/status.ts

@@ -0,0 +1,55 @@
+import type { ControlView } from './host/native-model-control.js'
+import type { PhysicalRoute, Role, TokenMeasurement, VerificationLevel } from './contracts.js'
+
+/** Bounded, read-only UI projection. No prompts, tool arguments or credentials. */
+export interface FusionStatus {
+  schemaVersion: 1
+  sessionId: string
+  selected: boolean
+  observedAt: string
+  task?: {
+    id: string
+    revision: number
+    stage: string
+    detail: string | null
+    /** English copies for an English DSH; optional so older records still read. */
+    stageEn?: string
+    detailEn?: string | null
+    attention: boolean
+    verification: VerificationLevel
+    workerId: string | null
+    modelControl?: ControlView
+    models: { lead: PhysicalRoute; worker: PhysicalRoute; compactor: PhysicalRoute | null }
+    usage: {
+      calls: number
+      finalCalls: number
+      provisionalCalls: number
+      unreportedCalls: number
+      compactionCalls: number
+      keepaliveCalls: number
+      /** Known subtotals only; missing request fields never become zero totals. */
+      input: UsageSubtotal
+      cacheRead: UsageSubtotal
+      output: UsageSubtotal
+      actualBilledUsd: null
+      upstreamHttpCalls: null
+      /** Where the tokens went: the point of Fusion is that most land on the cheaper Worker. */
+      byRole: Record<Role, RoleUsage>
+    }
+    /** Checks frozen on the current work order; 0 means the Lead review was the only verification. */
+    automatedChecks: number | null
+    requests: { id: string; role: Role; purpose: string; provider: string; model: string;
+      outcome: string; authority: 'none' | 'provisional' | 'final'; startedAt: string }[]
+    tools: { id: string; role: Role; name: string; state: string; failed: boolean; startedAt: string }[]
+    contexts: { role: Role; purpose: string; inputTokens: number; budget: number;
+      quality: TokenMeasurement['quality']; admitted: boolean; checkedAt: string }[]
+    pendingApprovals: number
+    unsettledTools: number
+    /** True while a human inspection is required before continue, model switch, or leaving Fusion. */
+    recovering?: boolean
+    outcomeUnknown?: boolean
+  }
+}
+
+export interface RoleUsage { calls: number; input: UsageSubtotal; cacheRead: UsageSubtotal; output: UsageSubtotal }
+export interface UsageSubtotal { knownTokens: number; reportedRequests: number; totalRequests: number }