Unify session surface validation

packages/support/invariants/README.md

@@ -4,7 +4,7 @@ Dev-mode event-contract assertions. This pure-listener plugin checks relationshi
 
 **Off in production.** Enable it in tests and the demos, where a contract violation should fail loudly. It costs nothing when not registered, and doubles as executable documentation of the event taxonomy — the assertions *are* the contract.
 
-Session itself owns immutable log storage in every composition: it takes one lossless JSON snapshot of each accepted event, deep-freezes that record, and exposes the log through immutable array snapshots. The invariants plugin checks the cross-record and cross-seam rules that storage immutability cannot express.
+Session itself owns immutable, surface-valid log storage in every composition: it takes one lossless JSON snapshot of each candidate, validates the complete surface transition, deep-freezes the accepted record, and exposes the log through immutable array snapshots. The invariants plugin checks the remaining cross-record and cross-seam rules that Session does not own.
 
 Session-log assertions run during Cordis `internal/dispatch`, while `Session.append()` is resolving the `session/event` callback snapshot but before it pushes the candidate into the log. A valid transition is staged by exact event identity and applied to the live trace only when that same committed event reaches the plugin's contained post-commit listener. A later internal dispatch check can therefore veto without advancing either the log or the invariant trace, while ordinary `session/event` observer failures remain observe-only.
 
@@ -28,7 +28,6 @@ await ctx.plugin(Invariants)
 Session log (per session):
 
 - **`seq` strictly increases** — the spine of replay equivalence.
-- **surface metadata is valid** — `surfaceOp` and `sourceEventSeqs` use the shared `dsh-session` checker for type eligibility, structural shape, nonempty unique earlier references, and complete replacement coverage.
 - **turns pair and nest** — `turn/start` opens a turn, `turn/end` closes the matching one; no overlapping turns.
 - **steps nest in turns** — `step/start` opens a step in the open turn; `step/end` closes the matching step.
 - **chunks belong to an open step** — `step/start` precedes its `assistant/chunk`s.

packages/support/invariants/src/index.ts

@@ -6,13 +6,12 @@
  * `session/event`, `agent/status`, and the scoped dispatch and request seams.
  * It is **off in production**: enable it in tests and demos, where a contract
  * violation should be a loud failure rather than a subtle one. It doubles as
- * executable documentation of the event taxonomy: these assertions and the
- * shared session validators they invoke are the contract.
+ * executable documentation of the relational event taxonomy.
  *
- * Session owns immutable log storage: it snapshots and deep-freezes every
- * accepted event at the source. This plugin checks relationships that one
- * event's types and immutability cannot express, including turn/step nesting,
- * scoped dispatch, status transitions, and request reconstructability.
+ * Session owns immutable, surface-valid log storage: it validates, snapshots,
+ * and deep-freezes every accepted event at the source. This plugin checks the
+ * remaining relationships that acceptance cannot express, including turn/step
+ * nesting, scoped dispatch, status transitions, and request reconstructability.
  *
  * @module @deepseek-ai/dsh-invariants
  */
@@ -26,9 +25,8 @@ import {
   Session,
   SessionId,
   foldRequestHeader,
-  validateSurfaceMetadata,
 } from '@deepseek-ai/dsh-session'
-import type { SessionEvent, SurfaceEventType } from '@deepseek-ai/dsh-session'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
 
 export const name = 'invariants'
 export const inject = ['sessions']
@@ -62,15 +60,6 @@ interface SessionTrace {
    * `step/end` — a result must arrive in the same step as its call.
    */
   pendingCalls: Set<CallId>
-  /** Every seq seen so far — validates `sourceEventSeqs` references. */
-  knownSeqs: Set<number>
-  /**
-   * The seqs currently on the surface linked list, in linked-list order
-   * (head to tail). A replace reorders this relative to seq order (the new
-   * node takes the replaced range's position), so range validation is
-   * positional, not by seq comparison.
-   */
-  surface: number[]
 }
 
 /** One accepted event's deferred mutation of a live session trace. */
@@ -82,12 +71,6 @@ interface SessionTraceTransition {
     | { kind: 'none' }
     | { kind: 'add' | 'delete'; callId: CallId }
     | { kind: 'clear' }
-  /** The event's mutation of the derived surface order. */
-  surface:
-    | { kind: 'none' | 'append' }
-    | { kind: 'replace'; start: number; count: number }
-  /** The committed event sequence to add to the known-sequence set. */
-  seq: number
 }
 
 /** Event payload prefix for scoped seams whose first argument names its agent. */
