throughline 0.5.0 → 0.6.1

package/src/turn-backfill.mjs

@@ -0,0 +1,131 @@
+/**
+ * turn-backfill.mjs — transcript 全体走査による L2 回収の共通ルーチン
+ *
+ * 従来の「Stop ごとに最後の 1 ペアのみ保存」は、Stop の空振り・不発が bodies の
+ * 永久穴になった（実測欠落率 Desktop 27% / VSCode 41%、docs/12 §6）。
+ * 本ルーチンは transcript の全論理ターン群を走査し、未捕捉の完了ターンを回収する。
+ * turn-processor（毎 Stop）と session-start（マージ直後の前任回収）が共用する。
+ *
+ * 設計は docs/12 Workstream B-1（refuter 修正 1/3/4/5 適用済み）:
+ *   - 群レベル dedup: 群の**どの断片 index も** bodies に無い群だけ挿入する。
+ *     部分捕捉済み群への再挿入は「同一 user 発話の重複ペア」を量産する
+ *     （実測: 全 DB で 110 群が該当）ため、代表断片の差し替え回収はしない。
+ *   - 代表断片 = 群内最後の非 junk 断片（getLogicalTurnGroups 側で選択済み）。
+ *   - created_at は transcript エントリの timestamp。now を使うと一括回収行が
+ *     同一ミリ秒に潰れ、created_at 順ソート（handoff-record の L2 窓・現在地アンカー）
+ *     の会話順が tie で不定化するため。timestamp 欠損時のみ now。
+ *   - INSERT は 1 トランザクション（fsync 1 回、turn-processor の details と同型）。
+ */
+
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { getLogicalTurnGroups } from './transcript-reader.mjs';
+
+/**
+ * バックフィル回収実績を ~/.throughline/logs/backfill.log に 1 行 JSON で記録する。
+ * @param {object} entry
+ */
+export function logBackfill(entry) {
+  const path = join(homedir(), '.throughline', 'logs', 'backfill.log');
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, JSON.stringify(entry) + '\n', 'utf8');
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : 'unknown';
+    process.stderr.write(`[backfill-log] ${msg}\n`);
+  }
+}
+
+/**
+ * Claude Code の project-dir munging から session transcript path を決定的に導出する。
+ * macOS/Linux の Claude Code 規約を mirror する。Windows では呼び出し側が state file の
+ * transcriptPath に fallback する。
+ * @param {string} projectPath
+ * @param {string} sessionId
+ * @returns {string}
+ */
+export function deriveTranscriptPath(projectPath, sessionId) {
+  const mungedProjectPath = `-${String(projectPath).replace(/[/.]/g, '-').replace(/^-+/, '')}`;
+  return join(homedir(), '.claude', 'projects', mungedProjectPath, `${sessionId}.jsonl`);
+}
+
+/**
+ * transcript の未捕捉完了ターンを bodies へ回収する。
+ *
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @param {object} opts
+ * @param {string} opts.targetSessionId 書き込み先 session_id（merge 済みなら合流先）
+ * @param {string} opts.originSessionId transcript を所有する origin session_id
+ * @param {string|null|undefined} opts.transcriptPath
+ * @param {number} opts.now timestamp 欠損時の fallback epoch ms
+ * @returns {{groups: number, insertedTurns: number, skippedExisting: number, lastTurnNumber: number|null}}
+ */
+export function backfillBodies(db, { targetSessionId, originSessionId, transcriptPath, now }) {
+  const groups = getLogicalTurnGroups(transcriptPath);
+  if (groups.length === 0) {
+    return { groups: 0, insertedTurns: 0, skippedExisting: 0, lastTurnNumber: null };
+  }
+
+  const existing = new Set(
+    db
+      .prepare('SELECT DISTINCT turn_number FROM bodies WHERE origin_session_id = ?')
+      .all(originSessionId)
+      .map((r) => r.turn_number),
+  );
+
+  const insertBody = db.prepare(
+    `INSERT OR IGNORE INTO bodies
+       (session_id, origin_session_id, turn_number, role, text, token_count, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`,
+  );
+
+  let insertedTurns = 0;
+  let skippedExisting = 0;
+
+  db.exec('BEGIN');
+  try {
+    for (const g of groups) {
+      // 群のいずれかの断片 index が既に bodies にある = 部分捕捉済み群。
+      // 代表差し替えは重複ペアを生むので回収しない (refuter 修正1)。
+      if (g.fragments.some((f) => existing.has(f.index))) {
+        skippedExisting++;
+        continue;
+      }
+      const turnNumber = g.representative.index;
+      const assistantAt = g.representative.timestamp ?? now;
+      const userAt = g.user.timestamp ?? assistantAt;
+
+      insertBody.run(
+        targetSessionId,
+        originSessionId,
+        turnNumber,
+        'user',
+        g.user.content,
+        Math.round(g.user.content.length / 4),
+        userAt,
+      );
+      insertBody.run(
+        targetSessionId,
+        originSessionId,
+        turnNumber,
+        'assistant',
+        g.representative.content,
+        Math.round(g.representative.content.length / 4),
+        assistantAt,
+      );
+      insertedTurns++;
+    }
+    db.exec('COMMIT');
+  } catch (err) {
+    db.exec('ROLLBACK');
+    throw err;
+  }
+
+  return {
+    groups: groups.length,
+    insertedTurns,
+    skippedExisting,
+    lastTurnNumber: groups[groups.length - 1].representative.index,
+  };
+}

