front-cpu 0.1.1

package/src/stages/RES.ts

@@ -0,0 +1,46 @@
+/**
+ * RES阶段：Response（响应处理）
+ */
+
+import type { QueuedInstruction } from '../types'
+import { InstructionStatus } from '../types'
+import { isInstructionCancelled } from '../utils/InstructionCancellation'
+
+export class ResponseStage {
+  /**
+   * 处理网络响应
+   * 
+   * @returns success: 是否成功, shouldRetry: 是否需要重试, discarded: 是否被丢弃
+   */
+  processResponse(
+    instruction: QueuedInstruction,
+    error?: Error
+  ): { success: boolean; shouldRetry: boolean; discarded?: boolean } {
+    // 标记RES阶段时间戳
+    instruction.timestamps.RES = Date.now()
+
+    // 🔥 检查指令是否已被取消（可能在 SCH 或 EX 阶段被取消）
+    if (isInstructionCancelled(instruction)) {
+      // 保持 CANCELLED 状态，不要改为 FAILED
+      // instruction.status 已经是 CANCELLED
+      
+      // 返回 discarded 标志
+      return { 
+        success: false, 
+        shouldRetry: false,
+        discarded: true 
+      }
+    }
+
+    if (error) {
+      // 失败处理（简化版：不实现重试）
+      instruction.status = InstructionStatus.FAILED
+      instruction.error = error
+      return { success: false, shouldRetry: false }
+    }
+
+    // 成功
+    instruction.status = InstructionStatus.RESPONDED
+    return { success: true, shouldRetry: false }
+  }
+}

package/src/stages/SCH.ts