@@ -122,50 +105,6 @@ function validateEvent(trace: SessionTrace, event: SessionEvent): SessionTraceTr
   let nextTurn = trace.nextTurn
   let nextStep = trace.nextStep
   let pendingCalls: SessionTraceTransition['pendingCalls'] = { kind: 'none' }
-  let surface: SessionTraceTransition['surface'] = { kind: 'none' }
-
-  // --- Surface invariants ---
-  // Cast to surface-eligible event type so we can access surfaceOp and
-  // sourceEventSeqs (optional on SessionEvent, mandatory on SurfaceEvent).
-  // SurfaceEvent's mandatory surfaceOp is too strict here — we need to
-  // CHECK whether surface metadata is present, not assume it.
-  const se = event as SessionEvent<SurfaceEventType>
-  const metadataViolation = validateSurfaceMetadata(event)
-  if (metadataViolation !== undefined) throw new InvariantError(metadataViolation.message)
-
-  // Fold this event into the tracked surface linked list, validating the
-  // replace contract as we go. `append` adds a tail node; `replace` shadows a
-  // positional range — every shadowed node must appear in sourceEventSeqs.
-  let shadowed: number[] | undefined
-  if (se.surfaceOp !== undefined) {
-    if (se.surfaceOp === 'append') {
-      surface = { kind: 'append' }
-    } else {
-      const { start, end } = se.surfaceOp
-      const startIdx = trace.surface.indexOf(start)
-      if (startIdx === -1) {
-        throw new InvariantError(`surface replace: start seq ${start} is not on the surface`)
-      }
-      const endIdx = trace.surface.indexOf(end)
-      if (endIdx === -1) {
-        throw new InvariantError(`surface replace: end seq ${end} is not on the surface`)
-      }
-      if (startIdx > endIdx) {
-        throw new InvariantError(`surface replace: start seq ${start} (pos ${startIdx}) is after end seq ${end} (pos ${endIdx}) on the surface`)
-      }
-      shadowed = trace.surface.slice(startIdx, endIdx + 1)
-      surface = { kind: 'replace', start: startIdx, count: shadowed.length }
-    }
-  }
-
-  const provenanceViolation = validateSurfaceMetadata(
-    event,
-    trace.knownSeqs,
-    shadowed,
-  )
-  if (provenanceViolation !== undefined) {
-    throw new InvariantError(provenanceViolation.message)
-  }
 
   // Boundary/step-scoped events have explicit cases; every OTHER event type —
   // including plugin-added (merge-extensible) SessionEventMap keys — is caught
@@ -265,8 +204,6 @@ function validateEvent(trace: SessionTrace, event: SessionEvent): SessionTraceTr
   return {
     scalars: { lastSeq: event.seq, openTurn, openStep, nextTurn, nextStep },
     pendingCalls,
-    surface,
-    seq: event.seq,
   }
 }
 
@@ -289,20 +226,6 @@ function applyTransition(trace: SessionTrace, transition: SessionTraceTransition
     default:
       assertNever(transition.pendingCalls, 'session trace pending-call transition')
   }
-  switch (transition.surface.kind) {
-    case 'none':
-      break
-    case 'append':
-      trace.surface.push(transition.seq)
-      break
-    case 'replace':
-      trace.surface.splice(transition.surface.start, transition.surface.count, transition.seq)
-      break
-    /* v8 ignore next -- validateEvent produces this closed transition union */
-    default:
-      assertNever(transition.surface, 'session trace surface transition')
-  }
-  trace.knownSeqs.add(transition.seq)
 }
 
 /** Validate and apply one event while rebuilding an already-committed log. */
@@ -351,8 +274,6 @@ export function apply(ctx: Context): void {
     nextTurn: 1,
     nextStep: 1,
     pendingCalls: new Set(),
-    knownSeqs: new Set(),
-    surface: [],
   })
 
   /** Build (or rebuild) a session's trace by replaying its whole log. */

packages/support/invariants/tests/invariants.spec.ts

@@ -466,7 +466,7 @@ describe('HMR safety', () => {
   })
 })
 
