Merge branch 'master' into worktree-slash-split

scripts/migrate-packed-session-fixtures.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * Temporary branch-convergence command for canonical packed session fixtures.
+ *
+ * @see ../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md
+ */
+
+import { writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { inspectSessionFixtureLayouts } from './session-fixture-layout.ts'
+
+if (process.argv.length > 2) throw new Error('migrate:packed-session-fixtures takes no arguments')
+
+const root = resolve(import.meta.dirname, '..')
+const fixtures = inspectSessionFixtureLayouts(root)
+const changed = fixtures.filter(fixture => fixture.source !== fixture.canonical)
+for (const fixture of changed) {
+  writeFileSync(resolve(root, fixture.path), fixture.canonical)
+  console.log(fixture.path)
+}
+console.log(`packed session fixtures: ${changed.length} rewritten, ${fixtures.length} inspected`)

scripts/session-fixture-layout.snapshot.ts

@@ -0,0 +1,17 @@
+/** Repository-wide canonical-layout check for committed session fixtures. */
+
+import { resolve } from 'node:path'
+import { expect, it } from 'vitest'
+import { inspectSessionFixtureLayouts } from './session-fixture-layout.ts'
+
+const root = resolve(import.meta.dirname, '..')
+
+it('keeps every session-format JSONL fixture in canonical packed layout', () => {
+  const nonCanonical = inspectSessionFixtureLayouts(root)
+    .filter(fixture => fixture.source !== fixture.canonical)
+    .map(fixture => fixture.path)
+  expect(
+    nonCanonical,
+    'Run `pnpm run migrate:packed-session-fixtures` and commit the mechanical fixture rewrite.',
+  ).toEqual([])
+})

scripts/session-fixture-layout.spec.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest'
+import { decodeStorageRecord, type SessionEvent } from '@deepseek-ai/dsh-session'
+import { canonicalSessionFixture } from './session-fixture-layout.ts'
+
+const HEADER = '  {"type":"session","version":0,"id":"fixture","createdAt":1,"delegationDepth":0}  '
+
+function chunkRun(): SessionEvent[] {
+  return Array.from({ length: 4 }, (_, index) => ({
+    type: 'assistant/chunk',
+    seq: index,
+    time: 10 + index,
+    data: {
+      turn: 1,
+      step: 1,
+      chunk: { type: 'text-delta', index: 0, text: `part-${index}` },
+    },
+  }))
+}
+
+function unpackedFixture(): string {
+  return [HEADER, ...chunkRun().map(event => JSON.stringify(event)), ''].join('\n')
+}
+
+function decodedBody(content: string): SessionEvent[] {
+  return content.trimEnd().split('\n').slice(1)
+    .flatMap(line => decodeStorageRecord(JSON.parse(line) as unknown))
+}
+
+describe('canonicalSessionFixture', () => {
+  it('preserves the header line and packs an unpacked event run losslessly', () => {
+    const canonical = canonicalSessionFixture(unpackedFixture(), 'fixture.jsonl')
+    expect(canonical).toBeDefined()
+    expect(canonical?.split('\n')[0]).toBe(HEADER)
+    expect(JSON.parse(canonical?.split('\n')[1] ?? '{}')).toMatchObject({ type: 'text-chunks' })
+    expect(decodedBody(canonical ?? '')).toStrictEqual(chunkRun())
+  })
+
+  it('ignores JSONL whose first record is not a session header', () => {
+    expect(canonicalSessionFixture('{"type":"session_event"}\n{"value":1}\n')).toBeUndefined()
+  })
+
+  it('is idempotent for an already packed fixture', () => {
+    const packed = canonicalSessionFixture(unpackedFixture())
+    expect(packed).toBeDefined()
+    expect(canonicalSessionFixture(packed ?? '')).toBe(packed)
+  })
+
+  it('fails loud on malformed records after a session header', () => {
+    expect(() => canonicalSessionFixture(`${HEADER}\n{not-json}\n`, 'broken.jsonl'))
+      .toThrow(/broken\.jsonl:2: invalid JSON/)
+  })
+
+  it('labels malformed packed rows with the fixture path and line', () => {
+    expect(() => canonicalSessionFixture(`${HEADER}\n{"type":"text-chunks"}\n`, 'broken.jsonl'))
+      .toThrow(/broken\.jsonl:2: invalid session storage record: malformed text-chunks storage row/)
+  })
+})

scripts/session-fixture-layout.ts

@@ -0,0 +1,128 @@
+/** Canonical packed-row layout helpers for repository session fixtures. */
+
+import { deepStrictEqual } from 'node:assert'
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { decodeStorageRecord, packChunkRuns, type SessionEvent } from '@deepseek-ai/dsh-session'
+
+/** One repository session fixture and its canonical packed representation. */
+export interface SessionFixtureLayout {
+  /** Repository-relative path with `/` separators. */
+  path: string
+  /** Current fixture bytes decoded as UTF-8. */
+  source: string
+  /** Canonical packed fixture bytes. */
+  canonical: string
+}
+
+interface RecordLine {
+  line: number
+  text: string
+}
+
+function recordLines(content: string): RecordLine[] {
+  return content.split(/\r?\n/).flatMap((text, index) => (
+    text.trim().length === 0 ? [] : [{ line: index + 1, text }]
+  ))
+}
+
+function parseRecord(line: RecordLine, label: string): unknown {
+  try {
+    return JSON.parse(line.text) as unknown
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    throw new Error(`${label}:${line.line}: invalid JSON: ${detail}`, { cause: error })
+  }
+}
+
+function isSessionHeader(value: unknown): boolean {
+  return value !== null && typeof value === 'object' && (value as { type?: unknown }).type === 'session'
+}
+
+function decodeBody(lines: readonly RecordLine[], label: string): SessionEvent[] {
+  return lines.flatMap((line) => {
+    const record = parseRecord(line, label)
+    try {
+      return decodeStorageRecord(record)
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error)
+      throw new Error(`${label}:${line.line}: invalid session storage record: ${detail}`, { cause: error })
+    }
+  })
+}
+
+function renderFixture(headerLine: string, events: readonly SessionEvent[]): string {
+  return [
+    headerLine,
+    ...packChunkRuns(events).map(record => JSON.stringify(record)),
+    '',
+  ].join('\n')
+}
+
+/**
+ * Canonicalize one JSONL document when its first record is a session header.
+ * The header line remains byte-identical; body records decode to logical events
+ * and re-encode with {@link packChunkRuns}. Non-session JSONL returns undefined.
+ *
+ * @param content - JSONL source text.
+ * @param label - path-like diagnostic label.
+ * @returns Canonical text for a session fixture, otherwise undefined.
+ */
+export function canonicalSessionFixture(content: string, label = '<session-fixture>'): string | undefined {
+  const lines = recordLines(content)
+  const header = lines[0]
+  if (header === undefined) return undefined
+
+  let headerValue: unknown
+  try {
+    headerValue = JSON.parse(header.text) as unknown
+  } catch {
+    return undefined
+  }
+  if (!isSessionHeader(headerValue)) return undefined
+
+  const events = decodeBody(lines.slice(1), label)
+  const canonical = renderFixture(header.text, events)
+  const canonicalLines = recordLines(canonical)
+  const decoded = decodeBody(canonicalLines.slice(1), label)
+  try {
+    deepStrictEqual(decoded, events)
+  } catch (error) {
+    throw new Error(`${label}: packed rewrite changed the decoded event stream`, { cause: error })
+  }
+  if (renderFixture(header.text, decoded) !== canonical) {
+    throw new Error(`${label}: packed rewrite is not idempotent`)
+  }
+  return canonical
+}
+
+/**
+ * Discover tracked and unignored untracked JSONL files through Git.
+ *
+ * @param root - repository root.
+ * @returns Stable repository-relative paths.
+ */
+function discoverJsonlFiles(root: string): string[] {
+  return execFileSync(
+    'git',
+    ['ls-files', '-z', '--cached', '--others', '--exclude-standard', '--', '*.jsonl'],
+    { cwd: root, encoding: 'utf8' },
+  ).split('\0')
+    .filter(path => path.length > 0 && existsSync(resolve(root, path)))
+    .sort()
+}
+
+/**
+ * Inspect every repository JSONL whose first record is a session header.
+ *
+ * @param root - repository root.
+ * @returns Session fixtures with current and canonical text.
+ */
+export function inspectSessionFixtureLayouts(root: string): SessionFixtureLayout[] {
+  return discoverJsonlFiles(root).flatMap((path) => {
+    const source = readFileSync(resolve(root, path), 'utf8')
+    const canonical = canonicalSessionFixture(source, path)
+    return canonical === undefined ? [] : [{ path, source, canonical }]
+  })
+}