docs: trim generated prose

packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts

@@ -48,11 +48,6 @@ runPersistenceContract('jsonl', async () => {
 })
 
 // Run the shared coordinator orchestration suite against the real JSONL backend.
-// One temp root is the shared storage scope (two mounted instances over the same
-// root = HMR/reload). `corruptTail` appends a partial, newline-less fragment to
-// the session's .jsonl past the committed region — a never-committed torn tail
-// that drives the coordinator's commitRepair-with-tornMarker branch over real
-// file bytes.
 runCoordinatorContract('jsonl', async (): Promise<CoordinatorFixture> => {
   const dir = await mkdtemp(join(tmpdir(), 'dsh-jsonl-coord-'))
   return {
@@ -340,10 +335,9 @@ describe('SessionPersistenceJsonl: scanLog unit', () => {
       JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }),
       JSON.stringify({ type: 'step/start', seq: 2, time: 2, data: { turn: 1, step: 1 } }), // gap: missing seq 1
     ].join('\n') + '\n'
-    // No committed turn/end, so the gap is a tolerated crash boundary: scanLog
-    // PRESERVES the contiguous prefix (turn/start seq 0) — real interrupted-turn
-    // work, not discarded — and stops at the gap. The orphaned open turn is
-    // closed by loadCore's synthetic turn/end, not here.
+    // No committed turn/end, so the gap is a tolerated crash boundary: scanLog PRESERVES the
+    // contiguous prefix (turn/start seq 0) — real interrupted-turn work, not discarded — and
+    // stops at the gap.
     expect(scanLog(Buffer.from(log)).events.map(e => e.seq)).toEqual([0])
   })
 
@@ -463,9 +457,7 @@ describe('SessionPersistenceJsonl: edge cases', () => {
   })
 
   it('list reads a header line longer than the 8KB read chunk', async () => {
-    // readFirstLine accumulates across reads when the first line exceeds its
-    // buffer. Plant a valid header whose line is > 8192 bytes (a long extra
-    // field is tolerated by the header type guard) and confirm list() reads it.
+    // readFirstLine accumulates across reads when the first line exceeds its buffer.
     const bucket = join(root, '_no-cwd')
     await mkdir(bucket, { recursive: true })
     const bigHeader = JSON.stringify({ type: 'session', version: 0, id: 'big', createdAt: 1, pad: 'x'.repeat(9000) })
@@ -485,10 +477,7 @@ describe('SessionPersistenceJsonl: edge cases', () => {
     for (const s of ctx.sessions.list()) await ctx.parallel('session/flush', s)
     await sessFiberA.dispose()
 
-    // A NEW live Session object reuses id "reuse". The init cache is keyed by
-    // the Session OBJECT, so this gets its OWN onCreated (not A's stale promise)
-    // — which detects the on-disk collision and rejects, rather than silently
-    // appending the new session's events onto A's log under a stale cursor.
+    // A NEW live Session object reuses id "reuse".
     const backend = ctx.sessionPersistence as unknown as { inits: Map<Session, Promise<void>> }
     let b!: Session
     await ctx.plugin(Object.assign((inner: Context) => {
@@ -506,13 +495,7 @@ describe('SessionPersistenceJsonl: edge cases', () => {
     await ctx.sessionPersistence.append(SessionId('x'), oneTurnLog())
     await ctx.fiber.dispose()
 
-    // Backend 2 over the SAME root. A live no-cwd session reuses id "x". Because
-    // loadLive(id, undefined) is the DEFINITE no-cwd bucket (NOT an all-buckets
-    // scan), case-2 adoption does NOT match the "/w" log — so it would NOT
-    // silently graft the no-cwd events onto the "/w" log with a mismatched cwd
-    // (the bug a non-scope-exact loadLive caused). It falls through to the
-    // new-session path, where createCore's any-cwd collision probe (loadStored)
-    // catches the duplicate id and REJECTS — the id is taken in another bucket.
+    // Backend 2 over the same root.
     const ctx2 = new Context()
     await ctx2.plugin(SessionStore)
     await ctx2.plugin(SessionPersistenceJsonl, { root })
@@ -580,9 +563,7 @@ describe('SessionPersistenceJsonl: edge cases', () => {
   })
 
   it('list surfaces a non-ENOENT root error (ENOTDIR) instead of reporting no sessions', async () => {
-    // A durable backend must NOT collapse a storage fault to "no sessions". Point
-    // the root at a regular FILE: readdir then fails with ENOTDIR, which must
-    // propagate rather than be swallowed as an empty listing.
+    // A durable backend must not collapse a storage fault to "no sessions".
     const filePath = join(root, 'not-a-dir')
     await writeFile(filePath, 'x')
     const ctx2 = new Context()
@@ -593,11 +574,8 @@ describe('SessionPersistenceJsonl: edge cases', () => {
   })
 
   it('loadLive surfaces a non-ENOENT lookup error (ENOTDIR) instead of reporting absent', async () => {
-    // A non-ENOENT error from the per-id open() must surface, not be collapsed to
-    // "not found" (which would let live-adoption proceed under a false absence
-    // assumption). A live session's onCreated reaches loadLive(id, cwd) →
-    // exists(logPath). Make that cwd's bucket DIRECTORY a regular file: open()ing
-    // `bucket/<id>.jsonl` under it then fails ENOTDIR.
+    // A non-ENOENT error from the per-id open() must surface, not be collapsed to "not found"
+    // (which would let live-adoption proceed under a false absence assumption).
     const cwd = '/x'
     const ctx2 = new Context()
     await ctx2.plugin(SessionStore)
@@ -716,10 +694,9 @@ describe('SessionPersistenceJsonl: edge cases', () => {
 
   it('Session.append rejects a non-serializable event at the source (never enters the log)', () => {
     const session = ctx.sessions.create(SessionId('reject-bad'))
-    // Serializability is enforced at the source: Session.append throws on a
-    // BigInt-bearing event BEFORE it enters session.events, so the durable log
-    // can never diverge from the live log. The throw surfaces at the caller's
-    // append site, not asynchronously in a backend flush.
+    // Serializability is enforced at the source: Session.append throws on a BigInt-bearing
+    // event before it enters session.events, so the durable log can never diverge from the live
+    // log.
     expect(() => {
       session.append('user/message', { content: [{ type: 'text', text: 'bad' }], source: { kind: 'user' }, bad: 1n } as never, { surfaceOp: 'append' })
     }).toThrow(/non-JSON-serializable/)