-describe('surface invariants', () => {
+describe('surface contract under the invariants composition', () => {
   it('accepts well-formed surface metadata', async () => {
     const { ctx } = await setup()
     const session = ctx.sessions.create()
@@ -495,7 +495,7 @@ describe('surface invariants', () => {
     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)
+    }).toThrow(/must not be empty/)
   })
 
   it('rejects duplicate sourceEventSeqs', async () => {
@@ -542,15 +542,15 @@ describe('surface invariants', () => {
 
   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
+    // not in the folded log — 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.
+    // The canonical surface validator folds the committed delta before checking
+    // the next append, so it sees this gap.
     ;(session as unknown as { log: unknown[] }).log.push({
       type: 'assistant/chunk',
       seq: 3,
@@ -575,7 +575,7 @@ describe('surface invariants', () => {
     // Reversed range: start seq 3 is at a later surface position than end seq 2.
     expect(() => {
       session.append('assistant/message', { turn: 1, step: 1, content: [] }, { surfaceOp: { op: 'replace', start: 3, end: 2 }, sourceEventSeqs: [2, 3] })
-    }).toThrow(/is after end seq 2 .* on the surface/)
+    }).toThrow(/is after end seq 2/)
   })
 
   it('rejects a replace whose sourceEventSeqs omits a shadowed surface node', async () => {
@@ -612,7 +612,7 @@ describe('surface invariants', () => {
     // seq 1 (step/start) is a real earlier event but never entered the surface.
     expect(() => {
       session.append('assistant/message', { turn: 1, step: 1, content: [] }, { surfaceOp: { op: 'replace', start: 1, end: 2 }, sourceEventSeqs: [1, 2] })
-    }).toThrow(/start seq 1 is not on the surface/)
+    }).toThrow(/start seq 1 not found in surface/)
   })
 
   it('rejects a replace naming an end seq that is not on the surface', async () => {
@@ -624,7 +624,7 @@ describe('surface invariants', () => {
     // start (2) is on the surface but end (99) never entered it.
     expect(() => {
       session.append('assistant/message', { turn: 1, step: 1, content: [] }, { surfaceOp: { op: 'replace', start: 2, end: 99 }, sourceEventSeqs: [2] })
-    }).toThrow(/end seq 99 is not on the surface/)
+    }).toThrow(/end seq 99 not found in surface/)
   })
 
   it('rejects a replace whose range is reversed in surface position after a prior replace reordered it', async () => {
@@ -641,7 +641,7 @@ describe('surface invariants', () => {
     // reversed positionally (3 is at pos 1, 4 is at pos 0).
     expect(() => {
       session.append('assistant/message', { turn: 1, step: 1, content: [] }, { surfaceOp: { op: 'replace', start: 3, end: 4 }, sourceEventSeqs: [3, 4] }) // seq 5
-    }).toThrow(/is after end seq 4 .* on the surface/)
+    }).toThrow(/is after end seq 4/)
   })
 
   it('accepts a replace whose start seq exceeds its end seq when the surface position order is valid', async () => {
@@ -685,25 +685,6 @@ describe('surface invariants', () => {
     expect(() => ctx.sessions.create(undefined, { seed: badSeed })).toThrow(/must include every shadowed surface node; missing 3/)
   })
 
-  it('rejects sourceEventSeqs on a non-surface event', async () => {
-    const { ctx } = await setup()
-    const session = ctx.sessions.create()
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    // Session rejects this at its own acceptance boundary. Emit a hand-built
-    // record to cover the listener's defensive check for alternate producers.
-    const event = { type: 'turn/end', seq: 1, time: 1, data: { turn: 1, reason: { kind: 'completed' } }, sourceEventSeqs: [0] }
-    expect(() => { ctx.emit(scopeTarget(session, undefined), 'session/event', session, event as never) })
-      .toThrow(/cannot carry sourceEventSeqs/)
-  })
-
-  it('rejects surfaceOp on a non-surface event', async () => {
-    const { ctx } = await setup()
-    const session = ctx.sessions.create()
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    const event = { type: 'turn/end', seq: 1, time: 1, data: { turn: 1, reason: { kind: 'completed' } }, surfaceOp: 'append' }
-    expect(() => { ctx.emit(scopeTarget(session, undefined), 'session/event', session, event as never) })
-      .toThrow(/cannot carry surfaceOp/)
-  })
 })
 
 describe('request-reconstruction cross-check (llm/stream)', () => {