Session：日志与 append

493export type SessionEvent<T extends SessionEventType = SessionEventType> = {
494  [K in SessionEventType]: {
495    type: K
497    seq: SessionSeq       // 单调序号：seq = log.length（品牌数字）
499    time: number          // Unix epoch ms
500    data: SessionEventMap[K]
511    ignorable?: true  // 读者不认识此 type 时可安全跳过
512  } & (K extends SurfaceEventType ? {
516}[T]

310'system/message': { turn: number; step: number; message: SystemMessage }

23export interface SessionMessageProjectionContext {
25  nodes: readonly SessionSeq[]      // 当前产生消息的事件序（模型可见顺序）
27  events: readonly SessionEvent[]   // 连续事件窗口；candidate 及其后的条目不是已提交输入
29  baseSeq: SessionLogOffset         // 窗口首事件的绝对序号
31  messages: ReadonlyMap<SessionSeq, Message>   // 已投影的消息，按原事件 seq 索引
32}
35export interface SessionMessageProjection<T extends SessionEventType = SessionEventType> {
37  type: T   // 由 @messageProjection 在 SessionEventMap 里声明事件类型即注册键
47  project(event: SessionEvent<T>, context: SessionMessageProjectionContext): ReadonlyMap<SessionSeq, Message>
48}

439export type SurfaceEventType =
440  | 'system/message'
441  | 'developer/message'   // 0.1.7 新增第 5 个成员
442  | 'user/message'
443  | 'assistant/message'
444  | 'tool/result'

311  'developer/message': {
312    turn: number
313    step: number
314    message: DeveloperMessage
315    /** Earlier request/header defining every tool addition; required exactly when additions are present. */工具增删必须指向定义它们的 header
316    headerSeq?: SessionSeq
317  }

720  append<T extends SessionEventType>(
721    type: T,
722    data: SessionEventMap[T],
723    ...opts: T extends SurfaceEventType ? [opts: SurfaceIntent<T>] : []
724  ): SessionEvent<T> {
725    const surfaceOpts: SurfaceIntent | undefined = opts[0]
726    const surfaceMetadata = {
727      ...surfaceOpts?.sourceEventSeqs === undefined ? {} : { sourceEventSeqs: ... },
728      ...surfaceOpts?.surfaceOp === undefined ? {} : { surfaceOp: ... },
729    }
730    const dataSnapshot = snapshotJsonValue(data)
732    if (dataSnapshot === undefined) {
733      throw new Error(`session event "${type}" carries non-JSON-serializable data`)
734    }
735    assertSupportedRequestHeader(type, dataSnapshot, ...)
736    const surfaceMetadataSnapshot = snapshotJsonValue(surfaceMetadata)
740    if (entry?.appending) {
741      throw new Error('session append cannot reenter while another append is being published')
742    }
743    const event = deepFreeze({
743      type,
744      seq: SessionSeq(this.log.length),     // ← seq 契约的落点（品牌化）
745      time: Date.now(),
746      data: dataSnapshot,
747      ...(surfaceMetadataSnapshot as ...),
748    } as unknown as SessionEvent<T>)
749    validateSessionEventData(event, ...)   // 0.1.5 新增：字段级校验0.1.7 起还管 developer/tool 变更
750    this.surfaceManager.validateNext(event as SessionEvent)
752    if (entry !== undefined) entry.appending = true
753    try {
754      let callbacks: SessionCallback[] | undefined
755      const callbackArgs: unknown[] = [this, event]
756      if (entry !== undefined) {
757        callbacks = collectSessionCallbacks(entry.emitCtx, [entry.carrier, 'session/event', ...callbackArgs])
758      }
759      this.log.push(event as SessionEvent)   // ① 进日志 = 已提交
760      this.eventsSnapshot = undefined   // ② 快照失效
761      if (callbacks !== undefined && entry !== undefined) {
762        invokeContainedSessionObservers(entry.emitCtx, 'session/event', entry.id, callbackArgs, callbacks)  // ③ 通知
763      }
764      return event
765    } finally {
766      if (entry !== undefined) {
767        entry.appending = false
768        if (entry.detachRequested && !entry.announcing) entry.detach()
769      }
770    }
771  }

516function planSurfaceEvent(
517  state: SurfaceFoldState,
518  event: SessionEvent,
519  expectedSeq: SessionSeq,
520  events: readonly SessionEvent[],
521  baseSeq: SessionLogOffset,
522  projections: readonly SessionMessageProjection[],
523): SurfacePlan | undefined {
524  if (event.seq !== expectedSeq) {
525    throw new Error(`session event seq ${event.seq} is not contiguous; expected ${expectedSeq}`)
526  }
527  const surfaceOp = validateSurfaceMetadata(event)
528  assertDeveloperHeader(event, events, baseSeq)   // 0.1.7 新增校验 tool 变更引用
529  const projection = projections.find(item => item.type === event.type)0.1.6：投影优先
530  if (projection !== undefined) {
531    return { kind: 'project', projection, messages: projection.project(event, {
532      nodes: state.nodes, events, baseSeq, messages: state.projectedMessages,
533    }) }
534  }
541  if (surfaceOp === undefined) return
542  if (surfaceOp === 'append') {
543    return { kind: 'append', seq: event.seq }
544  }
545  const range = replacementRange(state, surfaceOp)
546  assertSourceEventReferences(event, range.shadowedSeqs)
547  assertToolResultRewrite(event, range.shadowedSeqs, events, baseSeq)
548  assertSystemHeadRewrite(event, state, range.startIdx, range.shadowedSeqs, events, baseSeq)
549  return { kind: 'replace', seq: event.seq, start: surfaceOp.startSeq, end: surfaceOp.endSeq, ...range }
553}

548  private constructor(
549    id: SessionId,
550    seed?: readonly SessionEvent[],
551    header?: SessionHeader,
552    mode: 'snapshot' | SessionSeedEventState = 'snapshot',
553    suppliedInheritedEventCount?: SessionLogOffset,
554  ) {
555    const restoredHeader = mode === 'snapshot' ? undefined : validateRestoredSessionHeader(id, header)
556    if (seed !== undefined) {
564      for (const [index, source] of seed.entries()) {
567        const snapshot = mode === 'snapshot' ? snapshotJsonValue(source) : source
568        if (snapshot === undefined) {
569          throw new Error(`seed event at index ${index} is not losslessly JSON-serializable`)
570        }
571        assertSessionEventEnvelope(snapshot, index)
572        if (snapshot.seq !== index) {
573          throw new Error(`seed event at index ${index} has seq ${snapshot.seq} (expected ${index}); seed must be contiguous from 0`)
574        }
579          this.surfaceManager.validateNext(snapshot)
584        this.log.push(mode === 'snapshot' ? deepFreeze(snapshot) : snapshot)
586    this.firstLiveSeq = SessionLogOffset(this.log.length)
587    this.header = restoredHeader ?? snapshotSessionHeader(id, header)
588    if (this.header.isSeeded && seed === undefined) {
589      throw new Error('seeded session requires an explicit constructor seed')
590    }
594    const inheritedEventCount = SessionLogOffset(suppliedInheritedEventCount ?? 0)
595    if (!this.header.isSeeded && inheritedEventCount !== 0) {
596      throw new Error('unseeded session inherited event count must be 0')
597    }
606    this.inheritedEventCount = inheritedEventCount
610    if (seed !== undefined && mode === 'snapshot' && this.header.isSeeded) {0.1.3-alpha.2 起
617      this.append('session/end-seed', { inherited: true })   // 带 inherited 标记
614    } else if (seed !== undefined && this.log.at(-1)?.type !== 'session/end-seed') {
613      this.append('session/end-seed', {})
614    }
615  }