feature(session): session surface

packages/invariants/src/index.ts

@@ -62,6 +62,8 @@ interface SessionTrace {
    * `step/end` — a result must arrive in the same step as its call.
    */
   pendingCalls: Set<string>
+  /** Every seq seen so far — validates `sourceEventSeqs` references. */
+  knownSeqs: Set<number>
 }
 
 /**
@@ -105,6 +107,30 @@ function checkEvent(trace: SessionTrace, event: SessionEvent): void {
   }
   trace.lastSeq = event.seq
 
+  // --- Surface invariants ---
+  if (event.sourceEventSeqs !== undefined) {
+    if (event.sourceEventSeqs.length === 0) {
+      throw new InvariantError('sourceEventSeqs must not be empty when present')
+    }
+    const unique = new Set(event.sourceEventSeqs)
+    if (unique.size !== event.sourceEventSeqs.length) {
+      throw new InvariantError('sourceEventSeqs must not contain duplicates')
+    }
+    for (const ref of event.sourceEventSeqs) {
+      if (ref >= event.seq) {
+        throw new InvariantError(`sourceEventSeqs must reference earlier events: ${ref} >= current seq ${event.seq}`)
+      }
+      if (!trace.knownSeqs.has(ref)) {
+        throw new InvariantError(`sourceEventSeqs references unknown seq ${ref}`)
+      }
+    }
+  }
+  if (event.surfaceOp !== undefined && typeof event.surfaceOp !== 'string') {
+    if (event.surfaceOp.start > event.surfaceOp.end) {
+      throw new InvariantError(`surface replace: start ${event.surfaceOp.start} must be <= end ${event.surfaceOp.end}`)
+    }
+  }
+
   // Boundary/step-scoped events have explicit cases; every OTHER event type —
   // including plugin-added (merge-extensible) SessionEventMap keys — is caught
   // by the `default` and must be turn-enclosed (ADR 0017). No assertNever: an
@@ -185,6 +211,8 @@ function checkEvent(trace: SessionTrace, event: SessionEvent): void {
       break
     }
   }
+  // Track every seq seen — used above to validate sourceEventSeqs references.
+  trace.knownSeqs.add(event.seq)
 }
 
 /** Legal agent status transitions (the only state machine the loop guarantees). */
@@ -216,7 +244,7 @@ export function apply(ctx: Context, config: Config = {}): void {
   // (re-)apply seeds the baseline, so a reload never produces a false positive.
   const lastStatus = new WeakMap<Agent, AgentStatus>()
 
-  const freshTrace = (): SessionTrace => ({ lastSeq: -1, openTurn: null, openStep: null, pendingCalls: new Set() })
+  const freshTrace = (): SessionTrace => ({ lastSeq: -1, openTurn: null, openStep: null, pendingCalls: new Set(), knownSeqs: new Set() })
 
   /** Build (or rebuild) a session's trace by replaying its whole log; freeze it. */
   const seedSession = (session: Session): SessionTrace => {

packages/invariants/tests/invariants.spec.ts

@@ -387,3 +387,115 @@ describe('HMR safety', () => {
     expect(Object.isFrozen(session.events[0])).toBe(false)
   })
 })