package/src/turn-backfill.test.mjs

@@ -0,0 +1,213 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir, homedir } from 'node:os';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { backfillBodies, deriveTranscriptPath } from './turn-backfill.mjs';
+
+function makeDb() {
+  const db = new DatabaseSync(':memory:');
+  db.exec(`
+    CREATE TABLE bodies (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT NOT NULL,
+      origin_session_id TEXT NOT NULL,
+      turn_number INTEGER NOT NULL,
+      role TEXT NOT NULL,
+      text TEXT NOT NULL,
+      token_count INTEGER,
+      created_at INTEGER NOT NULL,
+      UNIQUE(session_id, origin_session_id, turn_number, role)
+    );
+  `);
+  return db;
+}
+
+function withData(entries, fn) {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-backfill-'));
+  const path = join(dir, 'data.jsonl');
+  writeFileSync(path, entries.map((entry) => JSON.stringify(entry)).join('\n'), 'utf8');
+  try {
+    return fn(path);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function entry(role, text, timestamp, extra = {}) {
+  return {
+    type: role,
+    ...(timestamp === undefined ? {} : { timestamp }),
+    ...extra,
+    message: { role, content: [{ type: 'text', text }] },
+  };
+}
+
+test('backfillBodies: multi-fragment group uses last fragment index for both body rows', () => {
+  withData(
+    [
+      entry('user', 'question one'),
+      entry('assistant', 'first fragment'),
+      entry('assistant', 'last fragment'),
+      entry('user', 'question two'),
+      entry('assistant', 'second answer'),
+    ],
+    (path) => {
+      const db = makeDb();
+      const result = backfillBodies(db, {
+        targetSessionId: 'target', originSessionId: 'origin', transcriptPath: path, now: 999,
+      });
+      assert.deepEqual(result, { groups: 2, insertedTurns: 2, skippedExisting: 0, lastTurnNumber: 4 });
+      assert.deepEqual(
+        db.prepare('SELECT turn_number, role, text FROM bodies ORDER BY turn_number, role').all().map((row) => ({ ...row })),
+        [
+          { turn_number: 2, role: 'assistant', text: 'last fragment' },
+          { turn_number: 2, role: 'user', text: 'question one' },
+          { turn_number: 4, role: 'assistant', text: 'second answer' },
+          { turn_number: 4, role: 'user', text: 'question two' },
+        ],
+      );
+    },
+  );
+});
+
+test('backfillBodies: junk final fragment falls back and all-junk group is dropped', () => {
+  withData(
+    [
+      entry('user', 'keep this'),
+      entry('assistant', 'real answer'),
+      entry('assistant', "You've hit your session limit. Please try again later."),
+      entry('user', 'drop this'),
+      entry('assistant', 'API Error: unavailable'),
+    ],
+    (path) => {
+      const db = makeDb();
+      const result = backfillBodies(db, {
+        targetSessionId: 'target', originSessionId: 'origin', transcriptPath: path, now: 999,
+      });
+      assert.equal(result.groups, 1);
+      assert.equal(result.insertedTurns, 1);
+      assert.deepEqual(
+        db.prepare("SELECT turn_number, text FROM bodies WHERE role = 'assistant'").all().map((row) => ({ ...row })),
+        [{ turn_number: 1, text: 'real answer' }],
+      );
+    },
+  );
+});
+
+test('backfillBodies: user-only group is dropped', () => {
+  withData([entry('user', 'unanswered')], (path) => {
+    const db = makeDb();
+    assert.deepEqual(
+      backfillBodies(db, {
+        targetSessionId: 'target', originSessionId: 'origin', transcriptPath: path, now: 999,
+      }),
+      { groups: 0, insertedTurns: 0, skippedExisting: 0, lastTurnNumber: null },
+    );
+  });
+});
+
+test('backfillBodies: a single pre-seeded fragment skips its whole group while other groups insert', () => {
+  withData(
+    [
+      entry('user', 'first question'),
+      entry('assistant', 'first fragment'),
+      entry('assistant', 'last first fragment'),
+      entry('user', 'second question'),
+      entry('assistant', 'second answer'),
+    ],
+    (path) => {
+      const db = makeDb();
+      db.prepare(
+        `INSERT INTO bodies
+           (session_id, origin_session_id, turn_number, role, text, token_count, created_at)
+         VALUES ('existing-target', 'origin', 1, 'assistant', 'existing fragment', 1, 1)`,
+      ).run();
+      const result = backfillBodies(db, {
+        targetSessionId: 'target', originSessionId: 'origin', transcriptPath: path, now: 999,
+      });
+      assert.equal(result.insertedTurns, 1);
+      assert.equal(result.skippedExisting, 1);
+      assert.equal(
+        db.prepare("SELECT COUNT(*) AS count FROM bodies WHERE text = 'last first fragment'").get().count,
+        0,
+      );
+      assert.equal(
+        db.prepare("SELECT COUNT(*) AS count FROM bodies WHERE turn_number = 4").get().count,
+        2,
+      );
+    },
+  );
+});
+
+test('backfillBodies: second run is idempotent', () => {
+  withData([entry('user', 'question'), entry('assistant', 'answer')], (path) => {
+    const db = makeDb();
+    backfillBodies(db, { targetSessionId: 'target', originSessionId: 'origin', transcriptPath: path, now: 999 });
+    assert.equal(
+      backfillBodies(db, {
+        targetSessionId: 'target', originSessionId: 'origin', transcriptPath: path, now: 999,
+      }).insertedTurns,
+      0,
+    );
+  });
+});
+
+test('backfillBodies: transcript timestamps are retained and absent timestamps use now', () => {
+  withData(
+    [
+      entry('user', 'dated question', '2026-01-02T03:04:05.000Z'),
+      entry('assistant', 'dated answer', '2026-01-02T03:04:06.000Z'),
+      entry('user', 'undated question'),
+      entry('assistant', 'undated answer'),
+    ],
+    (path) => {
+      const db = makeDb();
+      backfillBodies(db, { targetSessionId: 'target', originSessionId: 'origin', transcriptPath: path, now: 777 });
+      assert.deepEqual(
+        db.prepare('SELECT turn_number, role, created_at FROM bodies ORDER BY turn_number, role').all().map((row) => ({ ...row })),
+        [
+          { turn_number: 1, role: 'assistant', created_at: Date.parse('2026-01-02T03:04:06.000Z') },
+          { turn_number: 1, role: 'user', created_at: Date.parse('2026-01-02T03:04:05.000Z') },
+          { turn_number: 3, role: 'assistant', created_at: 777 },
+          { turn_number: 3, role: 'user', created_at: 777 },
+        ],
+      );
+    },
+  );
+});
+
+test('backfillBodies: sidechain entries and missing or empty paths produce no groups', () => {
+  withData(
+    [entry('user', 'side question', undefined, { isSidechain: true }), entry('assistant', 'side answer', undefined, { isSidechain: true })],
+    (path) => {
+      const db = makeDb();
+      assert.equal(
+        backfillBodies(db, {
+          targetSessionId: 'target', originSessionId: 'origin', transcriptPath: path, now: 999,
+        }).groups,
+        0,
+      );
+      assert.deepEqual(
+        backfillBodies(db, {
+          targetSessionId: 'target', originSessionId: 'origin', transcriptPath: null, now: 999,
+        }),
+        { groups: 0, insertedTurns: 0, skippedExisting: 0, lastTurnNumber: null },
+      );
+      assert.deepEqual(
+        backfillBodies(db, {
+          targetSessionId: 'target', originSessionId: 'origin', transcriptPath: '', now: 999,
+        }),
+        { groups: 0, insertedTurns: 0, skippedExisting: 0, lastTurnNumber: null },
+      );
+    },
+  );
+});
+
+test('deriveTranscriptPath munges slash and dot characters with one leading dash', () => {
+  assert.equal(
+    deriveTranscriptPath('/Users/example/Developer/Through.line', 'session-id'),
+    join(homedir(), '.claude', 'projects', '-Users-example-Developer-Through-line', 'session-id.jsonl'),
+  );
+});

package/src/turn-processor.mjs

@@ -8,8 +8,9 @@
  *      （Haiku 要約用の claude -p subprocess 内で自分自身の Stop hook として起動された場合）
  *   1. resolveMergeTarget で「実書き込み先 (target) / origin」を解決
  *      （input session が別セッションに合流済みなら合流先に書く）
- *   2. 最後の assistant ターン + 直前の user ターンのペアを取得
- *   3. L2 本文 (bodies) に user / assistant の 2 行を INSERT
+ *   2. transcript 全体を論理ターン群で走査し、未捕捉の完了ターンを bodies へ
+ *      一括回収する (turn-backfill.mjs、docs/12 B-1)。回収実績は backfill.log に記録
+ *   3. （旧: 最後の 1 ペアのみ保存 — Stop 空振りで永久穴が生じたため全走査化）
  *   4. 【遅延要約】target 配下の bodies ターン数 (distinct origin×turn) が
  *      WINDOW (=20) を超えていたら、最古の未要約ターンを 1 件だけ
  *      Haiku 4.5 で要約 → skeletons (L1) に INSERT。
@@ -31,11 +32,11 @@
 
 import { getDb } from './db.mjs';
 import {
-  getLastTurnPair,
   readRawEntries,
   sliceCurrentTurnEntries,
   extractDetailBlocks,
 } from './transcript-reader.mjs';
+import { backfillBodies, logBackfill } from './turn-backfill.mjs';
 import { resolveMergeTarget } from './session-merger.mjs';
 import { writeSessionState } from './state-file.mjs';
 import { summarizeToL1 } from './haiku-summarizer.mjs';
@@ -160,46 +161,33 @@ export async function run() {
     db.prepare('UPDATE sessions SET updated_at = ? WHERE session_id = ?').run(now, target);
   }
 
-  // 最後の assistant ターン + 直前の user ターンを取得
-  const { user: userTurn, assistant: assistantTurn } = getLastTurnPair(transcript_path);
-  if (!assistantTurn) {
-    // /clear 直後などでトランスクリプトが空の場合は何もしない
+  // L2 = transcript 全体を論理ターン群で走査し、未捕捉の完了ターンを一括回収する。
+  // 従来の「最後の 1 ペアのみ保存」は Stop の空振り・不発が永久穴になった (docs/12 B-1)。
+  // user / assistant は「1 往復 = 1 ターン」として同じ turn_number（= 代表 assistant
+  // 断片の index）でペアリングされ、bodies と skeletons が同じ turn_number で突合できる。
+  const backfill = backfillBodies(db, {
+    targetSessionId: target,
+    originSessionId: origin,
+    transcriptPath: transcript_path,
+    now,
+  });
+  logBackfill({
+    ts: new Date(now).toISOString(),
+    hook: 'stop',
+    session_id,
+    target,
+    origin,
+    transcript_path: transcript_path ?? null,
+    groups: backfill.groups,
+    inserted_turns: backfill.insertedTurns,
+    skipped_existing: backfill.skippedExisting,
+  });
+  if (backfill.lastTurnNumber === null) {
+    // /clear 直後などでトランスクリプトに完了ターンが無い場合は何もしない
     process.exit(0);
   }
 
-  const turnNumber = assistantTurn.turn_number;
-
-  // L2 = bodies に user / assistant を個別行で保存
-  const insertBody = db.prepare(
-    `INSERT OR IGNORE INTO bodies
-       (session_id, origin_session_id, turn_number, role, text, token_count, created_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?)`,
-  );
-  // user / assistant を「1 往復 = 1 ターン」として扱うため、同じ turn_number
-  // （= assistant 側の turn_number）でペアリングして保存する。
-  // これにより bodies と skeletons が同じ turn_number で突合できる。
-  if (userTurn?.content) {
-    insertBody.run(
-      target,
-      origin,
-      turnNumber,
-      'user',
-      userTurn.content,
-      Math.round(userTurn.content.length / 4),
-      now,
-    );
-  }
-  if (assistantTurn?.content) {
-    insertBody.run(
-      target,
-      origin,
-      turnNumber,
-      'assistant',
-      assistantTurn.content,
-      Math.round(assistantTurn.content.length / 4),
-      now,
-    );
-  }
+  const turnNumber = backfill.lastTurnNumber;
 
   // L1 = 遅延要約。target 配下の bodies ターン数 (distinct origin×turn) が
   // WINDOW を超えていたら、最古の未要約ターンを 1 件だけ要約する。