@@ -0,0 +1,331 @@
+/**
+ * SCH阶段：Scheduler（指令调度器）
+ */
+
+import type { QueuedInstruction } from '../types'
+import { InstructionStatus } from '../types'
+import { getISA } from '../isa'
+import type { ResourceAccessMode, SchedulingStrategy } from '../isa/types'
+import { resourceStrategyRegistry } from '../scheduling/ResourceStrategyRegistry'
+import { cancelInstruction } from '../utils/InstructionCancellation'
+
+export class SchedulerStage {
+  private pendingQueue: QueuedInstruction[] = []
+  private activeInstructions: Map<string, QueuedInstruction> = new Map()
+  // 资源 -> 调度策略映射
+  private resourceStrategies: Map<string, SchedulingStrategy> = new Map()
+  // 资源 -> 读写锁状态
+  private resourceLocks: Map<string, ResourceLockState> = new Map()
+  private maxConcurrency: number
+
+  constructor(maxConcurrency: number = 10) {
+    this.maxConcurrency = maxConcurrency
+  }
+
+  /**
+   * 调度循环（tick）
+   */
+  tick(): void {
+    // 🔥 边检查边发射，避免批量检查导致的竞态条件
+    // 每发射一个指令，资源状态立即更新，下一个指令检查时会看到最新状态
+
+    let issued = true
+    while (issued) {
+      issued = false
+
+      for (const instruction of this.pendingQueue) {
+        if (this.canIssue(instruction)) {
+          this.issue(instruction)
+          issued = true
+          break // 跳出for循环，重新检查pending队列
+        }
+      }
+
+      // 如果这轮没有发射任何指令，说明所有指令都被阻塞了，退出
+    }
+  }
+
+  /**
+   * 添加指令到调度队列
+   */
+  addInstruction(instruction: QueuedInstruction): void {
+    this.pendingQueue.push(instruction)
+  }
+
+  /**
+   * 判断指令是否可以发射
+   */
+  private canIssue(instruction: QueuedInstruction): boolean {
+    // 检查并发数限制
+    if (this.activeInstructions.size >= this.maxConcurrency) {
+      return false
+    }
+
+    // 检查资源冲突（根据调度策略）
+    if (this.hasResourceConflict(instruction)) {
+      return false
+    }
+
+    return true
+  }
+
+  /**
+   * 获取指令的调度策略
+   */
+  private getInstructionStrategy(instruction: QueuedInstruction): SchedulingStrategy {
+    const ISA = getISA()
+    const isa = ISA[instruction.type]
+    const instructionStrategy = isa?.meta.schedulingStrategy
+    const resourceAccesses = this.getResourceAccesses(instruction)
+    
+    // 如果有多个资源，使用第一个资源的策略
+    const primaryResourceId = resourceAccesses[0]?.id
+    if (!primaryResourceId) {
+      return 'serial' // 默认
+    }
+
+    return resourceStrategyRegistry.getStrategy(primaryResourceId, instructionStrategy)
+  }
+
+  /**
+   * 发射指令
+   */
+  private issue(instruction: QueuedInstruction): void {
+    // 从pending队列移除
+    const index = this.pendingQueue.indexOf(instruction)
+    if (index !== -1) {
+      this.pendingQueue.splice(index, 1)
+    }
+
+    // 标记为issued
+    instruction.status = InstructionStatus.ISSUED
+    instruction.timestamps.SCH = Date.now()
+
+    // 加入active列表
+    this.activeInstructions.set(instruction.id, instruction)
+
+    // 记录资源的活跃指令
+    const resourceAccesses = this.getResourceAccesses(instruction)
+    const strategy = this.getInstructionStrategy(instruction)
+    
+    for (const resourceAccess of resourceAccesses) {
+      // 记录策略
+      this.resourceStrategies.set(resourceAccess.id, strategy)
+      
+      // 记录读写锁
+      const lockState = this.getOrCreateResourceLock(resourceAccess.id)
+      if (resourceAccess.mode === 'read') {
+        lockState.readers.add(instruction.id)
+      } else {
+        lockState.writers.add(instruction.id)
+      }
+    }
+  }
+
+  /**
+   * 检测资源冲突（根据调度策略）
+   */
+  private hasResourceConflict(instruction: QueuedInstruction): boolean {
+    const resourceAccesses = this.getResourceAccesses(instruction)
+    const strategy = this.getInstructionStrategy(instruction)
+
+    for (const resourceAccess of resourceAccesses) {
+      const lockState = this.resourceLocks.get(resourceAccess.id)
+      const hasActive =
+        !!lockState && (lockState.readers.size > 0 || lockState.writers.size > 0)
+
+      // out-of-order: 允许并发，不冲突
+      if (strategy === 'out-of-order') {
+        continue
+      }
+
+      // latest: 不冲突，但会取消旧指令（保留最新）
+      if (strategy === 'latest' && hasActive) {
+        this.cancelOldInstructions(resourceAccess.id, instruction.id)
+      }
+
+      // serial: 如果有活跃指令，则冲突（串行执行）
+      if (strategy === 'serial' && hasActive) {
+        return true
+      }
+
+      // read-write: 读共享、写互斥
+      if (strategy === 'read-write' && lockState) {
+        if (resourceAccess.mode === 'read') {
+          if (lockState.writers.size > 0) {
+            return true
+          }
+        } else {
+          if (lockState.writers.size > 0 || lockState.readers.size > 0) {
+            return true
+          }
+        }
+      }
+    }
+
+    return false
+  }
+
+  /**
+   * 取消旧指令（latest 策略）
+   */
+  private cancelOldInstructions(resourceId: string, newInstructionId: string): void {
+    const lockState = this.resourceLocks.get(resourceId)
+    if (!lockState) return
+
+    const activeInstructionIds = new Set<string>([
+      ...lockState.readers,
+      ...lockState.writers,
+    ])
+    
+    for (const oldInstructionId of activeInstructionIds) {
+      const oldInstruction = this.activeInstructions.get(oldInstructionId)
+      if (oldInstruction && oldInstructionId !== newInstructionId) {
+        // 使用统一的取消机制
+        cancelInstruction(
+          oldInstruction,
+          `Cancelled by latest strategy: new instruction ${newInstructionId}`,
+          'SCH'
+        )
+      }
+    }
+  }
+
+  /**
+   * 从payload中提取资源访问列表（读/写）
+   */
+  private getResourceAccesses(instruction: QueuedInstruction): NormalizedResourceAccess[] {
+    const ISA = getISA()
+    const isa = ISA[instruction.type]
+    if (!isa) {
+      return []
+    }
+
+    const rawAccesses = isa.meta.resourceIdentifier(instruction.payload)
+    const merged = new Map<string, ResourceAccessMode>()
+
+    for (const rawAccess of rawAccesses) {
+      const normalized =
+        typeof rawAccess === 'string'
+          ? { id: rawAccess, mode: 'write' as ResourceAccessMode }
+          : {
+              id: rawAccess.id,
+              mode: (rawAccess.mode ?? 'write') as ResourceAccessMode,
+            }
+
+      const existing = merged.get(normalized.id)
+      if (!existing) {
+        merged.set(normalized.id, normalized.mode)
+        continue
+      }
+
+      if (existing === 'read' && normalized.mode === 'write') {
+        merged.set(normalized.id, 'write')
+      }
+    }
+
+    return Array.from(merged, ([id, mode]) => ({ id, mode }))
+  }
+
+  /**
+   * 获取或创建资源读写锁
+   */
+  private getOrCreateResourceLock(resourceId: string): ResourceLockState {
+    let lockState = this.resourceLocks.get(resourceId)
+    if (!lockState) {
+      lockState = {
+        readers: new Set<string>(),
+        writers: new Set<string>(),
+      }
+      this.resourceLocks.set(resourceId, lockState)
+    }
+    return lockState
+  }
+
+  /**
+   * 释放指令占用的资源
+   */
+  releaseInstruction(instructionId: string): void {
+    const instruction = this.activeInstructions.get(instructionId)
+    if (!instruction) return
+
+    // 释放资源的活跃指令记录
+    const resourceAccesses = this.getResourceAccesses(instruction)
+    for (const resourceAccess of resourceAccesses) {
+      const lockState = this.resourceLocks.get(resourceAccess.id)
+      if (!lockState) {
+        continue
+      }
+
+      if (resourceAccess.mode === 'read') {
+        lockState.readers.delete(instructionId)
+      } else {
+        lockState.writers.delete(instructionId)
+        }
+        
+        // 如果该资源没有活跃指令了，清理记录
+      if (lockState.readers.size === 0 && lockState.writers.size === 0) {
+        this.resourceLocks.delete(resourceAccess.id)
+        this.resourceStrategies.delete(resourceAccess.id)
+      }
+    }
+
+    // 从active列表移除
+    this.activeInstructions.delete(instructionId)
+  }
+
+  /**
+   * 获取pending队列（用于调试）
+   */
+  getPendingQueue(): QueuedInstruction[] {
+    return [...this.pendingQueue]
+  }
+
+  /**
+   * 获取正在执行的指令列表（用于调试）
+   */
+  getActiveInstructions(): QueuedInstruction[] {
+    return Array.from(this.activeInstructions.values())
+  }
+
+  /**
+   * 获取pending队列大小
+   */
+  getPendingQueueSize(): number {
+    return this.pendingQueue.length
+  }
+
+  /**
+   * 获取活跃指令数量
+   */
+  getActiveCount(): number {
+    return this.activeInstructions.size
+  }
+
+  /**
+   * 获取所有待处理指令
+   */
+  getPendingInstructions(): QueuedInstruction[] {
+    return [...this.pendingQueue]
+  }
+
+  /**
+   * 清空调度器
+   */
+  clear(): void {
+    this.pendingQueue = []
+    this.activeInstructions.clear()
+    this.resourceStrategies.clear()
+    this.resourceLocks.clear()
+  }
+}
+
+interface ResourceLockState {
+  readers: Set<string>
+  writers: Set<string>
+}
+
+interface NormalizedResourceAccess {
+  id: string
+  mode: ResourceAccessMode
+}