+
+describe('surface invariants', () => {
+  it('accepts well-formed surface metadata', async () => {
+    const { ctx } = await setup()
+    const session = ctx.sessions.create()
+    // Events must be turn-enclosed and step-scoped events need an open step.
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('step/start', { turn: 1, step: 1 })
+    expect(() => {
+      session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+      session.append('assistant/message', { turn: 1, step: 1, content: [] }, { surfaceOp: 'append', sourceEventSeqs: [1] })
+    }).not.toThrow()
+  })
+
+  it('accepts replace surface op', async () => {
+    const { ctx } = await setup()
+    const session = ctx.sessions.create()
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('step/start', { turn: 1, step: 1 })
+    session.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    session.append('assistant/message', { turn: 1, step: 1, content: [] }, { surfaceOp: { op: 'replace', start: 2, end: 2 }, sourceEventSeqs: [2] })
+    // no throw — well-formed replace op
+  })
+
+  it('rejects empty sourceEventSeqs', async () => {
+    const { ctx } = await setup()
+    const session = ctx.sessions.create()
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    expect(() => {
+      session.append('assistant/message', { turn: 1, step: 1, content: [] }, { surfaceOp: 'append', sourceEventSeqs: [] })
+    }).toThrow(InvariantError)
+  })
+
+  it('rejects duplicate sourceEventSeqs', async () => {
+    const { ctx } = await setup()
+    const session = ctx.sessions.create()
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    expect(() => {
+      session.append('assistant/message', { turn: 1, step: 1, content: [] }, { surfaceOp: 'append', sourceEventSeqs: [1, 1] })
+    }).toThrow(/must not contain duplicates/)
+  })
+
+  it('rejects sourceEventSeqs referencing the event itself (self-reference)', async () => {
+    const { ctx } = await setup()
+    const session = ctx.sessions.create()
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) // seq 0
+    // The next event is seq 1. Referencing its own seq fails on "must reference
+    // earlier events" (the check order is: earlier first, then unknown).
+    expect(() => {
+      session.append('assistant/message', { turn: 1, step: 1, content: [] }, { surfaceOp: 'append', sourceEventSeqs: [1] })
+    }).toThrow(/must reference earlier/)
+  })
+
+  it('accepts sourceEventSeqs referencing a valid earlier event', async () => {
+    // Positive test: ref < current seq and ref is in knownSeqs → passes.
+    const { ctx } = await setup()
+    const session = ctx.sessions.create()
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('step/start', { turn: 1, step: 1 })
+    // seqs so far: 0, 1. The next event at seq 2 references seq 1 → valid.
+    expect(() => {
+      session.append('assistant/message', { turn: 1, step: 1, content: [] }, { surfaceOp: 'append', sourceEventSeqs: [1] })
+    }).not.toThrow()
+  })
+
+  it('rejects sourceEventSeqs referencing a far-future seq', async () => {
+    const { ctx } = await setup()
+    const session = ctx.sessions.create()
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    expect(() => {
+      session.append('assistant/message', { turn: 1, step: 1, content: [] }, { surfaceOp: 'append', sourceEventSeqs: [99] })
+    }).toThrow(/must reference earlier/)
+  })
+
+  it('rejects sourceEventSeqs referencing unknown seq (gap in event log)', async () => {
+    // The unknown-seq check fires when a ref passes the "earlier" test but is
+    // not in knownSeqs — only possible with a gap in seqs. We create a gap by
+    // directly manipulating the private log array to skip a seq.
+    const { ctx } = await setup()
+    const session = ctx.sessions.create()
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('step/start', { turn: 1, step: 1 })
+    // Push a fake event at seq 3 into the internal log, creating a gap at seq 2.
+    // The invariants plugin replays session.events on every append, so it sees
+    // this gap during trace reconstruction.
+    ;(session as unknown as { log: unknown[] }).log.push({
+      type: 'assistant/chunk',
+      seq: 3,
+      time: Date.now(),
+      data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'x' } },
+    })
+    // Now the log has seqs 0, 1, 3 (gap at 2). Append at what session believes
+    // is seq 3 (log.length). Reference seq 2: passes earlier (2 < 3) but not
+    // in knownSeqs ({0, 1, 3} — gap at 2).
+    expect(() => {
+      session.append('assistant/message', { turn: 1, step: 1, content: [] }, { surfaceOp: 'append', sourceEventSeqs: [2] })
+    }).toThrow(/unknown seq 2/)
+  })
+
+  it('rejects replace op with start > end', async () => {
+    const { ctx } = await setup()
+    const session = ctx.sessions.create()
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('step/start', { turn: 1, step: 1 })
+    session.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 2
+    // start > end is invalid (reversed order).
+    expect(() => {
+      session.append('assistant/message', { turn: 1, step: 1, content: [] }, { surfaceOp: { op: 'replace', start: 2, end: 1 }, sourceEventSeqs: [2] })
+    }).toThrow(/must be <= end/)
+  })
+})