Merge remote-tracking branch 'origin/master' into worktree/semantic-session-checkpoints

# Conflicts: # docs/event-producer-consumer.md # docs/module-graph.md # examples/tui-agent/tests/tui-keyless-smoke.e2e.ts # packages/examples/acp-demo/package.json # packages/examples/cli-demo/tsconfig.json # packages/support/invariants/src/index.ts # packages/support/invariants/tests/invariants.spec.ts # pnpm-lock.yaml
2026-07-21 20:09:37 +08:00
parent 380a94febb 8672fa881a
commit 8ce5989ffb
634 changed files with 21549 additions and 3328 deletions
@@ -11,17 +11,23 @@
      "types": "./lib/types/index.d.ts",
      "default": "./lib/index.js"
    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
    "./src/*": "./src/*",
    "./package.json": "./package.json"
  },
  "files": [
    "lib/index.js",
+    "lib/invariant.js",
    "lib/types/**/*.d.ts",
    "lib/types/**/*.d.ts.map",
    "src"
  ],
  "license": "BSD-3-Clause",
  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
    "@deepseek-ai/dsh-session": "^0.0.1",
    "@deepseek-ai/dsh-session-persistence": "^0.0.1",
    "cordis": "^4.0.0-rc.7"
@@ -30,6 +36,7 @@
    "schemastery": "^3.18.0"
  },
  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
    "@deepseek-ai/dsh-session-persistence": "workspace:^",
    "cordis": "^4.0.0-rc.7"
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-session-persistence-jsonl`.
+ * @module @deepseek-ai/dsh-session-persistence-jsonl/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-session-persistence-jsonl'
+
+/** Cordis companion plugin name. */
+export const name = 'session-persistence-jsonl-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: persistence correctness requires backend round-trip and crash-tail tests;
+ * this package exposes no continuously observable in-process relation.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
@@ -21,17 +21,15 @@ function mutableHeader(header: SessionHeader): MutableSessionHeader {
  return header
 }

-async function expectParallelFlushError(promise: Promise<unknown>, message: RegExp): Promise<void> {
+async function expectFlushError(promise: Promise<unknown>, message: RegExp): Promise<void> {
  try {
    await promise
  } catch (error) {
-    expect(error).toBeInstanceOf(AggregateError)
-    const [cause] = (error as AggregateError).errors as unknown[]
-    expect(cause).toBeInstanceOf(Error)
-    expect((cause as Error).message).toMatch(message)
+    expect(error).toBeInstanceOf(Error)
+    expect((error as Error).message).toMatch(message)
    return
  }
-  throw new Error('expected parallel flush to reject')
+  throw new Error('expected flush to reject')
 }

 async function freshRoot(): Promise<string> {
@@ -257,7 +255,7 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => {
    appendClosedTurn(source)

    const child = ctx.sessions.fork(source, undefined, SessionId('persist-child'))
-    await ctx.parallel('session/flush', child)
+    await ctx.sessions.flush(child)
    const loaded = await ctx.sessionPersistence.load(child.id)

    expect(loaded.events).toEqual(source.events)
@@ -436,12 +434,14 @@ describe('SessionPersistenceJsonl: write path (session/event → flush)', () =>

    const a = ctx.sessions.create(SessionId('sa'))
    const b = ctx.sessions.create(SessionId('sb'))
+    a.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    b.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    a.append('user/message', { content: [{ type: 'text', text: 'A' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
    b.append('user/message', { content: [{ type: 'text', text: 'B' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
    a.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
    b.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-    await ctx.parallel('session/flush', a)
-    await ctx.parallel('session/flush', b)
+    await ctx.sessions.flush(a)
+    await ctx.sessions.flush(b)

    const la = await ctx.sessionPersistence.load(SessionId('sa'))
    const lb = await ctx.sessionPersistence.load(SessionId('sb'))
@@ -635,7 +635,7 @@ describe('SessionPersistenceJsonl: edge cases', () => {
    }, { inject: ['sessions'] }))
    // Drain A, then dispose ITS fiber (the live session A is gone) while the
    // backend stays loaded.
-    for (const s of ctx.sessions.list()) await ctx.parallel('session/flush', s)
+    for (const s of ctx.sessions.list()) await ctx.sessions.flush(s)
    await sessFiberA.dispose()

    // A new Session object reuses the id. Object-keyed initialization must run independently,
@@ -703,7 +703,7 @@ describe('SessionPersistenceJsonl: edge cases', () => {
      a.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
      a.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
    }, { inject: ['sessions'] }))
-    for (const s of ctx.sessions.list()) await ctx.parallel('session/flush', s)
+    for (const s of ctx.sessions.list()) await ctx.sessions.flush(s)
    await firstFiber.dispose()

    let second!: Session
@@ -814,18 +814,19 @@ describe('SessionPersistenceJsonl: edge cases', () => {
    await ctx2.plugin(SessionPersistenceJsonl, { root, compression: 'none' })
    const session = ctx2.sessions.create(SessionId('flush-fail'))
    // A full turn lands in the write-behind buffer.
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
    // Make the durable materialize fail on the next flush.
    const backend = ctx2.sessionPersistence as unknown as { materialize: (...args: unknown[]) => Promise<void> }
    const origMat = backend.materialize.bind(backend)
    backend.materialize = () => Promise.reject(new Error('disk full'))
-    await expectParallelFlushError(ctx2.parallel('session/flush', session), /disk full/)
+    await expectFlushError(ctx2.sessions.flush(session), /disk full/)
    // The events are STILL buffered (not silently dropped): a retry persists them.
    backend.materialize = origMat
-    await ctx2.parallel('session/flush', session)
+    await ctx2.sessions.flush(session)
    const loaded = await ctx2.sessionPersistence.load(SessionId('flush-fail'))
-    expect(loaded.events.map(e => e.seq)).toEqual([0, 1])
+    expect(loaded.events.map(e => e.seq)).toEqual([0, 1, 2])
    await ctx2.fiber.dispose()
  })

@@ -22,6 +22,9 @@
    },
    {
      "path": "../../session-persistence/session-persistence"
+    },
+    {
+      "path": "../../support/invariants"
    }
  ]
 }