package/src/stages/WB.ts

@@ -0,0 +1,127 @@
+/**
+ * WB阶段：Write Back（写回）
+ *
+ * 职责：
+ * 1. 调用 commit 函数（成功时）
+ * 2. 回滚乐观更新（失败时）
+ */
+
+import type { QueuedInstruction } from '../types'
+import { InstructionStatus } from '../types'
+import { getISA } from '../isa'
+import { cpuEventCollector, cpuConsole } from '../logging/runtime'
+
+export class WriteBackStage {
+  /**
+   * 回滚乐观更新
+   */
+  private rollbackOptimisticUpdate(instruction: QueuedInstruction): void {
+    const ISA = getISA()
+    const definition = ISA[instruction.type]
+
+    if (instruction.optimisticSnapshot && definition?.optimistic?.rollback) {
+      // 记录回滚操作
+      if (!instruction.writeBackExecution) {
+        instruction.writeBackExecution = { hasCommit: false, rollbackExecuted: true }
+      }
+      instruction.writeBackExecution.rollbackExecuted = true
+      instruction.writeBackExecution.rollbackSnapshot = instruction.optimisticSnapshot
+
+      // 🎯 记录乐观更新回滚事件
+      cpuEventCollector.onOptimisticRolledBack(
+        instruction.id,
+        instruction.type,
+        instruction.context.correlationId,
+        instruction.optimisticSnapshot,
+        '指令执行失败',
+        instruction.error
+      )
+      cpuConsole.onOptimisticRolledBack(instruction, '指令执行失败')
+
+      try {
+        definition.optimistic.rollback(instruction.optimisticSnapshot)
+      } catch (rollbackError) {
+        instruction.writeBackExecution.rollbackError =
+          rollbackError instanceof Error ? rollbackError : new Error(String(rollbackError))
+        console.error('❌ [CPU] 乐观更新回滚失败:', {
+          instructionId: instruction.id,
+          type: instruction.type,
+          error: rollbackError,
+        })
+      }
+    }
+  }
+
+  /**
+   * 写回/完成指令
+   */
+  async writeBack(instruction: QueuedInstruction, success: boolean): Promise<void> {
+    // 标记WB阶段
+    instruction.timestamps.WB = Date.now()
+
+    const ISA = getISA()
+    const definition = ISA[instruction.type]
+
+    // 初始化WB执行记录
+    instruction.writeBackExecution = {
+      hasCommit: !!(definition && definition.commit),
+      rollbackExecuted: false,
+    }
+
+    // 🔥 如果指令已被取消，只回滚不提交
+    if (instruction.cancelled) {
+      this.rollbackOptimisticUpdate(instruction)
+      return
+    }
+
+    if (success) {
+      // ==================== 成功路径 ====================
+
+      // 🔥 调用 commit 函数（如果存在）
+      if (definition && definition.commit) {
+        // 记录commit调用参数
+        instruction.writeBackExecution.commitArgs = {
+          result: instruction.result,
+          payload: instruction.payload,
+          context: instruction.context,
+          optimisticSnapshot: instruction.optimisticSnapshot,
+        }
+
+        try {
+          await definition.commit(
+            instruction.result,
+            instruction.payload,
+            instruction.context,
+            instruction.optimisticSnapshot // 🔥 传递乐观更新快照
+          )
+          instruction.writeBackExecution.commitSuccess = true
+        } catch (error) {
+          instruction.writeBackExecution.commitSuccess = false
+          instruction.writeBackExecution.commitError =
+            error instanceof Error ? error : new Error(String(error))
+
+          // commit失败 → 回滚乐观更新
+          this.rollbackOptimisticUpdate(instruction)
+
+          // 设置为失败状态
+          instruction.status = InstructionStatus.FAILED
+          instruction.error = instruction.writeBackExecution.commitError
+          return
+        }
+      }
+
+      // 成功场景
+      instruction.status = InstructionStatus.COMMITTED
+    } else {
+      // ==================== 失败路径 ====================
+
+      // 🔥 回滚乐观更新
+      this.rollbackOptimisticUpdate(instruction)
+
+      // 设置失败状态（如果不是已取消）
+      if (instruction.status !== InstructionStatus.CANCELLED) {
+        instruction.status = InstructionStatus.FAILED
+      }
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,118 @@
+/**
+ * CPU流水线核心类型定义
+ */
+
+import type { CallSource } from './logging/types'
+
+/**
+ * 流水线阶段
+ */
+export const PipelineStage = {
+  IF: 'IF', // Instruction Fetch
+  SCH: 'SCH', // Scheduler
+  EX: 'EX', // Execute
+  RES: 'RES', // Response
+  WB: 'WB', // Write Back
+} as const
+
+export type PipelineStage = (typeof PipelineStage)[keyof typeof PipelineStage]
+
+/**
+ * 指令状态
+ */
+export const InstructionStatus = {
+  PENDING: 'pending', // 在IF缓冲区等待调度
+  ISSUED: 'issued', // 已发射到EX阶段
+  EXECUTING: 'executing', // 正在执行
+  RESPONDED: 'responded', // 已收到响应
+  COMMITTED: 'committed', // 已提交完成
+  FAILED: 'failed', // 执行失败
+  CANCELLED: 'cancelled', // 被取消/丢弃（可能在任何阶段）
+} as const
+
+export type InstructionStatus = (typeof InstructionStatus)[keyof typeof InstructionStatus]
+
+/**
+ * 指令执行上下文
+ */
+export interface InstructionContext {
+  /** 指令唯一ID */
+  instructionId: string
+  /** 关联ID（用于SSE去重等） */
+  correlationId: string
+  /** 时间戳 */
+  timestamp: number
+  /** 来源 */
+  source: 'user' | 'system' | 'test'
+  /** 重试次数 */
+  retryCount: number
+  /** 调用源（哪个文件哪一行发起的指令） */
+  callSource?: CallSource
+}
+
+/**
+ * WB阶段执行信息
+ */
+export interface WriteBackExecution {
+  /** 是否有commit函数 */
+  hasCommit: boolean
+  /** commit函数调用参数 */
+  commitArgs?: {
+    result: any
+    payload: any
+    context: InstructionContext
+    optimisticSnapshot?: any
+  }
+  /** commit执行结果 */
+  commitSuccess?: boolean
+  /** commit错误信息 */
+  commitError?: Error
+  /** 是否执行了回滚 */
+  rollbackExecuted?: boolean
+  /** 回滚快照 */
+  rollbackSnapshot?: any
+  /** 回滚错误 */
+  rollbackError?: Error
+}
+
+/**
+ * 队列中的指令
+ */
+export interface QueuedInstruction<TPayload = any> {
+  /** 指令ID */
+  id: string
+  /** 指令类型 */
+  type: string
+  /** 指令负载 */
+  payload: TPayload
+  /** 执行上下文 */
+  context: InstructionContext
+  /** 当前状态 */
+  status: InstructionStatus
+  /** 各阶段时间戳 */
+  timestamps: {
+    IF?: number
+    SCH?: number
+    EX?: number
+    RES?: number
+    WB?: number
+  }
+  /** 执行结果 */
+  result?: any
+  /** 错误信息 */
+  error?: Error
+  /** 乐观更新快照（用于回滚） */
+  optimisticSnapshot?: any
+  /** WB阶段执行详情 */
+  writeBackExecution?: WriteBackExecution
+  /** 是否已取消（用于 switchMap 策略） */
+  cancelled?: boolean
+  /** 取消原因 */
+  cancelReason?: string
+  /** 取消发生的阶段 */
+  cancelledAt?: 'SCH' | 'EX' | 'RES'
+  /** 用于取消网络请求 */
+  abortController?: AbortController
+  /** 指令标签 */
+  tags?: string[]
+}

package/src/utils/InstructionCancellation.ts

@@ -0,0 +1,73 @@
+/**
+ * 指令取消管理器
+ * 
+ * 提供统一的指令取消机制，可以在任何阶段取消指令
+ */
+
+import type { QueuedInstruction } from '../types'
+import { InstructionStatus } from '../types'
+
+/**
+ * 取消指令
+ * 
+ * @param instruction 要取消的指令
+ * @param reason 取消原因
+ * @param stage 取消发生的阶段
+ */
+export function cancelInstruction(
+  instruction: QueuedInstruction,
+  reason: string,
+  stage: 'SCH' | 'EX' | 'RES'
+): void {
+  // 标记为已取消
+  instruction.cancelled = true
+  instruction.cancelReason = reason
+  instruction.cancelledAt = stage
+  instruction.status = InstructionStatus.CANCELLED
+
+  // 设置错误信息
+  instruction.error = new Error(`[${stage}] ${reason}`)
+  
+  // 🔥 实际取消网络请求
+  if (instruction.abortController && !instruction.abortController.signal.aborted) {
+    instruction.abortController.abort(instruction.cancelReason)
+  }
+}
+
+/**
+ * 检查指令是否已被取消
+ */
+export function isInstructionCancelled(instruction: QueuedInstruction): boolean {
+  return instruction.cancelled === true || instruction.status === InstructionStatus.CANCELLED
+}
+
+/**
+ * 获取取消信息（用于日志）
+ */
+export function getCancellationInfo(instruction: QueuedInstruction): {
+  cancelled: boolean
+  reason?: string
+  stage?: string
+} {
+  return {
+    cancelled: isInstructionCancelled(instruction),
+    reason: instruction.cancelReason,
+    stage: instruction.cancelledAt,
+  }
+}
+
+/**
+ * 批量取消指令（用于 switchMap 等场景）
+ */
+export function cancelInstructions(
+  instructions: QueuedInstruction[],
+  reason: string,
+  stage: 'SCH' | 'EX' | 'RES'
+): void {
+  for (const instruction of instructions) {
+    if (!isInstructionCancelled(instruction)) {
+      cancelInstruction(instruction, reason, stage)
+    }
+  }
+}
+